X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/b36e2ab7892cdf30a8b33d02e00af70398013b5d..63621a81d16ab743de6b57d47578a9a2c670ad22:/man/mhpath.man diff --git a/man/mhpath.man b/man/mhpath.man index 5f1a15f1..15569b46 100644 --- a/man/mhpath.man +++ b/man/mhpath.man @@ -1,55 +1,66 @@ -.\" +.TH MHPATH %manext1% 2012-02-18 "%nmhversion%" +. .\" %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 -.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 -\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. -.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 -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. - +.PP +.RS 5 .nf -.in +.5i % mhpath /r/phyl/Mail/foo @@ -59,7 +70,7 @@ 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 @@ -74,13 +85,13 @@ Cur is 4. /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 @@ -89,48 +100,67 @@ no messages in range \*(lq1\-2\*(rq. % mhpath 1 2 /r/phyl/Mail/foo/1 /r/phyl/Mail/foo/2 -.in -.5i .fi - -\fImhpath\fR is also useful in back\-quoted operations: - +.RE +.PP +.B mhpath +is also useful in backquoted operations: +.PP +.RS 5 .nf -.in +.5i % cd `mhpath +inbox` % echo `mhpath +` /r/phyl/Mail -.in -.5i .fi -.Fi -^$HOME/\&.mh\(ruprofile~^The user profile -.Pr -^Path:~^To determine the user's nmh directory -.Ps -^Current\-Folder:~^To find the default current folder -.Sa -folder(1) -.De -`+folder' defaults to the current folder -.Ds -`msgs' defaults to none -.Co -None -.Bu -Like all nmh commands, \fImhpath\fR expands and sorts \%[msgs]. So don't -expect - -.ti +.5i +.RE +.PP +Because +.B mhpath +expands and sorts +.RI [ msgs ]. +the command +.PP +.RS 5 +.nf mv `mhpath 501 500` - -to move 501 to 500. -Quite the reverse. But - -.ti +.5i +.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. - -Out of range message 0 is treated far more severely than large out of -range message numbers. -.En +.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 +^Current\-Folder:~^To find the default current folder +.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