X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/b36e2ab7892cdf30a8b33d02e00af70398013b5d..9291a5f82480f2458e04cb9ea7e6749bc952b308:/man/mhpath.man diff --git a/man/mhpath.man b/man/mhpath.man index 5f1a15f1..b8674857 100644 --- a/man/mhpath.man +++ b/man/mhpath.man @@ -1,136 +1,166 @@ -.\" +.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 +$ mhpath /r/phyl/Mail/foo -% mhpath all +$ mhpath all /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 -% mhpath new +$ mhpath new /r/phyl/Mail/foo/7 -% mhpath last new +$ mhpath last new /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 -% 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 -% mhpath 1 2 +$ 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` +$ cd \`mhpath +inbox\` -% echo `mhpath +` +$ echo \`mhpath +\` /r/phyl/Mail -.in -.5i .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 -.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 +.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 -.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