-.TH MH-MAIL %manext5% "March 3, 2013" "%nmhversion%"
+.TH MH-FOLDERS %manext5% "February 25, 2016" "%nmhversion%"
.\"
.\" %nmhwarning%
.\"
.B nmh
folder corresponds to directory. There are no limits on folder
names beyond those of the host filesystem.
-.I Is that right?
.RE
.PP
.B one message per file
.RS 5
-The file name is a positive integer. The filename for a new
+The file name is a positive integer. Other files containing metadata or
+arbitrary names can exist in a folder; while the preference is that non\-message
+files begin with \*(lq.\*(rq, all files that are not positive integers
+.B must
+be ignored by a
+.BR MH \-compatible
+implementation. However, implementations are free to indicate to the user
+the existence of non\-message files that are not prefixed with a \*(lq.\*(rq.
+.PP
+The filename for a new
message is one greater than the highest numbered message in
-the folder; its full path can be shown by
-.B mh-path
-.IR new .
+the folder; its full path can be accessed by the pseudo\-sequence
+.I new
+(e.g.,
+.B mhpath
+.IR new ).
+New messages are
+.B only
+permitted to be added to a folder at the end of the message number range.
+.PP
+To add a new message to a folder, the recommended sequence is:
+.PP
+.IP \(bu 4
+Create a temporary file in the desired folder.
+.IP \(bu 4
+Attempt to link the temporary file to the new message number.
+.IP \(bu 4
+If successful, remove the temporary file. If the link fails, increment the
+message number and try again.
.PP
.RE
.B context
.B sequences
.RS 5
There is one sequences file in each
-.B .nmh
+.B nmh
folder. Its default name is
.IR \&.mh\(rusequences ,
but that can be overridden with the \*(lqmh\-sequences\*(rq profile entry.
.BI "sequence: " "m[-n] [...]"
.RE
.PP
-showing the message numbers and/or ranges of message numbers in
-each sequence.
+showing the (possibly empty) message numbers and/or ranges of message
+numbers in each sequence. The
+.B cur
+sequence has at most just a single message number, not a range.
+.PP
+Sequence names have a maximum size of 998 characters. Each line is also
+limited to a maximum of 998 characters, but RFC 822 continuation rules
+apply; sequences can be continued across multiple lines by prefixing
+continuation lines with a whitespace character.
+.PP
+If an implementation finds messages in a sequence that do not exist,
+the sequence file should be updated to remove the missing messages
+from the sequence. If a sequence contains no messages, it should be
+removed from the sequence file. The exception to this is the
+.B cur
+sequence, which can refer to a nonexistent message.
.RE
.PP
.SS Locking
.B nmh
programs read and write the context and sequences files, and lock
-these files when accessing them. Any program outside of
+these files when accessing them. There should not be a need to
+access these files directly; instead, programs such as
+.BR flist ,
+.BR folder ,
+.BR mark ,
+.BR pick ,
+and
+.B rcvstore
+should be used to query and update their contents. Any program
+outside of
.B nmh
that accesses these files must be sure to lock them using the same
-locking method. The locking method is selected when
+locking method as
+.BR nmh .
+The default data locking method is selected when
+.B nmh
+is configured and can be accessed as a string using
+.BR "mhparam datalocking" .
+By default, fcntl locking is used, but this may be overridden with
+the
+.B datalocking
+profile entry.
+.PP
+A second, possibly different, locking method is used by
+.BR inc (1)
+when accessing the user's mail spool file or by
+.B nmh
+programs that open any mbox file. This locking method can be overridden
+when
.B nmh
-is configured. By default, kernel-level locking is used if
-appropriate for the platform, and it is for popular platforms. That
-default should also be the same as used by the
+is configured, or in the
+.B nmh
+mts configuration file, and can be accessed as a string using
+.BR "mhparam spoollocking" .
+By default, kernel-level locking is used if appropriate for the
+platform, and it is for popular platforms. That default should also
+be the same as used by the
.B mail
program, if provided on the platform.
-.I Should we add a lockmethod component to mhparam so users can easily detect it?
+.PP
+.SS Naming
+.B nmh
+folders can be given arbitrary names, with one exception:
+folders should not be given all-numeric names. This
+limitation results from
+.B nmh
+messages themselves being stored
+in numerically named files -- allowing folders to be named
+similarly would make
+.B nmh
+slower, and introduce usage ambiguities.
.SH FILES
-.fc ^ ~
-.nf
-.ta \w'%etcdir%/ExtraBigFileName 'u
-^<mh\-dir>/context~^The user context
-^or $MHCONTEXT~^Rather than the standard context
-^<folder>/\&.mh\(rusequences~^Public sequences for <folder>
-.fi
+.PD 0
+.TP 20
+<mh\-dir>/context
+The user's context.
+.TP 20
+$MHCONTEXT
+Overrides the above context.
+.TP 20
+<folder>/\&.mh\-sequences
+Public sequences for <folder>.
.SH "SEE ALSO"
.I
+.IR flist (1),
+.IR folder (1),
.IR mail (1),
-.IR mh\-path (1),
+.IR mark (1),
+.IR mhparam (1),
+.IR mhpath (1),
.IR mh\-profile (5),
-.IR mh\-sequence (5)
+.IR mh\-sequence (5),
+.IR mh\-tailor (5),
+.IR pick (1),
+.IR rcvstore (1)
projects / nmh / blobdiff