+++ /dev/null
-.\"
-.\" THIS FILE HAS BEEN AUTOMATICALLY GENERATED. DO NOT EDIT.
-.\"
-.TH MH-FORMAT %manext5% "%nmhdate%" MH.6.8 [%nmhversion%]
-.SH NAME
-mh-format \- format file for nmh message system
-.SH DESCRIPTION
-Several
-.B nmh
-commands utilize either a
-.I format
-string or a
-.I format
-file during their execution. For example,
-.B scan
-uses a format string which directs it how to generate the scan listing
-for each message;
-.B repl
-uses a format file which directs it
-how to generate the reply to a message, and so on.
-.PP
-There are a few alternate scan listing formats available
-in
-.IR nmh/etc/scan.time ,
-.IR nmh/etc/scan.size ,
-and
-.IR nmh/etc/scan.timely .
-Look in
-.I nmh/etc
-for other
-.B scan
-and
-.B repl
-format files which may have been written at your site.
-.PP
-It suffices to have your local
-.B nmh
-expert actually write new format
-commands or modify existing ones. This manual section explains how to
-do that. Note: familiarity with the C
-.B printf
-routine is assumed.
-.PP
-A format string consists of ordinary text, and special multi-character
-escape sequences which begin with `%'. When specifying a format
-string, the usual C backslash characters are honored: `\\b', `\\f',
-`\\n', `\\r', and `\\t'. Continuation lines in format files end with
-`\\' followed by the newline character.
-
-.\" TALK ABOUT SYNTAX FIRST, THEN SEMANTICS
-.SS SYNTAX
-Format strings are built around
-.IR "escape sequences" .
-There are three types of escape sequences: header
-.IR components ,
-built-in
-.IR functions ,
-and flow
-.IR control .
-Comments may be inserted in most places where a function argument is
-not expected. A comment begins with `%;' and ends with a (non-escaped)
-newline.
-.PP
-A
-.I component
-escape is specified as
-.RI `%{ component }',
-and
-exists for each header found in the message being processed. For example
-.RI `%{ date }'
-refers to the \*(lqDate:\*(rq field of the appropriate message.
-All component escapes have a string value. Normally, component values are
-compressed by converting any control characters (tab and newline included)
-to spaces, then eliding any leading or multiple spaces. However, commands
-may give different interpretations to some component escapes; be sure
-to refer to each command's manual entry for complete details.
-.PP
-A
-.I function
-escape is specified as
-.RI `%( function )'.
-All functions are built-in, and most have a string or numeric value.
-A function escape may have an
-.IR argument .
-The argument follows the function escape: separating
-whitespace is discarded:
-.RI `%( function " " argument )'.
-.PP
-In addition to literal numbers or strings,
-the argument to a function escape can be another function, a component,
-or a control escape. When the argument is a function or a
-component, they are listed without a leading `%'. When control escapes
-are used as function arguments, they written as normally, with
-a leading `%';
-
-.SS "Control escapes"
-.PP
-A
-.I control
-escape is one of: `%<', `%?', `%|', or `%>'.
-These are combined into the conditional execution construct:
-.PP
-.RS 5
-.nf
-.RI "%< " condition " " "format-text"
-.RI "%? " condition " " "format-text"
- \&...
-.RI "%| " "format-text"
-%>
-.fi
-.RE
-.PP
-Extra white space is shown here only for clarity. These
-constructs may be nested without ambiguity. They form a general
-.B if\-elseif\-else\-endif
-block where only one of the
-format-texts
-is interpreted. In other
-words, `%<' is like the "if", `%?' is like the "elseif", `%|' is like
-"else", and `%>' is like "endif".
-.PP
-A `%<' or `%?' control escape causes its condition to be evaluated.
-This condition is a
-.I component
-or
-.IR function .
-For integer valued functions or components, the condition is true
-if the function return or component value is non-zero, and false if zero.
-For string valued functions or components, the condition is true
-if the function return or component value is
-a non-empty string, and false for an empty string.
-
-.PP
-The `%?' control escape is optional, and may there may be more
-than one `%?' control escape in a conditional block.
-The `%|' control escape
-is also optional, but may be included at most once.
-
-.SS "Function escapes"
-Functions expecting an argument generally
-require an argument of a particular type.
-In addition to the number and string types,
-these include:
-.PP
-.RS 5
-.nf
-.ta +\w'Argument 'u +\w'An optional component, 'u
-.I Argument Description Example Syntax
-literal A literal number %(\fIfunc\fR 1234)
- or string %(\fIfunc\fR text string)
-comp Any component %(\fIfunc\fR\^{\fIin-reply-to\fR\^})
-date A date component %(\fIfunc\fR\^{\fIdate\fR\^})
-addr An address component %(\fIfunc\fR\^{\fIfrom\fR\^})
-expr Nothing %(\fIfunc\fR)
- or a subexpression %(\fIfunc\fR\^(\fIfunc2\fR\^))
- or control escape %(\fIfunc\fR %<{\fIreply-to\fR\^}%|%{\fIfrom\fR\^}%>)
-.fi
-.RE
-.PP
-The types
-.I date
-and
-.I addr
-have the same syntax as
-.IR comp ,
-but require that the header component be a date string, or address
-string, respectively.
-.PP
-Most arguments not of type
-.IR expr
-are required.
-When escapes are nested (via expr arguments), evaluation is done from inner-most to outer-most.
-As noted above, for the
-expr
-argument type,
-functions and components are written without a
-leading `%'.
-Control escape arguments must use a leading `%', preceded by a space.
-.PP
-For example,
-.PP
-.RS 5
-.nf
-%<(mymbox{from}) To: %{to}%>
-.fi
-.RE
-.PP
-writes the value of the header component \*(lqFrom:\*(rq to the
-internal register named str; then (\fImymbox\fR\^) reads str and
-writes its result to the internal register named
-.IR num ;
-then the control escape evaluates
-.IR num .
-If
-.IR num
-is non-zero, the
-string \*(lqTo:\*(rq is printed followed by the value of the
-header component \*(lqTo:\*(rq.
-.SS Evaluation
-The evaluation of format strings is performed
-by a small virtual machine.
-The machine is capable of evaluating nested expressions
-as described above, and in addition
-has an integer register
-.IR num ,
-and a text string register
-.IR str .
-When a function escape that
-accepts an optional argument is processed,
-and the argument is not present, the current value of either
-.I num
-or
-.I str
-is used as the argument: which register is
-used depends on the function, as listed below.
-.PP
-Component escapes write the value of their message header in
-.IR str .
-Function escapes write their return value in
-.I num
-for functions returning integer or boolean values, and in
-.I str
-for functions returning string values. (The boolean type is a subset
-of integers with usual values 0=false and 1=true.) Control escapes
-return a boolean value, setting
-.I num
-to 1 if the last explicit condition
-evaluated by a `%<' or `%?' control
-succeeded, and 0 otherwise.
-.PP
-All component escapes, and those function escapes which return an
-integer or string value, evaluate to their value as well as setting
-.I str
-or
-.IR num .
-Outermost escape expressions in
-these forms will print
-their value, but outermost escapes which return a boolean value
-do not result in printed output.
-.SS Functions
-The function escapes may be roughly grouped into a few categories.
-.PP
-.RS 5
-.nf
-.ta \w'Fformataddr 'u +\w'Aboolean 'u +\w'Rboolean 'u
-.I Function Argument Result Description
-msg integer message number
-cur integer message is current (0 or 1)
-unseen integer message is unseen (0 or 1)
-size integer size of message
-strlen integer length of \fIstr\fR
-width integer output buffer size in bytes
-charleft integer bytes left in output buffer
-timenow integer seconds since the UNIX epoch
-me string the user's mailbox
-eq literal boolean \fInum\fR == \fIarg\fR
-ne literal boolean \fInum\fR != \fIarg\fR
-gt literal boolean \fInum\fR > \fIarg\fR
-match literal boolean \fIstr\fR contains \fIarg\fR
-amatch literal boolean \fIstr\fR starts with \fIarg\fR
-plus literal integer \fIarg\fR plus \fInum\fR
-minus literal integer \fIarg\fR minus \fInum\fR
-divide literal integer \fInum\fR divided by \fIarg\fR
-modulo literal integer \fInum\fR modulo \fIarg\fR
-num literal integer Set \fInum\fR to \fIarg\fR.
-num integer Set \fInum\fR to zero.
-lit literal string Set \fIstr\fR to \fIarg\fR.
-lit string Clear \fIstr\fR.
-getenv literal string Set \fIstr\fR to environment value of \fIarg\fR
-profile literal string Set \fIstr\fR to profile component \fIarg\fR
- value
-.\" dat literal int return value of dat[arg]
-nonzero expr boolean \fInum\fR is non-zero
-zero expr boolean \fInum\fR is zero
-null expr boolean \fIstr\fR is empty
-nonnull expr boolean \fIstr\fR is non-empty
-void expr Set \fIstr\fR or \fInum\fR
-comp comp string Set \fIstr\fR to component text
-compval comp integer Set \fInum\fR to \*(lq\fBatoi\fR(\fIcomp\fR\^)\*(rq
-.\" compflag comp integer Set \fInum\fR to component flags bits (internal)
-.\" decodecomp comp string Set \fIstr\fR to RFC-2047 decoded component text
-decode expr string decode \fIstr\fR as RFC-2047 (MIME-encoded)
- component
-unquote expr string remove RFC-2822 quotes from \fIstr\fR
-trim expr trim trailing white-space from \fIstr\fR
-putstr expr print \fIstr\fR
-putstrf expr print \fIstr\fR in a fixed width
-putnum expr print \fInum\fR
-putnumf expr print \fInum\fR in a fixed width
-.\" addtoseq literal add msg to sequence (LBL option)
-nodate string integer Argument not a date string (0 or 1)
-formataddr expr append \fIarg\fR to \fIstr\fR as a
- (comma separated) address list
-putaddr literal print \fIstr\fR address list with
- \fIarg\fR as optional label;
- get line width from \fInum\fR
-.fi
-.RE
-.PP
-The following functions require a date component as an argument:
-.PP
-.RS 5
-.nf
-.ta \w'Fformataddr 'u +\w'Aboolean 'u +\w'Rboolean 'u
-.I Function Argument Return Description
-sec date integer seconds of the minute
-min date integer minutes of the hour
-hour date integer hours of the day (0-23)
-wday date integer day of the week (Sun=0)
-day date string day of the week (abbrev.)
-weekday date string day of the week
-sday date integer day of the week known?
- (1=explicit,0=implicit,\-1=unknown)
-mday date integer day of the month
-yday date integer day of the year
-mon date integer month of the year
-month date string month of the year (abbrev.)
-lmonth date string month of the year
-year date integer year (may be > 100)
-zone date integer timezone in hours
-tzone date string timezone string
-szone date integer timezone explicit?
- (1=explicit,0=implicit,\-1=unknown)
-date2local date coerce date to local timezone
-date2gmt date coerce date to GMT
-dst date integer daylight savings in effect? (0 or 1)
-clock date integer seconds since the UNIX epoch
-rclock date integer seconds prior to current time
-tws date string official 822 rendering
-pretty date string user-friendly rendering
-.fi
-.RE
-.PP
-These functions require an address component as an argument.
-The return value of functions noted with `*' is computed from
-the first address present in the header component.
-.PP
-.RS 5
-.nf
-.ta \w'Fformataddr 'u +\w'Aboolean 'u +\w'Rboolean 'u
-.I Function Argument Return Description
-proper addr string official 822 rendering
-friendly addr string user-friendly rendering
-addr addr string mbox@host or host!mbox rendering*
-pers addr string the personal name*
-note addr string commentary text*
-mbox addr string the local mailbox*
-mymbox addr integer List has the user's address? (0 or 1)
-host addr string the host domain*
-nohost addr integer no host was present (0 or 1)*
-type addr integer host type* (0=local,1=network,
- \-1=uucp,2=unknown)
-path addr string any leading host route*
-ingrp addr integer address was inside a group (0 or 1)*
-gname addr string name of group*
-.fi
-.RE
-.PP
-(A clarification on (\fImymbox\fR\^{\fIcomp\fR\^}) is in order.
-This function checks each of the addresses in the header component
-\*(lq\fIcomp\fR\*(rq against the user's mailbox name and any
-.RI \*(lq Alternate-Mailboxes \*(rq.
-It returns true if any address matches,
-however, it also returns true if the \*(lq\fIcomp\fR\*(rq header is not
-present in the message. If needed, the (\fInull\fR\^) function can be
-used to explicitly test for this case.)
-.SS Formatting
-When a function or component escape is interpreted and the result will
-be immediately printed, an optional field width can be specified to
-print the field in exactly a given number of characters. For example, a
-numeric escape like %4(\fIsize\fR\^) will print at most 4 digits of the
-message size; overflow will be indicated by a `?' in the first position
-(like `?234'). A string escape like %4(\fIme\fR\^) will print the first 4
-characters and truncate at the end. Short fields are padded at the right
-with the fill character (normally, a blank). If the field width argument
-begins with a leading zero, then the fill character is set to a zero.
-.PP
-The functions (\fIputnumf\fR\^) and (\fIputstrf\fR\^)
-print their result in exactly the number of characters
-specified by their leading field width argument. For example,
-%06(\fIputnumf\fR\^(\fIsize\fR\^)) will print the message
-size in a field six characters wide filled with leading zeros;
-%14(\fIputstrf\^\fR{\fIfrom\^\fR}) will print the \*(lqFrom:\*(rq header
-component in fourteen characters with trailing spaces added as needed.
-For \fIputstrf\fR, using a negative value for the field width causes
-right-justification of the string within the field, with padding on
-the left up to the field width.
-The functions (\fIputnum\fR\^) and
-(\fIputstr\fR\^) are somewhat special: they print their result in the minimum number of characters
-required, and ignore any leading field width argument.
-.PP
-The available output width is kept in an internal register; any output
-past this width will be truncated.
-.SS Examples
-With all this in mind,
-here's the default format string for
-.BR scan .
-It's been divided into several pieces for readability.
-The first part is:
-.PP
-.RS
-.nf
-%4(msg)%<(cur)+%| %>%<{replied}\-%?{encrypted}E%| %>
-.fi
-.RE
-.PP
-which says that the message number should be printed in four digits.
-If the message is the current message then a `+' else a space should
-be printed; if a \*(lqReplied:\*(rq field is present then a `\-'
-else if an \*(lqEncrypted:\*(rq field is present then an `E' otherwise
-a space should be printed. Next:
-.PP
-.RS
-.nf
-%02(mon{date})/%02(mday{date})
-.fi
-.RE
-.PP
-the month and date are printed in two digits (zero filled) separated by
-a slash. Next,
-.PP
-.RS 5
-.nf
-%<{date} %|*%>
-.fi
-.RE
-.PP
-If a \*(lqDate:\*(rq field was present,
-then a space is printed, otherwise a `*'.
-Next,
-.PP
-.RS 5
-.nf
-%<(mymbox{from})%<{to}To:%14(decode(friendly{to}))%>%>
-.fi
-.RE
-.PP
-if the message is from me, and there is a \*(lqTo:\*(rq header,
-print \*(lqTo:\*(rq followed by a \*(lquser-friendly\*(rq rendering of the
-first address in the \*(lqTo:\*(rq field; any MIME-encoded
-characters are decoded into the actual characters.
-Continuing,
-.PP
-.RS 5
-.nf
-%<(zero)%17(decode(friendly{from}))%>
-.fi
-.RE
-.PP
-if either of the above two tests failed,
-then the \*(lqFrom:\*(rq address is printed
-in a mime-decoded, \*(lquser-friendly\*(rq format.
-And finally,
-.PP
-.RS 5
-.nf
-%(decode{subject})%<{body}<<%{body}>>%>
-.fi
-.RE
-.PP
-the mime-decoded subject and initial body (if any) are printed.
-.PP
-For a more complicated example, next consider
-a possible
-.I replcomps
-format file.
-.PP
-.RS 5
-.nf
-%(lit)%(formataddr %<{reply-to}
-.fi
-.RE
-.PP
-This clears
-.I str
-and formats the \*(lqReply-To:\*(rq header
-if present. If not present, the else-if clause is executed.
-.PP
-.RS 5
-.nf
-%?{from}%?{sender}%?{return-path}%>)\\
-.fi
-.RE
-.PP
-This formats the
-\*(lqFrom:\*(rq, \*(lqSender:\*(rq and \*(lqReturn-Path:\*(rq
-headers, stopping as soon as one of them is present. Next:
-.PP
-.RS 5
-.nf
-%<(nonnull)%(void(width))%(putaddr To: )\\n%>\\
-.fi
-.RE
-.PP
-If the \fIformataddr\fR result is non-null, it is printed as
-an address (with line folding if needed) in a field \fIwidth\fR
-wide with a leading label of \*(lqTo:\*(rq.
-.PP
-.RS 5
-.nf
-%(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\\
-.fi
-.RE
-.PP
-.I str
-is cleared, and the \*(lqTo:\*(rq and \*(lqCc:\*(rq headers, along with the user's
-address (depending on what was specified with
-the \*(lq\-cc\*(rq switch to \fIrepl\fR\^) are formatted.
-.PP
-.RS 5
-.nf
-%<(nonnull)%(void(width))%(putaddr cc: )\\n%>\\
-.fi
-.RE
-.PP
-If the result is non-null, it is printed as above with a
-leading label of \*(lqcc:\*(rq.
-.PP
-.RS 5
-.nf
-%<{fcc}Fcc: %{fcc}\\n%>\\
-.fi
-.RE
-.PP
-If a
-.B \-fcc
-.I folder
-switch was given to
-.B repl
-(see
-.BR repl (1)
-for more details about %{\fIfcc\fR\^}),
-an \*(lqFcc:\*(rq header is output.
-.PP
-.RS 5
-.nf
-%<{subject}Subject: Re: %{subject}\\n%>\\
-.fi
-.RE
-.PP
-If a subject component was present,
-a suitable reply subject is output.
-.PP
-.RS 5
-.nf
-%<{message-id}In-Reply-To: %{message-id}\\n%>\\
-%<{message-id}References: %<{references} %{references}%>\\
-%{message-id}\\n%>
-\-\-\-\-\-\-\-\-
-.fi
-.RE
-.PP
-If a message-id component was present, an \*(lqIn-Reply-To:\*(rq header is
-output including the message-id, followed by a \*(lqReferences:\*(rq
-header with references, if present, and the message-id.
-As with all
-plain-text, the row of dashes are output as-is.
-.PP
-This last part is a good example for a little more elaboration.
-Here's that part again in pseudo-code:
-.PP
-.RS 5
-.nf
-.ta .5i 1i 1.5i 2i
-if (comp_exists(message-id)) then
- print (\*(lqIn-reply-to: \*(rq)
- print (message-id.value)
- print (\*(lq\\n\*(rq)
-endif
-if (comp_exists(message-id)) then
- print (\*(lqReferences: \*(rq)
- if (comp_exists(references)) then
- print(references.value);
- endif
- print (message-id.value)
- print (\*(lq\\n\*(rq)
-endif
-.fi
-.RE
-.PP
-.\" (Note that this pseudocode begs the question ``why not just
-.\" support this syntax?'' MH has been hacked on for a long time...)
-.\".PP
-One more example: Currently,
-.B nmh
-supports very
-large message numbers, and it is not uncommon for a folder
-to have far more than 10000 messages.
-.\" (Indeed, the original MH
-.\" tutorial document by Rose and Romine is entitled "How to
-.\" process 200 messages a day and still get some real work
-.\" done." The authors apparently only planned to get
-.\" real work done for about 50 days per folder.)
-Nontheless (as noted above)
-the various scan format strings are inherited
-from older MH versions, and are generally hard-coded to 4
-digits of message number before formatting problems
-start to occur.
-The nmh format strings can be modified to behave more sensibly with larger
-message numbers:
-.PP
-.RS
-.nf
-%(void(msg))%<(gt 9999)%(msg)%|%4(msg)%>
-.fi
-.RE
-.PP
-The current message number is placed in \fInum\fP.
-(Note that
-.RI ( msg )
-is an int function, not a component.)
-The
-.RI ( gt )
-conditional
-is used to test whether the message number
-has 5
-or more digits.
-If so, it is printed at full width: otherwise
-at 4 digits.
-.SH "SEE ALSO"
-scan(1), repl(1), ap(8), dp(8)
-
-.SH CONTEXT
-None
projects / mmh / blobdiff