lock_file.c: close(2) file descriptor on failure, avoiding leak.

[nmh] / man / mh-folders.man

diff --git a/man/mh-folders.man b/man/mh-folders.man
index 0fbdddd067ab471088483ed46211750f0658b958..a3ed3f0989be1edc423006ba83e923edef37f673 100644 (file)
--- a/man/mh-folders.man
+++ b/man/mh-folders.man
@@ -1,9 +1,9 @@
-.TH MH-FOLDERS %manext5% "July 22, 2014" "%nmhversion%"
-.\"
+.TH MH-FOLDERS %manext5% 2016-02-25 "%nmhversion%"
+.
 .\" %nmhwarning%
-.\"
+.
 .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
@@ -11,36 +11,34 @@ according to the following rules:
 .PP
 .B one folder per directory
 .RS 5
-A
+An
 .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
-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
-.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
-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
-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
-.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:
-.PP
 .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.
-.PP
 .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 ,
-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
@@ -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
-.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
@@ -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
-sequence, which can refer to a nonexistant message.
+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
@@ -132,13 +127,13 @@ 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
+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
-.BR inc (1)
+.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
@@ -153,16 +148,29 @@ 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
-.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"
-.I
 .IR flist (1),
 .IR folder (1),
 .IR mail (1),