new.c: Order two return statements to match comment.

[nmh] / man / mh-folders.man

diff --git a/man/mh-folders.man b/man/mh-folders.man
index e6b1d442b3804a9e46e197f45292c76e238bc1a4..a3ed3f0989be1edc423006ba83e923edef37f673 100644 (file)
--- a/man/mh-folders.man
+++ b/man/mh-folders.man
@@ -1,9 +1,9 @@
-.TH MH-MAIL %manext5% "March 7, 2013" "%nmhversion%"
-.\"
+.TH MH-FOLDERS %manext5% 2016-02-25 "%nmhversion%"
+.

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

-.\"
+.

 .SH NAME
 .SH NAME

-mh-folders \- specification of storage format used by nmh message system
+mh-folders \- storage format used by nmh message system

 .SH DESCRIPTION
 .B nmh
 stores messages in the files and directories of the host filesystem
 .SH DESCRIPTION
 .B nmh
 stores messages in the files and directories of the host filesystem


@@ -11,36 +11,34 @@ according to the following rules:
 .PP
 .B one folder per directory
 .RS 5
 .PP
 .B one folder per directory
 .RS 5

-A
+An

 .B nmh
 .B nmh

-folder corresponds to directory.  There are no limits on folder
+folder corresponds to a directory.  There are no limits on folder

 names beyond those of the host filesystem.
 .RE
 .PP
 .B one message per file
 .RS 5
 The file name is a positive integer.  Other files containing metadata or
 names beyond those of the host filesystem.
 .RE
 .PP
 .B one message per file
 .RS 5
 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
+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
 files begin with \*(lq.\*(rq, all files that are not positive integers

-.B must
-be ignored by a
+.I must
+be ignored by an

 .BR MH \-compatible
 implementation.  However, implementations are free to indicate to the user
 .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.
+the existence of non-message files that are not prefixed with a \*(lq.\*(rq.

 .PP
 .PP

-The filename for a new
-message is one greater than the highest numbered message in
-the folder; its full path can be accessed by the pseudo\-sequence
+The filename for a new message is one greater than the highest numbered
+message in the folder; its full path can be accessed by the pseudo-sequence

 .I new
 (e.g.,
 .B mhpath
 .IR new ).
 New messages are
 .I new
 (e.g.,
 .B mhpath
 .IR new ).
 New messages are

-.B only
+.I 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:
 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
 .IP \(bu 4
 Create a temporary file in the desired folder.
 .IP \(bu 4


@@ -48,15 +46,13 @@ 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.
 .IP \(bu 4
 If successful, remove the temporary file.  If the link fails, increment the
 message number and try again.

-.PP

 .RE
 .B context
 .RS 5
 There is one context file.  Its default location is in the
 .RE
 .B context
 .RS 5
 There is one context file.  Its default location is in the

-user's Path and default name is
+user's Path and its default name is

 .IR context ,
 .IR context ,

-but those can be overridden with the $MHCONTEXT environment
-variable.
+but these can be overridden by the $MHCONTEXT environment variable.

 .B context
 has the following format:
 .PP
 .B context
 has the following format:
 .PP


@@ -84,8 +80,8 @@ is a message number or range of message numbers in the sequence.
 There is one sequences file in each
 .B nmh
 folder.  Its default name is
 There is one sequences file in each
 .B nmh
 folder.  Its default name is

-.IR \&.mh\(rusequences ,
-but that can be overridden with the \*(lqmh\-sequences\*(rq profile entry.
+.IR \&.mh_sequences ,
+but this can be overridden by the \*(lqmh\-sequences\*(rq profile entry.

 .B sequences
 has the following format:
 .PP
 .B sequences
 has the following format:
 .PP


@@ -99,7 +95,7 @@ numbers in each sequence.  The
 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
 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
+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
 apply; sequences can be continued across multiple lines by prefixing
 continuation lines with a whitespace character.
 .PP


@@ -108,9 +104,8 @@ 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
 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.
+sequence, which can refer to a nonexistent message.

 .RE
 .RE

-.PP

 .SS Locking
 .B nmh
 programs read and write the context and sequences files, and lock
 .SS Locking
 .B nmh
 programs read and write the context and sequences files, and lock


@@ -128,32 +123,62 @@ outside of
 that accesses these files must be sure to lock them using the same
 locking method as
 .BR nmh .
 that accesses these files must be sure to lock them using the same
 locking method as
 .BR nmh .

-The locking method is selected when
+The default data locking method is selected when

 .B nmh
 is configured and can be accessed as a string using
 .B nmh
 is configured and can be accessed as a string using

-.BR "mhparam lockmethod" .
+.BR "mhparam datalocking" .
+By default, fcntl locking is used, but this may be overridden by
+the
+.B datalocking
+profile entry.
+.PP
+A second, possibly different, locking method is used by
+.IR 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, 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.
 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.

+.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
 .SH FILES

-.fc ^ ~
-.nf
-.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
+.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"
 .SH "SEE ALSO"

-.I

 .IR flist (1),
 .IR folder (1),
 .IR mail (1),
 .IR mark (1),
 .IR flist (1),
 .IR folder (1),
 .IR mail (1),
 .IR mark (1),

-.IR mh\-param (1),
-.IR mh\-path (1),
+.IR mhparam (1),
+.IR mhpath (1),

 .IR mh\-profile (5),
 .IR mh\-sequence (5),
 .IR mh\-profile (5),
 .IR mh\-sequence (5),

+.IR mh\-tailor (5),

 .IR pick (1),
 .IR rcvstore (1)
 .IR pick (1),
 .IR rcvstore (1)