Added note that suffixes were removed from filenames of temporary files.

[nmh] / man / mh-folders.man

diff --git a/man/mh-folders.man b/man/mh-folders.man
index 6397dffa0dd8b4b88f7216f5dade18d2c7d5d605..4b560e473c2f9adbf0ff57f3c897fc16002e810e 100644 (file)
--- a/man/mh-folders.man
+++ b/man/mh-folders.man
@@ -1,4 +1,4 @@
-.TH MH-MAIL %manext5% "March 3, 2013" "%nmhversion%"
+.TH MH-MAIL %manext5% "March 7, 2013" "%nmhversion%"

 .\"
 .\" %nmhwarning%
 .\"
 .\"
 .\" %nmhwarning%
 .\"


@@ -15,16 +15,39 @@ A
 .B nmh
 folder corresponds to directory.  There are no limits on folder
 names beyond those of the host filesystem.
 .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
 .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
 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
 .PP
 .RE
 .B context


@@ -59,7 +82,7 @@ is a message number or range of message numbers in the sequence.
 .B sequences
 .RS 5
 There is one sequences file in each
 .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.
 folder.  Its default name is
 .IR \&.mh\(rusequences ,
 but that can be overridden with the \*(lqmh\-sequences\*(rq profile entry.


@@ -74,33 +97,63 @@ 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.
 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 nonexistant message.

 .RE
 .PP
 .SS Locking
 .B nmh
 programs read and write the context and sequences files, and lock
 .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
 .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 locking method is selected when

 .B nmh
 .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 and can be accessed as a string using
+.BR "mhparam lockmethod" .
+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.
 .B mail
 program, if provided on the platform.

-.I Should we add a lockmethod component to mhparam so users can easily detect it?

 .SH FILES
 .fc ^ ~
 .nf
 .SH FILES
 .fc ^ ~
 .nf

-.ta \w'%etcdir%/ExtraBigFileName  'u
+.ta \w'^<folder>/\&.mh\(rusequences~'u

 ^<mh\-dir>/context~^The user context
 ^or $MHCONTEXT~^Rather than the standard context
 ^<folder>/\&.mh\(rusequences~^Public sequences for <folder>
 .fi
 .SH "SEE ALSO"
 .I
 ^<mh\-dir>/context~^The user context
 ^or $MHCONTEXT~^Rather than the standard context
 ^<folder>/\&.mh\(rusequences~^Public sequences for <folder>
 .fi
 .SH "SEE ALSO"
 .I

+.IR flist (1),
+.IR folder (1),

 .IR mail (1),
 .IR mail (1),

+.IR mark (1),
+.IR mh\-param (1),

 .IR mh\-path (1),
 .IR mh\-profile (5),
 .IR mh\-path (1),
 .IR mh\-profile (5),

-.IR mh\-sequence (5)
+.IR mh\-sequence (5),
+.IR pick (1),
+.IR rcvstore (1)