Cleanup manpage mh-format(5)
authormarkus schnalke <meillo@marmaro.de>
Tue, 19 Apr 2016 14:15:10 +0000 (16:15 +0200)
committermarkus schnalke <meillo@marmaro.de>
Tue, 19 Apr 2016 14:15:10 +0000 (16:15 +0200)
- More suitable scan listing examples
- Adjust paths
- There are no ``local mh experts'' anymore in the mmh world
- Add overview on the escape types
- %(decode) does print str as well
- Decode Subject header in the example
- Further minor stuff

man/mh-format.man5

index 5fe3451..20b3937 100644 (file)
@@ -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 mmh/etc/scan.time ,
-.IR mmh/etc/scan.size ,
+There are a few alternate scan listing formats available, e.g.
+.IR scan.nmh ,
+.IR scan.mailx ,
 and
-.IR mmh/etc/scan.timely .
+.IR scan.timely .
 Look in
-.I mmh/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 mh
-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
@@ -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.
@@ -280,7 +282,7 @@ 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
 putstr expr            print \fIstr\fR
@@ -325,7 +327,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
@@ -338,7 +340,7 @@ the first address present in the header component.
 .nf
 .ta \w'Fformataddr 'u +\w'Aboolean 'u +\w'Rboolean 'u
 .I "Function   Argument        Return  Description
-proper addr    string  official 822 rendering
+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*
@@ -383,16 +385,15 @@ size in a field six characters wide filled with leading zeros;
 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:
@@ -481,7 +482,7 @@ if present.  If not present, the else-if clause is executed.
 .RE
 .PP
 This formats the
-`From:', `Sender:' and `Return-Path:'
+`From:', `Sender:' or `Return-Path:'
 headers, stopping as soon as one of them is present.  Next:
 .PP
 .RS 5
@@ -516,7 +517,7 @@ leading label of `Cc:'.
 .PP
 .RS 5
 .nf
-%<{subject}Subject: Re: %{subject}\\n%>\\
+%<{subject}Subject: Re: %(decode{subject})\\n%>\\
 .fi
 .RE
 .PP
@@ -545,17 +546,17 @@ Here's that part again in pseudo-code:
 .nf
 .ta .5i 1i 1.5i 2i
 if (comp_exists(message-id))  then
-       print (`In-reply-to: ')
-       print (message-id.value)
-       print (`\\n')
+       print("In-reply-to: ")
+       print(message-id.value)
+       print("\\n")
 endif
 if (comp_exists(message-id)) then
-       print (`References: ')
+       print("References: ")
        if (comp_exists(references)) then
              print(references.value);
        endif
-       print (message-id.value)
-       print (`\\n')
+       print(message-id.value)
+       print("\\n")
 endif
 .fi
 .RE
@@ -563,8 +564,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 mmh
+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.
@@ -573,8 +574,7 @@ 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.)
-Nonetheless (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.