X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/2deac42fba728951115da3e5995997ea6e2db019..07661005b9a36338ab158bcbe7762788a1df4030:/man/mh-folders.man?ds=sidebyside

diff --git a/man/mh-folders.man b/man/mh-folders.man
index 6397dffa..4b560e47 100644
--- 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%
 .\"
@@ -15,16 +15,39 @@ A
 .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
@@ -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 .nmh
+.B nmh
 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.
+.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
-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 locking method is selected 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 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.
-.I Should we add a lockmethod component to mhparam so users can easily detect it?
 .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
+.IR flist (1),
+.IR folder (1),
 .IR mail (1),
+.IR mark (1),
+.IR mh\-param (1),
 .IR mh\-path (1),
 .IR mh\-profile (5),
-.IR mh\-sequence (5)
+.IR mh\-sequence (5),
+.IR pick (1),
+.IR rcvstore (1)