crawl_folders.h: Rename to be alongside implementation.

[nmh] / man / mhpath.man

diff --git a/man/mhpath.man b/man/mhpath.man
index 5f1a15f1eea14403e09afa25889cfce3f95e06cf..b867485783254f11406a011c818e9212dcdd128d 100644 (file)
--- a/man/mhpath.man
+++ b/man/mhpath.man
@@ -1,136 +1,166 @@
-.\"
+.TH MHPATH %manext1% 2012-02-18 "%nmhversion%"
+.

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

-.\" $Id$
-.\"
-.\" include the -mh macro file
-.so %etcdir%/tmac.h
-.\"
-.TH MHPATH %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
+.

 .SH NAME
 mhpath \- print full pathnames of nmh messages and folders
 .SH SYNOPSIS
 .SH NAME
 mhpath \- print full pathnames of nmh messages and folders
 .SH SYNOPSIS

-.in +.5i
-.ti -.5i
-mhpath
-\%[+folder] \%[msgs]
-\%[\-version]
-\%[\-help]
-.in -.5i
+.HP 5
+.na
+.B mhpath
+.RB [ \-help ]
+.RB [ \-version ]
+.RI [ +folder ]
+.RI [ msgs ]
+.ad

 .SH DESCRIPTION
 .SH DESCRIPTION

-\fIMhpath\fR expands and sorts the message list `msgs' and writes the full
-pathnames of the messages to the standard output separated by newlines.
-If no `msgs' are specified, \fImhpath\fR outputs the folder pathname
-instead.  If the only argument is `+', your nmh \fIPath\fR is output;
-this can be useful is shell scripts.
-
-Contrasted with other nmh commands, a message argument to \fImhpath\fR
-may often be intended for \fIwriting\fR.  Because of this:
-.sp
-1) the name \*(lqnew\*(rq has been added to \fImhpath\fR's list of
-reserved message names (the others are \*(lqfirst\*(rq, \*(lqlast\*(rq,
-\*(lqprev\*(rq, \*(lqnext\*(rq, \*(lqcur\*(rq, and \*(lqall\*(rq).
+.B mhpath
+expands and sorts the message list `msgs' and writes the full
+pathnames of the messages to the standard output, separated by newlines.
+If no `msgs' are specified,
+.B mhpath
+outputs the current mail folder's pathname instead.
+If the only argument is `+', your
+.B nmh
+\*(lqPath\*(rq is output; this can be useful in shell scripts.
+.PP
+In contrast with other
+.B nmh
+commands, a message argument to
+.B mhpath
+may often be intended for writing.  Because of this:
+.IP 1) 4
+the name \*(lqnew\*(rq has been added to
+.BR mhpath 's
+list of reserved message names (the others are \*(lqfirst\*(rq,
+\*(lqlast\*(rq, \*(lqprev\*(rq, \*(lqnext\*(rq, \*(lqcur\*(rq,
+and \*(lqall\*(rq).

 The new message is equivalent to the message after the last message
 in a folder (and equivalent to 1 in a folder without messages).
 The \*(lqnew\*(rq message may not be used as part of a message range.
 The new message is equivalent to the message after the last message
 in a folder (and equivalent to 1 in a folder without messages).
 The \*(lqnew\*(rq message may not be used as part of a message range.

-.sp
-2) Within a message list, the following designations may refer to messages
+.IP 2) 4
+Within a message list, the following designations may refer to messages

 that do not exist: a single numeric message name, the single message name
 \*(lqcur\*(rq, and (obviously) the single message name \*(lqnew\*(rq.
 All other message designations must refer to at least one existing
 that do not exist: a single numeric message name, the single message name
 \*(lqcur\*(rq, and (obviously) the single message name \*(lqnew\*(rq.
 All other message designations must refer to at least one existing

-message.
-.sp
-3) An empty folder is not in itself an error.
-
-Message numbers greater than the highest existing message in a folder
-as part of a range designation are replaced with the next free message
-number.
-
+message, if the folder contains messages.
+.IP 3) 4
+An empty folder is not, in itself, an error.
+.PP
+A message number less than that of the smallest existing message in a
+folder is treated as if the message already exists.  A message number
+greater than that of the highest existing message in a folder causes
+an \*(lqout of range\*(rq error message to be displayed.
+.PP
+As part of a range designation that contains messages that do exist,
+message numbers less than the smallest, or greater than the highest,
+existing message in a folder are ignored.
+.PP

 Examples: The current folder foo contains messages 3 5 6.
 Cur is 4.
 Examples: The current folder foo contains messages 3 5 6.
 Cur is 4.

-
+.PP
+.RS 5

 .nf
 .nf

-.in +.5i
-% mhpath
+$ mhpath

 /r/phyl/Mail/foo
 
 /r/phyl/Mail/foo
 

-% mhpath all
+$ mhpath all

 /r/phyl/Mail/foo/3
 /r/phyl/Mail/foo/5
 /r/phyl/Mail/foo/6
 
 /r/phyl/Mail/foo/3
 /r/phyl/Mail/foo/5
 /r/phyl/Mail/foo/6
 

-% mhpath 2001
-/r/phyl/Mail/foo/7
+$ mhpath 2001
+mhpath: message 2001 out of range 1-6

 
 

-% mhpath 1\-2001
+$ mhpath 1\-2001

 /r/phyl/Mail/foo/3
 /r/phyl/Mail/foo/5
 /r/phyl/Mail/foo/6
 
 /r/phyl/Mail/foo/3
 /r/phyl/Mail/foo/5
 /r/phyl/Mail/foo/6
 

-% mhpath new
+$ mhpath new

 /r/phyl/Mail/foo/7
 
 /r/phyl/Mail/foo/7
 

-% mhpath last new
+$ mhpath last new

 /r/phyl/Mail/foo/6
 /r/phyl/Mail/foo/7
 
 /r/phyl/Mail/foo/6
 /r/phyl/Mail/foo/7
 

-% mhpath last\-new
-bad message list \*(lqlast\-new\*(rq.
+$ mhpath last\-new
+mhpath: bad message list last\-new

 
 

-% mhpath cur
+$ mhpath cur

 /r/phyl/Mail/foo/4
 
 /r/phyl/Mail/foo/4
 

-% mhpath 1\-2
-no messages in range \*(lq1\-2\*(rq.
+$ mhpath 1\-2
+mhpath: no messages in range 1\-2

 
 

-% mhpath first:2
+$ mhpath first:2

 /r/phyl/Mail/foo/3
 /r/phyl/Mail/foo/5
 
 /r/phyl/Mail/foo/3
 /r/phyl/Mail/foo/5
 

-% mhpath 1 2
+$ mhpath 1 2

 /r/phyl/Mail/foo/1
 /r/phyl/Mail/foo/2
 /r/phyl/Mail/foo/1
 /r/phyl/Mail/foo/2

-.in -.5i

 .fi
 .fi

-
-\fImhpath\fR is also useful in back\-quoted operations:
-
+.RE
+.PP
+.B mhpath
+is also useful in backquoted operations:
+.PP
+.RS 5

 .nf
 .nf

-.in +.5i
-% cd `mhpath +inbox`
+$ cd \`mhpath +inbox\`

 
 

-% echo `mhpath +`
+$ echo \`mhpath +\`

 /r/phyl/Mail
 /r/phyl/Mail

-.in -.5i

 .fi
 .fi

-.Fi
-^$HOME/\&.mh\(ruprofile~^The user profile
-.Pr
+.RE
+.PP
+Because
+.B mhpath
+expands and sorts
+.RI [ msgs ].
+the command
+.PP
+.RS 5
+.nf
+mv \`mhpath 501 500\`
+.fi
+.RE
+.PP
+to will not move 501 to 500; quite the reverse.  But
+.PP
+.RS 5
+.nf
+mv \`mhpath 501\` \`mhpath 500\`
+.fi
+.RE
+.PP
+will do the trick.
+.PP
+Out-of-range message 0 produces a different error message than large
+out-of-range message numbers.  But both cause
+.B mhpath
+to exit with non-zero status.
+.SH FILES
+.fc ^ ~
+.nf
+.ta \w'ExtraBigProfileName  'u
+^$HOME/.mh_profile~^The user profile
+.fi
+.SH "PROFILE COMPONENTS"
+.fc ^ ~
+.nf
+.ta 2.4i
+.ta \w'ExtraBigProfileName  'u

 ^Path:~^To determine the user's nmh directory
 ^Path:~^To determine the user's nmh directory

-.Ps

 ^Current\-Folder:~^To find the default current folder
 ^Current\-Folder:~^To find the default current folder

-.Sa
-folder(1)
-.De
-`+folder' defaults to the current folder
-.Ds
-`msgs' defaults to none
-.Co
+.fi
+.SH "SEE ALSO"
+.IR folder (1)
+.SH DEFAULTS
+.nf
+.RB ` +folder "' defaults to the current folder"
+.RB ` msgs "' defaults to none"
+.fi
+.SH CONTEXT

 None
 None

-.Bu
-Like all nmh commands, \fImhpath\fR expands and sorts \%[msgs].  So don't
-expect
-
-.ti +.5i
-mv `mhpath 501 500`
-
-to move 501 to 500.
-Quite the reverse.  But
-
-.ti +.5i
-mv `mhpath 501` `mhpath 500`
-
-will do the trick.
-
-Out of range message 0 is treated far more severely than large out of
-range message numbers.
-.En