X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/67506f8a343d03fae9f5a98e89cbd431426347cc..63621a81d16ab743de6b57d47578a9a2c670ad22:/man/mh-folders.man diff --git a/man/mh-folders.man b/man/mh-folders.man index 0fbdddd0..a3ed3f09 100644 --- 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'^/\&.mh\(rusequences~'u -^/context~^The user context -^or $MHCONTEXT~^Rather than the standard context -^/\&.mh\(rusequences~^Public sequences for -.fi +.PD 0 +.TP 20 +/context +The user's context. +.TP 20 +$MHCONTEXT +Overrides the above context. +.TP 20 +/.mh\-sequences +Public sequences for . .SH "SEE ALSO" -.I .IR flist (1), .IR folder (1), .IR mail (1),