Glenn -- thanks for helping to move out the next release!
On 27 June 2003 at 13:33, Glenn Burkhardt <[EMAIL PROTECTED]> wrote:
> Bart Massey submitted an update to the mh-format man page as part of
> bug report 2031. I'm not an expert on the content, but it looks like
> he's done a good job at improving this page.
>
> Please review it, and if there are no corrections, I plan to commit it.
It mostly looks good to me! Here are some comments and fixes:
------------------------------------------------------------------------
> Format strings are designed to be efficiently parsed by
> nmh which means they are not necessarily simple to write
> and understand. This means that novice, casual, or even
> advanced users of nmh should not have to deal with them.
I've never seen the point of the last sentence. They aren't *that*
hard to understand; the sentence merely scares people away. I'd
suggest deleting that sentence.
------------------------------------------------------------------------
> A format string consists of ordinary text, and special
> multi-character escapesequences which begin with `%'.
s/escapesequences/escape sequences/
------------------------------------------------------------------------
> The argument to a function escape is processed in argument
> mode. A function or component escape evaluated in argu-
> ment mode should not be preceded by a leading `%'.
Nothing so far has explained what "argument mode" is. I don't know
myself.
------------------------------------------------------------------------
> The control escape
> tests whether the function or component escape evaluates
> non-zero (for an integer-valued escape) or non-empty (for
> a string-valued escape).
This sentence talks about "non-zero" and "non-empty," but it doesn't
define the terms used later, "true" and "false." It'd suggest
changing it to read:
The control escape
evaluates the function or component escape as
true (non-zero for an integer-valued escape, or non-empty for
a string-valued escape) or false (zero or empty, respectively).
------------------------------------------------------------------------
> If the condition of a `%<' or `%?' control escape
> evaulates true, or a `%|' escape is encountered, then the
> format-text of that escape (up to the next corresponding
> `%|', `%?', or `%>' control escape) is interpreted nor-
> mally. Text up to the corresponding `%>' control escape is
> then skipped, and the `%>' control escape is discarded.
>
> If the condition of a `%<' or `%?' control escape evalu-
> ates false, however, the format-text (up to the next cor-
> responding `%|', `%?', or `%>' control escape) is skipped
> instead of being interpreted. Evaluation then continues
> at the new escape.
>
> The `%?' control escape is optional, and may be included
> zero or more times. The `%|' control escape is also
> optional, and may be included at most once.
Good grief; no wonder people think format strings are hard to
understand! I'd suggest adding a paragraph like this to the end:
(In other words, `%<' is like the "if" in an
if-elseif-else-endif block, `%?' is like the "elseif",
`%|' is like "else", and `%>' is like "endif".
If the condition after `%<' is true, its format-text
is interpreted. Otherwise, that format-text is skipped,
and the first `%?' is evaluated as before.
If no `%?' escape evaluates true, then the
format-text after `%|', if any, will be interpreted.)
I don't have a lot of time today to write that perfectly, but I
think it's close enough to give people the idea. (If anyone wants
to make my wording more accurate, please go ahead!)
------------------------------------------------------------------------
> %<(mymbox{from}) To: %{to}%>
>
> writes the value of the header component "From:" to str;
> then (mymbox) reads str and writes its result to num; then
> the control escape evaluates num. If num is non-zero, the
> string "To:" is printed followed by the value of the
> header component "To:".
Nothing has explained str and num yet. They're explained in the
following paragraph (under Evaluation), but they need to be
identified as soon as they're used. How about this wording instead?
writes the value of the header component "From:" to the
internal register named str; then (mymbox) reads str and
writes its result to the internal register named num; then
the control escape evaluates num. If num is non-zero, the
string "To:" is printed followed by the value of the
header component "To:".
------------------------------------------------------------------------
> These functions require an address component as an argu-
> ment. The return value of functions noted with `*' is
> computed from the first address present in the header com-
> ponent.
>
> Function Argument Return Description
> proper addr string official 822 rendering
The reference "These functions" isn't very clear: is it talking
about the functions above or below? I'd suggest changing "These
functions" to "The following functions".
------------------------------------------------------------------------
> ingrp addr integer address was inside a group (0 or 1)*
> gname addr string name of group*
I don't think anything explains what a "group" is.
------------------------------------------------------------------------
> %<(mymbox{from})%<{to}To:%14(friendly{to})%>%>
>
> 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. Continuing,
>
> %<(zero)%17(friendly{from})%>
>
> if either of the above two tests failed, then the "From:"
> address is printed in a "user-friendly" format. And
> finally,
>
> %{subject}%<{body}<<%{body}%>
>
> the subject and initial body (if any) are printed.
The slightly-old /etc/nmh/scan.default file that I have also uses
%(decode) on those three components:
%<(mymbox{from})%<{to}To:%14(decode(friendly{to}))%>%>\
%<(zero)%17(decode(friendly{from}))%> \
%(decode{subject})%<{body}<<%{body}>>%>
I haven't checked to see whether the latest sources do that. If
they do, the three lines need to be replaced. Also, the description
of the first could be changed to read:
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,
------------------------------------------------------------------------
> For a more complicated example, next consider the default
> replcomps format file.
The example shown is not even chose to my /etc/nmh/replcomps file!
And if we update replcomps to correct In-reply-to (and etc.), it'll
need even more fixes.
I'd volunteer to work with anyone else who's interested to update
the description once we have a new replcomps. (But I may be on the
road from the end of August until December; that wouldn't be a good
time.)
------------------------------------------------------------------------
Thanks again. It'll be great to get this page up to date!
Jerry
