X-Git-Url: http://git.marmaro.de/?p=mmh;a=blobdiff_plain;f=man%2Fmh-format.man5;h=3935872ed2a6d8068014e94e78607451b7b49511;hp=dccedad67665acd178d6597721f2bc5eb939aec1;hb=18591f8e001ecedbee48a51c1d1f08ebaa1c15c8;hpb=88d0e7601d67f8212791482433dcda4cb9d3eaac diff --git a/man/mh-format.man5 b/man/mh-format.man5 index dccedad..3935872 100644 --- a/man/mh-format.man5 +++ b/man/mh-format.man5 @@ -1,12 +1,12 @@ .\" -.\" THIS FILE HAS BEEN AUTOMATICALLY GENERATED. DO NOT EDIT. +.\" %nmhwarning% .\" .TH MH-FORMAT %manext5% "%nmhdate%" MH.6.8 [%nmhversion%] .SH NAME -mh-format \- format file for nmh message system +mh-format \- format file for mh message system .SH DESCRIPTION Several -.B nmh +.B mmh commands utilize either a .I format string or a @@ -19,25 +19,21 @@ for each message; 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 , +There are a few alternate scan listing formats available, e.g. +.IR scan.nmh , +.IR scan.mailx , and -.IR nmh/etc/scan.timely . +.IR scan.timely . Look in -.I nmh/etc +.I %etcdir% for other .B scan and .B repl -format files which may have been written at your site. +format files. .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 +This manual section explains how to write and modify format commands. +Note: familiarity with the C .B printf routine is assumed. .PP @@ -51,14 +47,20 @@ string, the usual C backslash characters are honored: `\\b', `\\f', .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) +There are four types of escape sequences: +.PP +.RS 5 +.nf +.ta +\w'name of escape class xxxxxxx'u +.RI "1) header components %{" component } +.RI "2) built-in functions %(" "function arg" ) +.RI "3) flow control %< ... %? ... %| ... %> +.RI "4) comments %; ... +.fi +.RE +.PP +Comments may be inserted in most places where no function argument is +expected. A comment begins with `%;' and ends with a (non-escaped) newline. .PP A @@ -68,7 +70,7 @@ escape is specified as 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. +refers to the `Date:' 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 @@ -91,7 +93,7 @@ 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 `%'; +a leading `%'. .SS "Control escapes" .PP @@ -110,7 +112,7 @@ These are combined into the conditional execution construct: .fi .RE .PP -Extra white space is shown here only for clarity. These +(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 @@ -131,7 +133,7 @@ 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 +The `%?' control escape is optional, and 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. @@ -145,7 +147,7 @@ these include: .RS 5 .nf .ta +\w'Argument 'u +\w'An optional component, 'u -.I Argument Description Example Syntax +.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\^}) @@ -185,7 +187,7 @@ For example, .fi .RE .PP -writes the value of the header component \*(lqFrom:\*(rq to the +writes the value of the header component `From:' to the internal register named str; then (\fImymbox\fR\^) reads str and writes its result to the internal register named .IR num ; @@ -194,8 +196,8 @@ then the control escape evaluates If .IR num is non-zero, the -string \*(lqTo:\*(rq is printed followed by the value of the -header component \*(lqTo:\*(rq. +string `To:' is printed followed by the value of the +header component `To:'. .SS Evaluation The evaluation of format strings is performed by a small virtual machine. @@ -213,6 +215,13 @@ or .I str is used as the argument: which register is used depends on the function, as listed below. +.\" What is the difference between these two lines: +.\" %(void{comp})%(trim)%(putstr) +.\" %(putstr(trim{comp})) +.\" The latter can be used as a single expression for %<. +.\" It does make a difference for (decode) because in the former +.\" way, wrapping (decode) with (void) can be necessary. +.\" What is the preferred way? .PP Component escapes write the value of their message header in .IR str . @@ -243,7 +252,7 @@ The function escapes may be roughly grouped into a few categories. .RS 5 .nf .ta \w'Fformataddr 'u +\w'Aboolean 'u +\w'Rboolean 'u -.I Function Argument Result Description +.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) @@ -276,13 +285,14 @@ 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 +compval comp integer Set \fInum\fR to `\fBatoi\fR(\fIcomp\fR\^)' .\" 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 + component and print it unquote expr string remove RFC-2822 quotes from \fIstr\fR -trim expr trim trailing white-space from \fIstr\fR +unmailto expr string remove `mailto:' and < > from \fIstr\fR +trim expr trim white-space from \fIstr\fR putstr expr print \fIstr\fR putstrf expr print \fIstr\fR in a fixed width putnum expr print \fInum\fR @@ -301,7 +311,7 @@ The following functions require a date component as an argument: .RS 5 .nf .ta \w'Fformataddr 'u +\w'Aboolean 'u +\w'Rboolean 'u -.I Function Argument Return Description +.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) @@ -325,7 +335,7 @@ 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 +tws date string official RFC-822 rendering pretty date string user-friendly rendering .fi .RE @@ -337,8 +347,8 @@ the first address present in the header component. .RS 5 .nf .ta \w'Fformataddr 'u +\w'Aboolean 'u +\w'Rboolean 'u -.I Function Argument Return Description -proper addr string official 822 rendering +.I "Function Argument Return Description +proper addr string official RFC-822 rendering friendly addr string user-friendly rendering addr addr string mbox@host or host!mbox rendering* pers addr string the personal name* @@ -357,10 +367,10 @@ gname addr string name of group* .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. +`\fIcomp\fR' against the user's mailbox name and any +.RI ` Alternate-Mailboxes '. It returns true if any address matches, -however, it also returns true if the \*(lq\fIcomp\fR\*(rq header is not +however, it also returns true if the `\fIcomp\fR' header is not present in the message. If needed, the (\fInull\fR\^) function can be used to explicitly test for this case.) .SS Formatting @@ -379,35 +389,33 @@ 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 +%14(\fIputstrf\^\fR{\fIfrom\^\fR}) will print the `From:' 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. +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 +With all this in mind, here's a 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%| %> +%4(msg)%<(cur)+%| %>%<{replied}\-%| %> .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: +be printed; if a `Replied:' field is present then a `\-' +else a space should be printed. Next: .PP .RS .nf @@ -424,7 +432,7 @@ a slash. Next, .fi .RE .PP -If a \*(lqDate:\*(rq field was present, +If a `Date:' field was present, then a space is printed, otherwise a `*'. Next, .PP @@ -434,9 +442,9 @@ Next, .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 +if the message is from me, and there is a `To:' header, +print `To:' followed by a `user-friendly' rendering of the +first address in the `To:' field; any MIME-encoded characters are decoded into the actual characters. Continuing, .PP @@ -447,8 +455,8 @@ Continuing, .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. +then the `From:' address is printed +in a mime-decoded, `user-friendly' format. And finally, .PP .RS 5 @@ -472,7 +480,7 @@ format file. .PP This clears .I str -and formats the \*(lqReply-To:\*(rq header +and formats the `Reply-To:' header if present. If not present, the else-if clause is executed. .PP .RS 5 @@ -482,7 +490,7 @@ if present. If not present, the else-if clause is executed. .RE .PP This formats the -\*(lqFrom:\*(rq, \*(lqSender:\*(rq and \*(lqReturn-Path:\*(rq +`From:', `Sender:' or `Return-Path:' headers, stopping as soon as one of them is present. Next: .PP .RS 5 @@ -493,7 +501,7 @@ headers, stopping as soon as one of them is present. Next: .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. +wide with a leading label of `To:'. .PP .RS 5 .nf @@ -502,9 +510,9 @@ wide with a leading label of \*(lqTo:\*(rq. .RE .PP .I str -is cleared, and the \*(lqTo:\*(rq and \*(lqCc:\*(rq headers, along with the user's +is cleared, and the `To:' and `Cc:' headers, along with the user's address (depending on what was specified with -the \*(lq\-cc\*(rq switch to \fIrepl\fR\^) are formatted. +the `\-cc' switch to \fIrepl\fR\^) are formatted. .PP .RS 5 .nf @@ -513,11 +521,11 @@ the \*(lq\-cc\*(rq switch to \fIrepl\fR\^) are formatted. .RE .PP If the result is non-null, it is printed as above with a -leading label of \*(lqCc:\*(rq. +leading label of `Cc:'. .PP .RS 5 .nf -%<{subject}Subject: Re: %{subject}\\n%>\\ +%<{subject}Subject: Re: %(decode{subject})\\n%>\\ .fi .RE .PP @@ -533,8 +541,8 @@ a suitable reply subject is output. .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 +If a message-id component was present, an `In-Reply-To:' header is +output including the message-id, followed by a `References:' header with references, if present, and the message-id. As with all plain-text, the row of dashes are output as-is. @@ -546,17 +554,17 @@ Here's that part again in pseudo-code: .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) + print("In-reply-to: ") + print(message-id.value) + print("\\n") endif if (comp_exists(message-id)) then - print (\*(lqReferences: \*(rq) + print("References: ") if (comp_exists(references)) then print(references.value); endif - print (message-id.value) - print (\*(lq\\n\*(rq) + print(message-id.value) + print("\\n") endif .fi .RE @@ -564,8 +572,8 @@ endif .\" (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 +One more example: +.B Mmh supports very large message numbers, and it is not uncommon for a folder to have far more than 10000 messages. @@ -574,12 +582,11 @@ to have far more than 10000 messages. .\" 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 +Nonetheless several 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 +The mh format strings can be modified to behave more sensibly with larger message numbers: .PP .RS