Added all of the MH sources, including RCS files, in

[mmh] / docs / historical / mh-6.8.5 / conf / doc / RCS / mh-format.rf,v

head    1.47;
access;
symbols;
locks; strict;


1.47
date    95.12.06.23.33.39;      author jromine; state Exp;
branches;
next    1.46;

1.46
date    94.04.21.19.11.19;      author jromine; state Exp;
branches;
next    1.45;

1.45
date    93.08.19.20.26.17;      author jromine; state Exp;
branches;
next    1.44;

1.44
date    93.06.12.06.49.57;      author jromine; state Exp;
branches;
next    1.43;

1.43
date    92.12.02.18.41.50;      author jromine; state Exp;
branches;
next    1.42;

1.42
date    92.11.20.19.35.06;      author jromine; state Exp;
branches;
next    1.41;

1.41
date    92.10.28.23.03.14;      author jromine; state Exp;
branches;
next    1.40;

1.40
date    92.10.27.00.20.03;      author jromine; state Exp;
branches;
next    1.39;

1.39
date    92.10.26.17.03.42;      author jromine; state Exp;
branches;
next    1.38;

1.38
date    92.05.12.22.23.34;      author jromine; state Exp;
branches;
next    1.37;

1.37
date    92.02.18.17.28.26;      author jromine; state Exp;
branches;
next    1.36;

1.36
date    92.02.14.19.14.42;      author jromine; state Exp;
branches;
next    1.35;

1.35
date    92.02.11.05.03.41;      author jromine; state Exp;
branches;
next    1.34;

1.34
date    92.02.09.22.11.10;      author jromine; state Exp;
branches;
next    1.33;

1.33
date    92.02.09.07.18.01;      author jromine; state Exp;
branches;
next    1.32;

1.32
date    92.02.07.01.08.25;      author jromine; state Exp;
branches;
next    1.31;

1.31
date    92.02.06.00.13.07;      author jromine; state Exp;
branches;
next    1.30;

1.30
date    92.01.29.22.55.31;      author jromine; state Exp;
branches;
next    1.29;

1.29
date    91.01.11.09.17.35;      author mh;      state Exp;
branches;
next    1.28;

1.28
date    91.01.11.09.15.19;      author mh;      state Exp;
branches;
next    1.27;

1.27
date    90.12.27.17.22.27;      author mh;      state Exp;
branches;
next    1.26;

1.26
date    90.04.05.15.09.13;      author sources; state Exp;
branches;
next    1.25;

1.25
date    90.04.04.23.07.22;      author sources; state Exp;
branches;
next    1.24;

1.24
date    90.04.02.18.07.25;      author sources; state Exp;
branches;
next    1.23;

1.23
date    90.04.02.17.56.48;      author sources; state Exp;
branches;
next    1.22;

1.22
date    90.04.02.17.49.02;      author sources; state Exp;
branches;
next    1.21;

1.21
date    90.03.31.18.24.07;      author sources; state Exp;
branches;
next    1.20;

1.20
date    90.03.22.11.31.15;      author sources; state Exp;
branches;
next    1.19;

1.19
date    90.03.20.22.21.11;      author sources; state Exp;
branches;
next    1.18;

1.18
date    90.03.20.19.41.54;      author sources; state Exp;
branches;
next    1.17;

1.17
date    90.03.20.17.36.10;      author sources; state Exp;
branches;
next    1.16;

1.16
date    90.03.20.10.20.21;      author sources; state Exp;
branches;
next    1.15;

1.15
date    90.03.19.16.02.45;      author sources; state Exp;
branches;
next    1.14;

1.14
date    90.03.18.23.27.00;      author sources; state Exp;
branches;
next    1.13;

1.13
date    90.03.18.20.55.16;      author sources; state Exp;
branches;
next    1.12;

1.12
date    90.03.18.19.54.04;      author sources; state Exp;
branches;
next    1.11;

1.11
date    90.03.18.16.49.19;      author sources; state Exp;
branches;
next    1.10;

1.10
date    90.03.15.20.11.07;      author sources; state Exp;
branches;
next    1.9;

1.9
date    90.03.15.11.27.04;      author sources; state Exp;
branches;
next    1.8;

1.8
date    90.03.15.11.20.39;      author sources; state Exp;
branches;
next    1.7;

1.7
date    90.03.15.10.50.08;      author sources; state Exp;
branches;
next    1.6;

1.6
date    90.03.15.10.40.21;      author sources; state Exp;
branches;
next    1.5;

1.5
date    90.03.15.10.11.44;      author sources; state Exp;
branches;
next    1.4;

1.4
date    90.03.15.00.06.45;      author sources; state Exp;
branches;
next    1.3;

1.3
date    90.03.14.17.34.00;      author sources; state Exp;
branches;
next    1.2;

1.2
date    90.03.14.09.51.17;      author sources; state Exp;
branches;
next    1.1;

1.1
date    90.03.14.09.50.29;      author sources; state Exp;
branches;
next    ;


desc
@@


1.47
log
@document %% and \\
@
text
@.\"    @@(MHWARNING)
.\" @@(#)$Id: mh-format.rf,v 1.46 1994/04/21 19:11:19 jromine Exp jromine $
.SC MH-FORMAT 5
.NA
mh-format \- format file for MH message system
.SY
some \fIMH\fR commands
.DE
Several \fIMH\fR commands utilize either a \fIformat\fR string or a
\fIformat\fR file during their execution.
For example,
\fIscan\fR\0(1) uses a format string which directs it how to generate the
scan listing for each message;
\fIrepl\fR\0(1) uses a format file which directs it how to generate the
reply to a message, and so on.

Format strings are designed to be efficiently parsed by \fIMH\fR which
means they are not necessarily simple to write and understand.
This means that novice, casual, or even advanced users of \fIMH\fR should
not have to deal with them.
Some canned scan listing formats are in
@@(MHETCPATH)/scan.time, @@(MHETCPATH)/scan.size, and @@(MHETCPATH)/scan.timely.
Look in @@(MHETCPATH) for other \fIscan\fR and \fIrepl\fR format files
which may have been written at your site.

It suffices to have your local \fIMH\fR expert actually write new format
commands or modify existing ones.
This manual section explains how to do that.
Note: familiarity with the C \fIprintf\fR routine is assumed.

A format string consists of ordinary text, and special
multi-character \fIescape\fR 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.
To put a literal `%' or `\\' in a format string, use two of them:
`%%' and `\\\\'.
.\" talk about syntax first, then semantics
There are three types of \fIescape\fR sequences:
header \fIcomponents\fR, built-in \fIfunctions\fR, and flow \fIcontrol\fR.

A \fIcomponent\fR escape is specified as `%{\fIcomponent\fR\^}',
and exists for each header found in the message being processed.
For example `%{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.

A \fIfunction\fR escape is specified as `%(\fIfunction\fR\^)'.
All functions are built-in, and most have a string or numeric value.

.ne 12
.Uh "Control-flow escapes"
A \fIcontrol\fR escape is one of: `%<', `%?', `%|', or `%>'. 
.\" `%[', or `%]'.
These are combined into the conditional execution construct:
.sp
.nf
        %<condition
                \fIformat text 1\fP
        %?condition2
                \fIformat text 2\fP
        %?condition3
                \fIformat text 3\fP
        \.\.\.
        %|
                \fIformat text N\fP
        %>
.fi
.sp
Extra white space is shown here only for clarity.
These constructs may be nested without ambiguity.
They form a general \fBif\-elseif\-else\-endif\fP block where
only one of the \fIformat text\fP segments is interpreted.

The `%<' and `%?' control escapes causes a condition to be evaluated.  
This condition
may be either a \fIcomponent\fP or a \fIfunction\fP.
The four constructs have the following syntax:
.sp 1
.nf
        %<{component}
        %<(function)
        %?{component}
        %?(function)
.fi
.sp
These control escapes test whether
the function or component value is non-zero (for integer-valued escapes),
or non-empty (for string-valued escapes).

If this test evaulates true,
then the format text
up to the next corresponding control escape 
(one of `%|', `%?', or `%>')
is interpreted normally.
Next,
all format text (if any) up to the corresponding `%>' control
escape is skipped.
The `%>' control escape is not interpreted;
normal
interpretation resumes after the `%>' escape.

If the test evaluates false, however,
then the format text 
up to the next corresponding control escape
(again, one of `%|', `%?', or `%>')
is skipped, instead of being interpreted.
If the control escape encountered was `%?',
then the condition associated with that control escape is
evaluated, and interpretation
proceeds after that test
as described in the previous paragraph.
If the control escape encountered was `%|',
then the format text
up to the corresponding `%>' escape
is interpreted normally.
As above, 
the `%>' escape is not interpreted and normal
interpretation resumes after the `%>' escape.

The `%?' control escape and its following format text
is optional, and may be included zero or more times.
The `%|' control escape and its following format text
is also optional, and may be included zero or one times.

.\" The '%[' and '%]' escapes form a loop construct.
.\" For format strings which are executed repeatedly
.\" (as with \fIscan\fP), these escapes delimit the main
.\" body of execution.  Format text which occurs
.\" before the '%[' escape is executed once only, prior
.\" to processing the first message; format text occuring
.\" after the '%]' escape is ignored.
.\" (These escapes may not be nested).
.\" 
.Uh "Function escapes"
.ne 10
Most functions expect an argument of a particular type:
.sp 1
.nf
.ta +\w'Argument 'u +\w'An optional component, 'u
\fIArgument\fR  \fIDescription\fR       \fIExample Syntax\fR
literal A literal number,       %(\fIfunc\fR 1234)
        or string       %(\fIfunc\fR text string)
comp    Any header component    %(\fIfunc\fR\^{\fIin-reply-to\fR\^})
date    A date component        %(\fIfunc\fR\^{\fIdate\fR\^})
addr    An address component    %(\fIfunc\fR\^{\fIfrom\fR\^})
expr    An optional component,  %(\fIfunc\fR\^(\fIfunc2\fR\^))
        function or control,    %(\fIfunc\fR %<{\fIreply-to\fR\^}%|%{\fIfrom\fR\^}%>)
        perhaps nested  %(\fIfunc\fR\^(\fIfunc2\fR\^{\fIcomp\fR\^}))
.re
.fi

The types \fIdate\fR and \fIaddr\fR have the same syntax
as \fIcomp\fR, but require that the header 
component be a date string, or address string, respectively.

All arguments except those of type \fIexpr\fR are required.
For the \fIexpr\fR argument type, 
the leading `%' must be omitted for component and function escape arguments,
and must be present (with a leading space) for control escape arguments.

The evaluation of format strings
is based on a simple machine with an
integer register \fInum\fR, and a text string register \fIstr\fR.
When a function escape is processed,
if it accepts an optional \fIexpr\fR argument which is not present, 
it reads the current value of either \fInum\fR or \fIstr\fR as appropriate.

.\" return values
.Uh "Return values"
Component escapes write the value of their message header in \fIstr\fR.
Function escapes write their return value in
\fInum\fR for functions returning \fIinteger\fR or \fIboolean\fR values,
and in \fIstr\fR for functions returning string values.
(The \fIboolean\fR type is a subset of integers with usual
values 0=false and 1=true.)
Control escapes return a \fIboolean\fP value, and set \fInum\fP.

All component escapes, and those
function escapes which return an \fIinteger\fR or \fIstring\fR value,
pass this value back to their caller
in addition to setting \fIstr\fR or \fInum\fR.
These escapes will print out this value
unless called as part of an argument to another escape sequence.
Escapes which return a \fIboolean\fR value do pass this value
back to their caller in \fInum\fP, but will never print out the value.

.nf
.ta \w'Formataddr 'u +\w'Argument 'u +\w'Rboolean 'u
\fIFunction\fR  \fIArgument\fR  \fIReturn\fR    \fIDescription\fR
msg             integer message number
cur             integer message is current
.\" unseen              integer message is unseen
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
lit     literal string  Set \fIstr\fR to \fIarg\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 \fInum\fR set to \*(lq\fBatoi\fR(\fIcomp\fR\^)\*(rq
.\" compflag    comp    integer Set \fInum\fR to component flags bits (internal)
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)
.re     
.fi

These functions require a date component as an argument:
.sp 1
.nf
.ta \w'Formataddr 'u +\w'Argument 'u +\w'Rboolean 'u
\fIFunction\fR  \fIArgument\fR  \fIReturn\fR    \fIDescription\fR
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?
                        (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?
                        (0=implicit,\-1=unknown)
date2local      date            coerce date to local timezone
date2gmt        date            coerce date to GMT
dst     date    integer daylight savings in effect?
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
nodate  date    integer \fIstr\fR not a date string
.re     
.fi

.ne 12
These functions require an address component as an argument.  
The return value of functions noted with `*' pertain only to
the first address present in the header component.
.sp 1
.nf
.ta \w'Formataddr 'u +\w'Argument 'u +\w'Rboolean 'u
\fIFunction\fR  \fIArgument\fR  \fIReturn\fR    \fIDescription\fR
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 the user's addresses? (0=no,1=yes)
host    addr    string  the host domain*
nohost  addr    integer no host was present*
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*
gname   addr    string  name of group*
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
.re     
.fi

When escapes are nested, evaluation is done from inner-most to outer-most.
The outer-most escape must begin with `%'; the inner escapes must not.
For example,

.ti +.5i
%<(mymbox{from}) To: %{to}%>

writes the value of the header component \*(lqFrom:\*(rq to \fIstr\fR\^;
then (\fImymbox\fR\^) reads \fIstr\fR 
and writes its result to \fInum\fR;
then the control escape evaluates \fInum\fR.  If \fInum\fR is
non-zero, the string \*(lqTo: \*(rq is printed followed by
the value of the header component \*(lqTo:\*(rq.

A minor explanation of (\fImymbox\fR\^{\fIcomp\fR\^}) is in order.
In general, it checks each of the addresses in the header component
\*(lq\fIcomp\fR\*(rq
against the user's mailbox name and any \fIAlternate-Mailboxes\fR.
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 condition.

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.

As above,
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\^) print their result in
the minimum number of characters required, and ignore any leading 
field width argument.

The available output width is kept in an internal register; any output past
this width will be truncated.

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.

With all this in mind,
here's the default format string for \fIscan\fR.
It's been divided into several pieces for readability.
The first part is:

.ti +.5i
%4(msg)%<(cur)+%| %>%<{replied}\-%?{encrypted}E%| %>

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,
and 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:

.ti +.5i
%02(mon{date})/%02(mday{date})

the month and date are printed in two digits (zero filled) separated by
a slash.
Next,

.ti +.5i
%<{date} %|*>

If a \*(lqDate:\*(rq field was present,
then a space is printed, otherwise a `*'.
Next,

.ti +.5i
%<(mymbox{from})%<{to}To:%14(friendly{to})%>%>

if the message is from me,
and there is a \*(lqTo:\*(rq header,
print `To:' followed by a \*(lquser-friendly\*(rq rendering of the 
first address in the \*(lqTo:\*(rq field.
Continuing,

.ti +.5i
%<(zero)%17(friendly{from})%>

if either of the above two tests failed,
then the \*(lqFrom:\*(rq address is printed
in a \*(lquser-friendly\*(rq format.
And finally,

.ti +.5i
%{subject}%<{body}<<%{body}%>

the subject and initial body (if any) are printed.

For a more complicated example, next consider
the default \fIreplcomps\fR format file.

.ti +.5i
%(lit)%(formataddr %<{reply-to}

This clears \fIstr\fR and formats the \*(lqReply-To:\*(rq header 
if present.  If not present, the else-if clause is executed.

.ti +.5i
%?{from}%?{sender}%?{return-path}%>)\\

This formats the 
\*(lqFrom:\*(rq, \*(lqSender:\*(rq and \*(lqReturn-Path:\*(rq
headers, stopping as soon as one of them is present.  Next:

.ti +.5i
%<(nonnull)%(void(width))%(putaddr To: )\\n%>\\

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.

.ti +.5i
%(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\\

\fIstr\fR 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.

.ti +.5i
%<(nonnull)%(void(width))%(putaddr cc: )\\n%>\\

If the result is non-null, it is printed as above with a
leading label of \*(lqcc: \*(rq.

.ti +.5i
%<{fcc}Fcc: %{fcc}\\n%>\\

If a \*(lq\-fcc\ folder\*(rq switch was given to \fIrepl\fR
(see \fIrepl\fR\0(1) for more details about %{\fIfcc\fR\^}),
an \*(lqFcc:\*(rq header is output.

.ti +.5i
%<{subject}Subject: Re: %{subject}\\n%>\\

If a subject component was present,
a suitable reply subject is output.

.nf
.ti +.5i
%<{date}In-reply-to: Your message of "\\
.ti +.5i
%<(nodate{date})%{date}%|%(pretty{date})%>."%<{message-id}
.ti +.5i
             %{message-id}%>\\n%>\\
.ti +.5i
\-\-\-\-\-\-\-\-
.fi

If a date component was present,
an \*(lqIn-Reply-To:\*(rq header is output with the preface
\*(lqYour message of \*(rq.  If the date was parseable, it is
output in a user-friendly format, otherwise it is output as-is.
The message-id is included if present.
As with all plain-text,
the row of dashes are output as-is.

This last part is a good example for a little more elaboration.
Here's that part again in pseudo-code:
.sp 1
.nf
.in +.5i
.ta .5i 1i 1.5i 2i
if (comp_exists(date))  then
        print (\*(lqIn-reply-to: Your message of \\\*(lq\*(rq)
        if (not_date_string(date.value) then
                print (date.value)
        else
                print (pretty(date.value))
        endif
        print (\*(lq\\\*(rq\*(rq)
        if (comp_exists(message-id)) then
                print (\*(lq\\n\\t\*(rq)
                print (message-id.value)
        endif
        print (\*(lq\\n\*(rq)
endif
.re
.in -.5i
.fi
.sp 1
Although this seems complicated,
in point of fact,
this method is flexible enough to extract individual fields and print them in
any format the user desires.
.Fi
None
.Pr
None
.Sa
scan(1), repl(1), ap(8), dp(8)
.De
None
.Co
None
.Hi
This software was contributed for MH 6.3.  Prior to this, output
format specifications were much easier to write, but considerably
less flexible.
.Bu
On hosts where \fIMH\fR was configured with the BERK option,
address parsing is not enabled.
.En
@


1.46
log
@think about documenting %[ %]
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.45 1993/08/19 20:26:17 jromine Exp jromine $
d38 2
@


1.45
log
@re-describe "profile"
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.44 1993/06/12 06:49:57 jromine Exp jromine $
d60 1
d132 9
d227 1
a227 1
.\" compflag    comp    integer Set \fInum\fR to component flags bits
@


1.44
log
@document %(profile xxx)
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.43 1992/12/02 18:41:50 jromine Exp jromine $
d208 1
a208 1
profile literal string  Set \fIstr\fR to value of profile or context \fIarg\fR
@


1.43
log
@typo
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.42 1992/11/20 19:35:06 jromine Exp jromine $
d208 1
@


1.42
log
@format typo
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.41 1992/10/28 23:03:14 jromine Exp jromine $
d348 1
a348 1
is not expected.  A comment line begins with `%;' and ends with
@


1.41
log
@make scan/repl strings match actual defaults
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.40 1992/10/27 00:20:03 jromine Exp jromine $
d297 1
a297 1
writes the value of the header component \*(lqFrom:\*(rq to \fIstr\fR;
@


1.40
log
@typos; fixups
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.39 1992/10/26 17:03:42 jromine Exp jromine $
d352 1
a352 1
here's a format string for \fIscan\fR.
d357 1
a357 1
%4(msg)%<(cur)+%| %>%<{replied}\-%| %>
d362 3
a364 2
and if a \*(lqReplied:\*(rq field is present then a `\-' else a space should
be printed.
@


1.39
log
@fixup typos (from Jerry Peek)
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.38 1992/05/12 22:23:34 jromine Exp jromine $
d352 1
a352 1
here's the default format string for \fIscan\fR.
d457 1
a457 1
%<(nodate{date})%{date}%|%(tws{date})%>."%<{message-id}
d467 1
a467 1
output in official format, otherwise it is output as-is.
@


1.38
log
@fixup for nroff problems
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.37 1992/02/18 17:28:26 jromine Exp jromine $
d40 1
a40 1
header \fIcomponents\fR, built-in \fIfunctions\fR, and, flow \fIcontrol\fR.
d102 2
a103 2
all format text up to the corresponding `%>' control
escape (if any) is skipped.
d483 1
a483 1
                print (rfc822(date.value))
@


1.37
log
@undocument unseen
@
text
@d2 2
a3 2
.\" @@(#)$Id: mh-format.rf,v 1.36 1992/02/14 19:14:42 jromine Exp jromine $
.SC MH\-FORMAT 5
d5 1
a5 1
mh\-format \- format file for MH message system
@


1.36
log
@fix compval
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.35 1992/02/11 05:03:41 jromine Exp jromine $
d189 1
a189 1
unseen          integer message is unseen
@


1.35
log
@document unseen
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.34 1992/02/09 22:11:10 jromine Exp jromine $
d215 1
a215 1
compval comp    integer \fInum\fR set to \*(lq\fBatoi\fR(\fIstr\fR\^)\*(rq
@


1.34
log
@document control escape return values
put new scan.default and replcomps format strings in.
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.33 1992/02/09 07:18:01 jromine Exp jromine $
d189 1
@


1.33
log
@add modulo
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.32 1992/02/07 01:08:25 jromine Exp jromine $
d173 1
d181 2
a182 2
Function escapes which return a \fIboolean\fR value do pass this value
back to their caller, but will never print out the value.
d221 1
a221 1
.\" addtoseq literal    add msg to sequence
d346 4
d380 1
a380 1
%<(mymbox{from})To:%14(friendly{to})
d383 1
d389 1
a389 1
%|%17(friendly{from})%>
d391 3
a393 2
if the message isn't from me,
then the print the \*(lqFrom:\*(rq address is printed.
d405 1
a405 1
%(lit)%(formataddr %<{reply-to}%|
d408 1
a408 1
if present.  If not present, the else clause is executed:
d411 1
a411 1
%<{from}%|%<{sender}%|%<{return-path}%>%>%>%>)\\
@


1.32
log
@date/year
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.31 1992/02/06 00:13:07 jromine Exp jromine $
d202 1
d206 1
a206 1
.\" dat literal int     ?
d220 1
@


1.31
log
@remove putstr[f] -- they're not in the default file
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.30 1992/01/29 22:55:31 jromine Exp jromine $
d240 1
a240 1
year    date    integer year of the century
@


1.30
log
@document getenv
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.29 1991/01/11 09:17:35 mh Exp jromine $
d349 1
a349 1
%4(putnumf(msg))%<(cur)+%| %>%<{replied}\-%| %>
d359 1
a359 1
%02(putnumf(mon{date}))/%02(putnumf(mday{date}))
d373 1
a373 1
%<(mymbox{from})To:%14(putstrf(friendly{to}))
d381 1
a381 1
%|%17(putstrf(friendly{from}))%>
@


1.29
log
@change "\-" to "-" where appropriate
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.28 91/01/11 09:15:19 mh Exp Locker: mh $
d204 1
@


1.28
log
@add "elseif" documentation
jlr
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.27 90/12/27 17:22:27 mh Exp Locker: mh $
d32 1
a32 1
multi\-character \fIescape\fR sequences which begin with `%'.
d40 1
a40 1
header \fIcomponents\fR, built\-in \fIfunctions\fR, and, flow \fIcontrol\fR.
d205 1
a205 1
nonzero expr    boolean \fInum\fR is non\-zero
d208 1
a208 1
nonnull expr    boolean \fIstr\fR is non\-empty
d213 1
a213 1
trim    expr            trim trailing white\-space from \fIstr\fR
d250 1
a250 1
pretty  date    string  user\-friendly rendering
d264 1
a264 1
friendly        addr    string  user\-friendly rendering
d375 1
a375 1
print `To:' followed by a \*(lquser\-friendly\*(rq rendering of the 
d410 1
a410 1
If the \fIformataddr\fR result is non\-null, it is printed as
d426 1
a426 1
If the result is non\-null, it is printed as above with a
d456 1
a456 1
output in official format, otherwise it is output as\-is.
d458 2
a459 2
As with all plain\-text,
the row of dashes are output as\-is.
d462 1
a462 1
Here's that part again in pseudo\-code:
@


1.27
log
@document "addr" format
jlr
@
text
@d2 1
a2 1
.\" @@(#)$Id: mh-format.rf,v 1.26 90/04/05 15:09:13 sources Exp Locker: mh $
d55 1
a55 1
All functions are built\-in, and most have a string or numeric value.
d57 5
a61 5
.ne 7
A \fIcontrol\fR escape is one of: `%<', `%|', or `%>'.
These form one of four conditional execution constructs with the
following syntax:
.sp 1
d63 10
a72 4
        %<(\fIfunction\fR\^)Command-String%>
        %<{\fIcomponent\fR\^}Command-String%>
        %<(\fIfunction\fR\^)Then-Command-String%|Else-Command-String%>
        %<{\fIcomponent\fR\^}Then-Command-String%|Else-Command-String%>
d75 1
d77 2
d80 15
a94 6
In the first two forms of the construct,
if the function or component value is non\-zero (for integer\-valued escapes),
or non\-empty (for string\-valued escapes),
then everything up to the corresponding `%>'
is interpreted, otherwise, skip to the corresponding '%>' and
start interpreting again.
d96 11
a106 7
In the second two forms of the construct, 
the first command string is interpreted
if the function or component value is non\-zero or non\-null,
and the second command string is interpreted otherwise.  Only one
of the command strings will be interpreted.
Interpreting the '%|' control escape causes 
a skip to the corresponding '%>'.  
d108 24
d166 1
d290 1
a290 1
%<(mymbox{from} To: %{to}%>
d450 1
a450 1
--------
@


1.26
log
@add ID
@
text
@d2 1
a2 1
.\" @@(#)$Id:$
d218 1
@


1.25
log
@minor revision
@
text
@d2 1
@


1.24
log
@typo
@
text
@d352 1
a352 1
%<{from}%|%<{sender}%|%<{return-path}%>%>%>%>)
d359 1
a359 1
%<(nonnull)%(void(width))%(putaddr To: )\\n%>
d366 1
a366 1
%(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))
d375 1
a375 1
%<(nonnull)%(void(width))%(putaddr cc: )\\n%>
d381 1
a381 1
%<{fcc}Fcc: %{fcc}\\n%>
d388 1
a388 1
%<{subject}Subject: Re: %{subject}\\n%>
d395 1
a395 1
%<{date}In-reply-to: Your message of
d397 1
a397 1
%<(nodate{date})%{date}%|%(tws{date})%>.%<{message-id}
d399 1
a399 1
             %{message-id}%>\\n%>
d412 1
a412 1
This is a good example for a little more elaboration.
d419 1
a419 1
        print (\*(lqIn-reply-to: Your message of \*(rq)
d425 1
@


1.23
log
@typo
@
text
@d243 2
a244 2
writes the value of the header component \fI{from}\fR to \fIstr\fR;
then \fI(mymbox)\fR reads \fIstr\fR 
d248 1
a248 1
the value of the header component \fI{to}\fR.
d256 1
a256 1
in the message.  If needed, the (\fInull\fR) function can be
d263 1
a263 1
For example, a numeric escape like \fI%4(size)\fR will print at most 4
d266 1
a266 1
A string escape like \fI%4(me)\fR will print the first 4 characters and
d273 1
a273 1
the functions \fIputnumf\fR and \fIputstrf\fR print their result in
d286 1
a286 1
The functions \fIputnum\fR and \fIputstr\fR print their result in
d352 1
a352 1
%<{from}%|%<{sender}%|%{return-path}%>%>%>)
d372 1
a372 1
the \*(lq\-cc\*(rq switch to \fIrepl\fR) are formatted.
@


1.22
log
@revised
@
text
@d250 1
a250 1
A minor explanation of (\fImymbox\fR\|{\fIcomp\fR\|}) is in order.
d277 1
a277 1
%06(\fIputnumffR\|(\fIsizefR\|)) will print the message size 
d279 1
a279 1
%14(\fIputstrf\|\fR{\fIfrom\|\fR}) will print
d384 1
a384 1
(see \fIrepl\fR\0(1) for more details about %{\fIfcc\fR\|}),
@


1.21
log
@follow TECO manual description of conditionals
@
text
@d56 4
a59 3
A \fIcontrol\fR escape is one of:
`%<(\fIfunction\fR\^)' or `%<{\fIcomponent\fR\^}', `%|', and `%>'.
These form a conditional execution construct with the following syntax:
d62 4
a65 3
        %<\fIescape\fR command-string %>
or
        %<\fIescape\fR then-command-string %| else-command-string %>
d70 1
a70 1
In the first form of the construct,
d77 1
a77 1
In the second form of the construct, 
d167 1
a167 1
putstrf expr            print \fIstr\fR in fixed width
d169 1
a169 1
putnumf expr            print \fInum\fR in fixed width
d259 4
a262 2
When a function escape is interpreted, an optional output width can be
specified to limit the field width to a maximum number of characters.
d267 4
a270 1
truncate at the end.
d272 6
a277 3
The functions \fIputnumf\fR and \fIputstrf\fR print their result in
exactly the number of characters specified.  For example,
\fI%06(putnumf(size))\fR will print the message size 
d279 1
a279 1
\fI%14(putstrf{from})\fR will print
d282 7
@


1.20
log
@put things back, do .NA stuff another way
@
text
@d57 13
a69 4
`%<(\fIfunction\fR\^)' or `%<{\fIcomponent\fR\^}', `%|', and `%>',
which correspond to if\-then\-else constructs.
They may be nested without ambiguity.
If the function or component value is non\-zero (for integer\-valued escapes),
d71 11
a81 4
then everything up to the corresponding `%|' or `%>'
(whichever comes first) is interpreted;
otherwise, skip to the corresponding `%|' or `%>' (whichever comes first)
and start interpreting again.
@


1.19
log
@add example pseudo-code from Phyllis Kantar
@
text
@d2 2
a3 2
.TH MH\-FORMAT 5 @@(MHCENTERFOOT) @@(MHLEFTFOOT)
.SH .NA
d5 1
a5 1
.SH .SY
@


1.18
log
@typo
@
text
@d373 1
a373 1
\*(lqYour message of\*(rq.  If the date was parseable, it is
d379 23
@


1.17
log
@fixup for makewhatis
@
text
@d2 1
a2 1
.TH MH\-FORMAT 5 [mh.6] MH
@


1.16
log
@more fixes from Phyllis Kantar
@
text
@d2 2
a3 2
.SC MH\-FORMAT 5
.NA
d5 1
a5 1
.SY
@


1.15
log
@fix some typos
@
text
@d58 3
a60 2
which correspond to if\-then\-else constructs:
if the function or component value is non\-zero (for integer\-valued escapes),
d62 3
a64 2
then everything up to `%|' or `%>' (whichever comes first) is interpreted;
otherwise, then skip to `%|' or `%>' (whichever comes first)
d202 1
a202 1
mymbox  addr    integer the user's mailbox? (0=no,1=yes)
d226 2
a227 1
then \fI(mymbox)\fR reads \fIstr\fR and writes its result to \fInum\fR;
d232 9
d278 2
a279 1
the month and date are printed in two digits (zero filled).
d285 2
a286 2
If no \*(lqDate:\*(rq field was present,
then a `*' is printed, otherwise a space.
d350 2
a351 1
If a \*(lq\-fcc\ folder\*(rq switch was given,
d357 2
a358 1
A suitable reply subject is output.
d371 6
a376 2
If a date was present,
An \*(lqIn-Reply-To:\*(rq header is output.  As with all plain\-text,
d388 1
a388 1
ap(8), dp(8)
@


1.14
log
@mention component compression
@
text
@d147 1
a147 1
putstrf expr            print \fIstr\fR in fixed width.
d149 1
a149 1
putnumf expr            print \fInum\fR in fixed width.
d159 1
a159 1
min     date    integer minutes of the day
d174 1
a174 1
zsone   date    integer timezone explicit?
d332 1
a332 1
leading lable of \*(lqcc: \*(rq.
d337 2
a338 1
If a \*(lq\-fcc\*(rq switch was given, an \*(lqFcc:\*(rq header is output.
d352 2
d357 2
a358 1
An \*(lqIn-Reply-To:\*(rq header is output.  
@


1.13
log
@remove some info about repl - complete details in repl(1).
@
text
@d46 5
a50 1
Different commands may interpret some component escapes differently; 
@


1.12
log
@suggest referencing command man pages for more details
@
text
@d293 1
a293 2
the default \fIreplcomps\fR format file.  \fIrepl\fR
resets the line width each time after printing a `\\n'.
d338 1
a338 2
If a subject was present, it is output prefaced with \*(lqRe: \*(rq.
(The \fI{subject}\fR component has any leading \*(lqRe: \*(rq stripped).
d349 2
a350 2
An \*(lqIn-Reply-To:\*(rq header is output.  If a date was present,
it is included with the preface \*(lqYour message of \*(rq.
@


1.11
log
@indicate which {addr} funcs return value for first addr only'\7f
@
text
@d46 2
@


1.10
log
@document "trim"
@
text
@d182 3
a184 1
These functions require an address component as an argument:
d191 3
a193 3
pers    addr    string  the personal name 
note    addr    string  commentary text
mbox    addr    string  the local mailbox 
d195 3
a197 3
host    addr    string  the host domain 
nohost  addr    integer no host was present
type    addr    integer host type (0=local,1=network,
d199 3
a201 4
path    addr    string  any leading host route
ingrp   addr    integer address was inside a group
gname   addr    string  name of group
                        (set for first address only)
@


1.9
log
@minor fixup
@
text
@d139 1
@


1.8
log
@final.  this is a major revision -- i hope it was worth it.
/JLR
@
text
@d28 1
a58 11
.\" Some functions expect an extra literal string or integer parameter,
.\" and are specified as `%(\fIfunction\fR argument)'.
.\" Many functions require a component argument, and are
.\" specified as `%(\fIfunction\fR\^{\fIcomponent\fR\^})'.
.\" Some functions will accept another function as an argument.  These
.\" may be nested, and are evaluated inner\-most to outer\-most.
.\" This nesting is specified as `%(\fIfunction2\fR\^(\fIfunction1\fR\^))'.
.\" If a function accepts an argument, it is of
.\" one of these six types: \fIint\fR\^, 
.\" \fIstring\fR\^, \fIcomp\fR\^, \fIexpr\fR\^,
.\" \fIdate\fR\^, and \fIaddr\fR\^.
d146 2
a147 3
These functions require a date header component as an argument:
.\" When \fIstr\fR is a date, these escapes are useful:

d181 1
a181 2
These functions require an address header component as an argument:
.\" When \fIstr\fR is an address, these escapes are useful:
d231 5
a235 3
\fI%6(putnumf(size))\fR will print the message size right\-justified 
in a field six characters wide; \fI%14(putstrf{from})\fR will print
the \*(lqFrom:\*(rq header component left\-justified in fourteen characters.
d340 1
a340 1
%<{date}In-reply-to: Your message of \\
a353 1

@


1.7
log
@checkpoint before mentioning replcomps
@
text
@d20 5
d27 1
a27 1
This manual section attempts to explain how to do that.
d298 62
a364 6
If the `\-form\ formatfile' switch is given,
\fIscan\fR will treat each line in the named file as a format string and act
accordingly.
This lets the user employ canned scan listing formats.
Take a look at the three files
@@(MHETCPATH)/scan.time, @@(MHETCPATH)/scan.size, and @@(MHETCPATH)/scan.timely.
@


1.6
log
@checkpoint
@
text
@d39 1
a39 1
Component escapes are all string valued.
d41 2
a42 2
A \fIfunction\fR escape is specified as `%(\fIfunction\fR\^)',
and is statically defined.
d47 1
a47 1
if the function or component is non\-zero (for integer\-valued escapes),
d88 1
a88 1
and must be present for control escape arguments.
d102 2
a103 2
(The \fIboolean\fR type is a subset of integers; 0=false and 1=true are
usually the only values.)
d145 1
a145 1
putstrf expr            print using width; \*(lq\fI%20(putstrf)\fR\*(rq
d147 1
a147 1
putnumf expr            print using width; \*(lq\fI%4(putnumf)\fR\*(rq
d228 2
a229 2
When a function escape is interpreted, the output width can be
limited to a maximum number of characters.
d235 6
@


1.5
log
@almost done
@
text
@d35 1
a35 1
A \fIcomponent\fR escape is specified as `%{\fIcomponent\fR\|}',
d41 1
a41 1
A \fIfunction\fR escape is specified as `%(\fIfunction\fR\|)',
d45 1
a45 1
`%<(\fIfunction\fR\|)' or `%<{\fIcomponent\fR\|}', `%|', and `%>',
d56 1
a56 1
.\" specified as `%(\fIfunction\fR\|{\fIcomponent\fR\|})'.
d59 1
a59 1
.\" This nesting is specified as `%(\fIfunction2\fR\|(\fIfunction1\fR\|))'.
d61 3
a63 3
.\" one of these six types: \fIint\fR\|, 
.\" \fIstring\fR\|, \fIcomp\fR\|, \fIexpr\fR\|,
.\" \fIdate\fR\|, and \fIaddr\fR\|.
d72 6
a77 6
comp    Any header component    %(\fIfunc\fR\|{\fIin-reply-to\fR\|})
date    A date component        %(\fIfunc\fR\|{\fIdate\fR\|})
addr    An address component    %(\fIfunc\fR\|{\fIfrom\fR\|})
expr    An optional component,  %(\fIfunc\fR\|(\fIfunc2\fR\|))
        function or control,    %(\fIfunc\fR\|(\fIfunc2\fR\|{\fIcomp\fR\|}))
        perhaps nested  %(\fIfunc\fR %<{\fIreply-to\fR\|}%|%{\fIfrom\fR\|}%>)
d85 5
d97 1
d142 1
a142 1
compval comp    integer \fInum\fR set to \*(lq\fBatoi\fR(\fIstr\fR\|)\*(rq
@


1.4
log
@checkpoint
@
text
@d17 1
a17 1
means they are not necessarily simple for humans to parse.
d26 1
a26 1
When specifying a string,
a30 1

d32 1
a32 2

The \fIescape\fR sequences are of three types:
a59 2

Most functions expect an argument of a particular type:
d64 3
a66 1

d68 10
a77 9
.ta 4 +\w'Argument 'u +\w'a component or function,  'u
        \fIArgument\fR  \fIDescription\fR       \fISyntax\fR
        int     a literal number        %(\fIfunc\fR number)
        string  a literal string        %(\fIfunc\fR text string)
        comp    any header component    %(\fIfunc\fR\|{\fIcomp\fR\|})
        date    a date component        %(\fIfunc\fR\|{\fIdate\fR\|})
        addr    an address component    %(\fIfunc\fR\|{\fIaddr\fR\|})
        expr    a component or function,        %(\fIfunc\fR\|(\fIfunc2\fR\|))
                perhaps nested  %(\fIfunc\fR\|(\fIfunc2\fR\|{\fIcomp\fR\|}))
d81 2
a82 1
The types \fIdate\fR and \fIaddr\fR require that the header 
d89 1
a89 1
if it requires a non\-literal argument,
d92 6
a97 5
Function results are written in
\fInum\fR for \fIint\fR and \fIbool\fR values, or \fIstr\fR 
for string values. (The \fIbool\fR type
is a subset of integers; usually 0=false, 1=true.)
All component escapes set \fIstr\fR with the value of their message header.
d99 8
a106 3
.\" A few function escapes accept a literal string or numeric argument,
.\" but most use the value of \fInum\fR or \fIstr\fR
.\" as their argument if needed.
a107 7
All component escapes, and
nearly all function escapes return a value in addition to setting \fIstr\fR
or \fInum\fR.  These escapes will print out this value
unless called from within another escape sequence.
A few function escapes do not print their results; these are indicated
in the \fIPrint Result?\fR column of the tables below.

d109 34
a142 35
.ta \w'Rbool,no 'u +\w'Formataddr 'u +\w'Argument  'u
\fIReturn\fR    \fIFunction\fR  \fIArgument\fR  \fIDescription\fR
\fIPrint?\fR
int     msg             message number
int     cur             message is current
int     size            size of message
int     strlen          length of \fIstr\fR
int     width           output buffer size in bytes
int     charleft                bytes left in output buffer
int     timenow         seconds since the UNIX epoch
string  me              the user's mailbox
bool,no eq      lit int \fInum\fR == \fIarg\fR
bool,no ne      lit int \fInum\fR != \fIarg\fR
bool,no gt      lit int \fInum\fR > \fIarg\fR
int     plus    lit int \fIarg\fR plus \fInum\fR
int     minus   lit int \fIarg\fR minus \fInum\fR
int     divide  lit int \fInum\fR divided by \fIarg\fR
int     num     lit int Set \fInum\fR to \fIarg\fR
.\" int dat     lit int ?
bool,no match   lit str \fIstr\fR contains \fIarg\fR
bool,no amatch  lit str \fIstr\fR starts with \fIarg\fR
string  lit     lit str Set \fIstr\fR to \fIarg\fR
bool,no nonzero expr    \fInum\fR is non\-zero
bool,no zero    expr    \fInum\fR is zero
bool,no null    expr    \fIstr\fR is empty
bool,no nonnull expr    \fIstr\fR is non\-empty
no      void    expr    Set \fIstr\fR or \fInum\fR
string  comp    comp    Set \fIstr\fR to component text
int     compval comp    \fInum\fR set to \fBatoi\fR of \fIstr\fR
bool    compflag        comp    Set \fInum\fR to component flags bits
        putstr  expr    print \fIstr\fR
        putstrf expr    print using width; \*(lq\fI%20(putstrf)\fR\*(rq
        putnum  expr    print \fInum\fR
        putnumf expr    print using width; \*(lq\fI%4(putnumf)\fR\*(rq
.re
d145 3
a147 1
When \fIstr\fR is a date, these escapes are useful:
d149 9
a157 10
.ta \w'Rbool,no 'u +\w'Formataddr 'u +\w'Argument 'u
\fIReturn\fR    \fIFunction\fR  \fIArgument\fR  \fIDescription\fR
\fIPrint?\fR
int     sec     date    seconds of the minute
int     min     date    minutes of the day
int     hour    date    hours of the day (0-23)
int     wday    date    day of the week (Sun=0)
string  day     date    day of the week (abbrev.)
string  weekday date    day of the week
bool    sday    date    day of the week known?
d159 9
a167 9
int     mday    date    day of the month
int     yday    date    day of the year
int     mon     date    month of the year
string  month   date    month of the year (abbrev.)
string  lmonth  date    month of the year
int     year    date    year of the century
int     zone    date    timezone in hours
string  tzone   date    timezone string
bool    zsone   date    timezone explicit?
d169 9
a177 9
bool    dst     date    daylight savings in effect?
int     clock   date    seconds since the UNIX epoch
int     rclock  date    seconds prior to current time
string  tws     date    official 822 rendering
string  pretty  date    user\-friendly rendering
bool,no nodate  date    \fIstr\fR not a date string
no      date2local      date    coerce date to local timezone
no      date2gmt        date    coerce date to GMT
.re
d180 4
a183 1
When \fIstr\fR is an address, these escapes are useful:
d185 11
a195 12
.ta \w'Rbool,no 'u +\w'Formataddr 'u +\w'Argument 'u
\fIReturn\fR    \fIFunction\fR  \fIArgument\fR  \fIDescription\fR
\fIPrint?\fR
string  proper  addr    official 822 rendering
string  friendly        addr    user\-friendly rendering
string  pers    addr    the personal name 
string  note    addr    commentary text
string  mbox    addr    the local mailbox 
bool    mymbox  addr    is this the user's mailbox?
string  host    addr    the host domain 
bool    nohost  addr    no host was present
bool    type    addr    host type (0=local,1=network,
d197 3
a199 3
string  path    addr    any leading host route
bool    ingrp   addr    address was inside a group
string  gname   addr    name of group
d201 1
a201 1
no      formataddr      expr    append \fIarg\fR to \fIstr\fR as a
d203 1
a203 1
        putaddr lit str print \fIstr\fR address list with
d206 1
a206 1
.re
d211 1
a211 4
For example, \fI%<(mymbox{from} To: %{to}%>\fR writes the value of \fI{from}\f
R
to \fIstr\fR; then \fI(mymbox)\fR reads \fIstr\fR and writes to \fInum\fR;
then the control escape evaluates \fInum\fR.
d213 9
d277 1
a277 1
  %{subject}%<{body}<<%{body}%>
d279 1
a279 1
the subject and initial body are printed.
d302 4
@


1.3
log
@major revision
@
text
@d16 2
a17 2
Format strings are designed to be efficiently parsed by \fIMH\fR since they
represent an integral part of \fIMH\fR.
d19 1
a19 1
deal with them.
d22 1
a22 1
This manual section explains how to do just that.
d24 2
a25 2
A format string is similar to a \fIprintf\fR\0(3) string,
but uses multi\-letter `%'\-escapes.
d29 2
a30 2
Continuation lines in format files end with `\\' followed by the newline
character.
d32 1
a32 8
The interpretation model is based on a simple machine with two registers,
\fInum\fR and \fIstr\fR.
The former contains an integer value, the latter a string value.
When an escape is processed,
if it requires an argument,
it reads the current value of either \fInum\fR or \fIstr\fR;
and,
if it returns a value, it writes either \fInum\fR or \fIstr\fR.
d34 6
a39 5
Escapes are of three types:
\fIcomponents\fR, \fIfunctions\fR, and, \fIcontrol\fR.
A component escape is specified as `%{name}',
and is created for each header found in the message being processed.
For example `%{date} refers to the \*(lqDate:\*(rq field of the appropriate
d41 1
a41 1
A component escape is always string valued.
d43 5
a47 1
A control escape is one of: `%<escape', `%|', and `%>',
d49 1
a49 1
if `escape' is non\-zero (for integer\-valued escapes),
d55 14
a68 5
A function escape is specified as `%(name)',
and is statically defined.
Some function escapes accept an extra literal parameter,
like `%(name literal)'.
Here is the list:
d70 41
a110 1
.ta \w'Rstring 'u +\w'Formataddr 'u +\w'Astring 'u +\w'yes  'u
d112 32
a143 32
\fItype\fR                      \fIPrint?\fR
int     num     int     yes     Set \fInum\fR to \fIarg\fR
string  lit     string  yes     Set \fIstr\fR to \fIarg\fR (could be empty)
        void    expr    no      Set \fIstr\fR or \fInum\fR -- not interpreted
bool    eq      int     no      \fInum\fR == \fIarg\fR
bool    ne      int     no      \fInum\fR != \fIarg\fR
bool    gt      int     no      \fInum\fR > \fIarg\fR
bool    nonzero expr    no      \fInum\fR is non\-zero
bool    zero    expr    no      \fInum\fR is zero
bool    match   string  no      \fIstr\fR contains \fIarg\fR
bool    amatch  string  no      \fIstr\fR starts with \fIarg\fR
bool    null    expr    no      \fIstr\fR is empty
bool    nonnull expr    no      \fIstr\fR is non\-empty
int     plus    int     yes     add \fIarg\fR to \fInum\fR
int     minus   int     yes     subtract \fIarg\fR from \fInum\fR, or change sign
int     divide  int     yes     divide \fInum\fR by \fIarg\fR
int     dat     int     yes     ?
string  comp    comp    yes     ?
int     compval comp    yes     \fInum\fR set to \fBatoi\fR of \fIstr\fR
bool    compflag        comp    yes     NOT WORTH IT?  RETURNS -1 OR 0.?
int     msg             yes     message number
int     cur             yes     message is current
int     size            yes     size of message
int     strlen          yes     length of \fIstr\fR
int     width           yes     size (characters) of output buffer
int     charleft                yes     space left in output buffer
int     timenow         yes     seconds since the UNIX epoch
string  me              yes     the user's mailbox
        putstr  expr    yes     print \fIstr\fR
        putstrf expr    yes     print using width; \*(lq\fI%20(putstrf)\fR\*(rq
        putnum  expr    yes     print \fInum\fR
        putnumf expr    yes     print using width; \*(lq\fI%4(putnumf)\fR\*(rq
d149 1
a149 1
.ta \w'Rstring 'u +\w'Formataddr 'u +\w'Astring 'u +\w'yes  'u
d151 27
a177 23
\fItype\fR                      \fIPrint?\fR
int     sec     date    yes     seconds of the minute
int     min     date    yes     minutes of the day
int     hour    date    yes     hours of the day (24 hour clock)
int     wday    date    yes     day of the week (Sun=0)
string  day     date    yes     day of the week (3 character abbrev.)
string  weekday date    yes     day of the week (long form)
bool    sday    date    yes     day of the week known (0=implicit,\-1=unknown)
int     mday    date    yes     day of the month
int     yday    date    yes     day of the year
int     mon     date    yes     month of the year
string  month   date    yes     month of the year (3 character abbrev.)
string  lmonth  date    yes     month of the year (long form)
int     year    date    yes     year of the century
int     zone    date    yes     timezone in hours
string  tzone   date    yes     timezone string
bool    zsone   date    yes     timezone explicit (0=implicit,\-1=unknown)
bool    dst     date    yes     daylight savings in effect
int     clock   date    yes     seconds since the UNIX epoch
int     rclock  date    yes     seconds prior to current time
string  tws     date    yes     official 822 rendering of the date
string  pretty  date    yes     a more user\-friendly rendering
bool    nodate  date    no      string not parseable as a date
d183 1
a183 1
.ta \w'Rstring 'u +\w'Formataddr 'u +\w'Astring 'u +\w'yes  'u
d185 20
a204 17
\fItype\fR                      \fIPrint?\fR
string  pers    addr    yes     the personal name of the address
string  mbox    addr    yes     the local part of the address
string  host    addr    yes     the domain part of the address
string  path    addr    yes     the route part of the address
int     type    addr    yes     host type (\-1=uucp,0=local,1=network,2=unknown)
bool    nohost  addr    yes     no host was present in the address
bool    ingrp   addr    yes     the address appeared inside a group
string  gname   addr    yes     name of the group (set for first address only)
string  note    addr    yes     commentary text
string  proper  addr    yes     official 822 rendering of the address
string  friendly        addr    yes     a more user\-friendly rendering
bool    mymbox  addr    yes     the address refers to the user's mailbox
        formataddr      expr    no      append \fIarg\fR to \fIstr\fP as an address list
        putaddr string  yes     print stored address list with \fIarg\fR as
                                optional label; get line width from \fInum\fR
                                EXAMPLE: \fI%(void(width))%(putaddr Cc: )\fR
@


1.2
log
@changes from Jerry Peek
@
text
@d59 2
a60 3
Some function escapes accept an extra literal parameter, like `%(name literal)
';
these are shown in the list below as \fIL\fR.
d63 34
a96 39
.ta \w'formataddr  'u +\w'argument  'u +\w'returns  'u
\fIescape\fR    \fIargument\fR  \fIreturns\fR   \fIinterpretation\fR
nonzero integer integer \fInum\fR is non\-zero
zero    integer integer \fInum\fR is zero
eq \fIL\fR      integer integer \fInum\fR == \fIL\fR
ne \fIL\fR      integer integer \fInum\fR != \fIL\fR
gt \fIL\fR      integer integer \fInum\fR > \fIL\fR
num \fIL\fR             integer put \fIL\fR into \fInum\fR
dat     ?       ?       ?
null    string  integer \fIstr\fR is empty
nonnull string  integer \fIstr\fR is non\-empty
match \fIL\fP   string  integer \fIstr\fR contains \fIL\fR
amatch \fIL\fR  string  integer \fIstr\fR starts with \fIL\fR
compval string  integer set \fIint\fR to number at start of \fIstr\fR
                        (EXAMPLE: if \fIstr\fR is \fI20 Nov 89\fR,
                        \fInum\fR would be set to 20.)???
compflag        string  integer NOT WORTH IT?  RETURNS -1 OR 0.?
void    integer integer Do not interpret; just put in \fIint\fR
                        (EXAMPLE: \fI%(void(rclock{date}))\fR puts
                        \fIrclock\fR value into \fIint\fR)
void    string  string  Do not interpret; just put in \fIstr\fR
putstr  string          print \fIstr\fR
putstrf string          print \fIstr\fR in the specified width
                        (e.g., %20(putstrf{subject})
putnum  integer         print \fInum\fR
putnumf integer         print \fInum\fR in the specified width
                        (e.g., %4(putnumf(msg))
msg             integer message number
cur             integer message is current
size            integer size of message
strlen  string  integer length of \fIstr\fR
me              string  the user's mailbox
plus \fIL\fR            integer add \fIL\fR to \fInum\fR
minus \fIL\fR           integer subtract \fIL\fR from \fInum\fR, then change si
gn
                        EXAMPLES: \fI%(void(minus))\fR, \fI%(void(minus 25))\fR
width           integer size (characters) of output buffer
charleft                integer space left in output buffer
timenow         integer seconds since the UNIX epoch
d102 25
a126 26
.ta \w'formataddr  'u +\w'argument  'u +\w'returns  'u
\fIescape\fR    \fIargument\fR  \fIreturns\fR   \fIinterpretation\fR
sec     string  integer seconds of the minute
min     string  integer minutes of the day
hour    string  integer hours of the day (24 hour clock)
mday    string  integer day of the month
mon     string  integer month of the year
wday    string  integer day of the week (Sunday=0)
year    string  integer year of the century
yday    string  integer day of the year
dst     string  integer daylight savings in effect
zone    string  integer timezone
sday    string  integer day of the week known
                        1 for explicit in date
                        0 for implicit (\fIMH\fR figured it out)
                        \-1 for unknown (\fIMH\fR couldn't figure it out)
clock   string  integer seconds since the UNIX epoch
rclock  string  integer seconds prior to current time
month   string  string  month of the year
lmonth  string  string  month of the year (long form)
tzone   string  string  timezone
day     string  string  day of the week
weekday string  string  day of the week (long)
tws     string  string  official 822 rendering of the date
pretty  string  string  a more user\-friendly rendering
nodate  string          date wasn't parseable
d132 19
a150 27
.ta \w'formataddr  'u +\w'argument  'u +\w'returns  'u
\fIescape\fR    \fIargument\fR  \fIreturns\fR   \fIinterpretation\fR
pers    string  string  the personal name of the address
mbox    string  string  the local part of the address
host    string  string  the domain part of the address
path    string  string  the route part of the address
type    string  integer the type of host
                        \-1 for uucp
                        0 for local
                        1 for network
                        2 for unknown
nohost  string  integer no host was present in the address
ingrp   string  integer the address appeared inside a group
gname   string  string  name of the group (present for first
                        address only)
note    string  string  commentary text
proper  string  string  official 822 rendering of the address
friendly        string  string  a more user\-friendly rendering
mymbox  string          the address refers to the user's mailbox
formataddr      string          append \fIL\fR to \fIstr\fP as an address list
                        (if \fIstr\fR wasn't empty, add comma and space before)
putaddr \fIL\fR                 print stored address list;
                        \fIL\fR is optional label;
                        get line width from \fInum\fR
                        EXAMPLE: \fI%(void(width))%(putaddr Cc: )\fR
lit \fIL\fP             string  Put \fIL\fR into \fIstr\fR
                        (if no \fIL\fR, empty \fIstr\fR)
@


1.1
log
@Initial revision
@
text
@d59 3
d68 5
a72 3
eq      integer integer \fInum\fR == width
ne      integer integer \fInum\fR != width
gt      integer integer width > \fInum\fR
d75 10
d96 5
a100 2
plus            integer add width to \fInum\fR
minus           integer subtract \fInum\fR from width
d158 8
a165 1
formataddr      string          print \fIstr\fR in an address list
d169 18
d205 1
a205 1
the hours and minutes are printed in two digits (zero filled).
d231 1
a231 1
%{subject}%<{body}<<%{body}%>
@