-.\"
+.TH MHPATH %manext1% 2012-02-18 "%nmhversion%"
+.
.\" %nmhwarning%
-.\" $Id$
-.\"
-.TH MHPATH %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
+.
.SH NAME
mhpath \- print full pathnames of nmh messages and folders
.SH SYNOPSIS
.HP 5
.na
.B mhpath
+.RB [ \-help ]
+.RB [ \-version ]
.RI [ +folder ]
.RI [ msgs ]
-.RB [ \-version ]
-.RB [ \-help ]
.ad
.SH DESCRIPTION
-.B Mhpath
+.B mhpath
expands and sorts the message list `msgs' and writes the full
-pathnames of the messages to the standard output separated by newlines.
+pathnames of the messages to the standard output, separated by newlines.
If no `msgs' are specified,
.B mhpath
-outputs the folder pathname
-instead. If the only argument is `+', your
+outputs the current mail folder's pathname instead.
+If the only argument is `+', your
.B nmh
-\*(lqPath\*(rq is output; this can be useful is shell scripts.
+\*(lqPath\*(rq is output; this can be useful in shell scripts.
.PP
-Contrasted with other
+In contrast with other
.B nmh
commands, a message argument to
.B mhpath
may often be intended for writing. Because of this:
-.PP
.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).
+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.
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.
+message, if the folder contains messages.
.IP 3) 4
-An empty folder is not in itself an error.
+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
-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.
+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.
/r/phyl/Mail/foo/6
% mhpath 2001
-/r/phyl/Mail/foo/7
+mhpath: message 2001 out of range 1-6
% mhpath 1\-2001
/r/phyl/Mail/foo/3
/r/phyl/Mail/foo/7
% mhpath last\-new
-bad message list \*(lqlast\-new\*(rq.
+mhpath: bad message list last\-new
% mhpath cur
/r/phyl/Mail/foo/4
% mhpath 1\-2
-no messages in range \*(lq1\-2\*(rq.
+mhpath: no messages in range 1\-2
% mhpath first:2
/r/phyl/Mail/foo/3
.RE
.PP
.B mhpath
-is also useful in back\-quoted operations:
+is also useful in backquoted operations:
.PP
.RS 5
.nf
.fi
.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'%etcdir%/ExtraBigFileName 'u
-^$HOME/\&.mh\(ruprofile~^The user profile
+.ta \w'ExtraBigProfileName 'u
+^$HOME/.mh_profile~^The user profile
.fi
-
.SH "PROFILE COMPONENTS"
.fc ^ ~
.nf
^Path:~^To determine the user's nmh directory
^Current\-Folder:~^To find the default current folder
.fi
-
.SH "SEE ALSO"
-folder(1)
-
+.IR folder (1)
.SH DEFAULTS
.nf
.RB ` +folder "' defaults to the current folder"
.RB ` msgs "' defaults to none"
.fi
-
.SH CONTEXT
None
-
-.SH BUGS
-Like all
-.B nmh
-commands,
-.B mhpath
-expands and sorts
-.RI [ msgs ].
-So don't
-expect
-.PP
-.RS 5
-.nf
-mv `mhpath 501 500`
-.fi
-.RE
-.PP
-to 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 is treated far more severely than large out of
-range message numbers.
projects / nmh / blobdiff