Return to mh-format.rf CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / mh / conf / doc

Annotation of 43BSDReno/contrib/mh/conf/doc/mh-format.rf, revision 1.1

1.1     ! root        1: .\"    @(MHWARNING)
        !             2: .TH MH\-FORMAT 5 "November 30, 1989" MH [mh.6]
        !             3: .UC 6
        !             4: .SH NAME
        !             5: mh\-format \- format file for MH message system
        !             6: .SH SYNOPSIS
        !             7: .in +.5i
        !             8: .ti -.5i
        !             9: some \fIMH\fR commands
        !            10: .in -.5i
        !            11: .SH DESCRIPTION
        !            12: Several \fIMH\fR commands utilize either a \fIformat\fR string or a
        !            13: \fIformat\fR file during their execution.
        !            14: For example,
        !            15: \fIscan\fR\0(1) uses a format string which directs it how to generate the
        !            16: scan listing for each message;
        !            17: \fIrepl\fR\0(1) uses a format file which directs it how to generate the
        !            18: reply to a message, and so on.
        !            19: 
        !            20: Format strings are designed to be efficiently parsed by \fIMH\fR since they
        !            21: represent an integral part of \fIMH\fR.
        !            22: This means that novice, casual, or even advanced users of \fIMH\fR should
        !            23: deal with them.
        !            24: It suffices to have your local \fIMH\fR expert actually write new format
        !            25: commands or modify existing ones.
        !            26: This manual section explains how to do just that.
        !            27: 
        !            28: A format string is similar to a \fIprintf\fR\0(3) string,
        !            29: but uses multi\-letter `%'\-escapes.
        !            30: When specifying a string,
        !            31: the usual C backslash characters are honored:
        !            32: `\\b', `\\f', `\\n', `\\r', and `\\t'.
        !            33: Continuation lines in format files end with `\\' followed by the newline
        !            34: character.
        !            35: 
        !            36: The interpretation model is based on a simple machine with two registers,
        !            37: \fInum\fR and \fIstr\fR.
        !            38: The former contains an integer value, the latter a string value.
        !            39: When an escape is processed,
        !            40: if it requires an argument,
        !            41: it reads the current value of either \fInum\fR or \fIstr\fR;
        !            42: and,
        !            43: if it returns a value, it writes either \fInum\fR or \fIstr\fR.
        !            44: 
        !            45: Escapes are of three types:
        !            46: \fIcomponents\fR, \fIfunctions\fR, and, \fIcontrol\fR.
        !            47: A component escape is specified as `%{name}',
        !            48: and is created for each header found in the message being processed.
        !            49: For example `%{date} refers to the \*(lqDate:\*(rq field of the appropriate
        !            50: message.
        !            51: A component escape is always string valued.
        !            52: 
        !            53: A control escape is one of: `%<escape', `%|', and `%>',
        !            54: which correspond to if\-then\-else constructs:
        !            55: if `escape' is non\-zero (for integer\-valued escapes),
        !            56: or non\-empty (for string\-valued escapes),
        !            57: then everything up to `%|' or `%>' (whichever comes first) is interpreted;
        !            58: otherwise, then skip to `%|' or `%>' (whichever comes first)
        !            59: and start interpreting again.
        !            60: 
        !            61: A function escape is specified as `%(name)',
        !            62: and is statically defined.
        !            63: Here is the list:
        !            64: .nf
        !            65: .ta \w'formataddr  'u +\w'argument  'u +\w'returns  'u
        !            66: \fIescape\fR   \fIargument\fR  \fIreturns\fR   \fIinterpretation\fR
        !            67: nonzero        integer integer \fInum\fR is non\-zero
        !            68: zero   integer integer \fInum\fR is zero
        !            69: eq     integer integer \fInum\fR == width
        !            70: ne     integer integer \fInum\fR != width
        !            71: gt     integer integer width > \fInum\fR
        !            72: null   string  integer \fIstr\fR is empty
        !            73: nonnull        string  integer \fIstr\fR is non\-empty
        !            74: putstr string          print \fIstr\fR
        !            75: putstrf        string          print \fIstr\fR in the specified width
        !            76:                        (e.g., %20(putstrf{subject})
        !            77: trim   string  string  remove leading and trailing white space
        !            78:                        and optionally limit width
        !            79: putnum integer         print \fInum\fR
        !            80: putnumf        integer         print \fInum\fR in the specified width
        !            81:                        (e.g., %4(putnumf(msg))
        !            82: msg            integer message number
        !            83: cur            integer message is current
        !            84: size           integer size of message
        !            85: strlen string  integer length of \fIstr\fR
        !            86: me             string  the user's mailbox
        !            87: plus           integer add width to \fInum\fR
        !            88: minus          integer subtract \fInum\fR from width
        !            89: divide         integer divide width by \fInum\fR
        !            90: charleft               integer space left in output buffer
        !            91: timenow                integer seconds since the UNIX epoch
        !            92: .re
        !            93: .fi
        !            94: 
        !            95: When \fIstr\fR is a date, these escapes are useful:
        !            96: .nf
        !            97: .ta \w'formataddr  'u +\w'argument  'u +\w'returns  'u
        !            98: \fIescape\fR   \fIargument\fR  \fIreturns\fR   \fIinterpretation\fR
        !            99: sec    string  integer seconds of the minute
        !           100: min    string  integer minutes of the day
        !           101: hour   string  integer hours of the day (24 hour clock)
        !           102: mday   string  integer day of the month
        !           103: mon    string  integer month of the year
        !           104: wday   string  integer day of the week (Sunday=0)
        !           105: year   string  integer year of the century
        !           106: yday   string  integer day of the year
        !           107: dst    string  integer daylight savings in effect
        !           108: zone   string  integer timezone
        !           109: sday   string  integer day of the week known
        !           110:                        1 for explicit in date
        !           111:                        0 for implicit (\fIMH\fR figured it out)
        !           112:                        \-1 for unknown (\fIMH\fR couldn't figure it out)
        !           113: clock  string  integer seconds since the UNIX epoch
        !           114: rclock string  integer seconds prior to current time
        !           115: month  string  string  month of the year
        !           116: lmonth string  string  month of the year (long form)
        !           117: tzone  string  string  timezone
        !           118: szone  string  integer timezone known
        !           119:                        1 for explicit in date
        !           120:                        \-1 for unknown
        !           121: day    string  string  day of the week
        !           122: weekday        string  string  day of the week (long)
        !           123: tws    string  string  official 822 rendering of the date
        !           124: pretty string  string  a more user\-friendly rendering
        !           125: nodate string          date wasn't parseable
        !           126: date2local     string          coerce date to local timezone
        !           127: date2gmt       string          coerce date to gmt
        !           128: .re
        !           129: .fi
        !           130: 
        !           131: When \fIstr\fR is an address, these escapes are useful:
        !           132: .nf
        !           133: .ta \w'formataddr  'u +\w'argument  'u +\w'returns  'u
        !           134: \fIescape\fR   \fIargument\fR  \fIreturns\fR   \fIinterpretation\fR
        !           135: pers   string  string  the personal name of the address
        !           136: mbox   string  string  the local part of the address
        !           137: host   string  string  the domain part of the address
        !           138: path   string  string  the route part of the address
        !           139: type   string  integer the type of host
        !           140:                        \-1 for uucp
        !           141:                        0 for local
        !           142:                        1 for network
        !           143:                        2 for unknown
        !           144: nohost string  integer no host was present in the address
        !           145: ingrp  string  integer the address appeared inside a group
        !           146: gname  string  string  name of the group (present for first
        !           147:                        address only)
        !           148: note   string  string  commentary text
        !           149: proper string  string  official 822 rendering of the address
        !           150: friendly       string  string  a more user\-friendly rendering
        !           151: mymbox string          the address refers to the user's mailbox
        !           152: formataddr     string          print \fIstr\fR in an address list
        !           153: .re
        !           154: .fi
        !           155: 
        !           156: With all this in mind,
        !           157: here's the default format string for \fIscan\fR.
        !           158: It's been divided into several pieces for readability.
        !           159: The first part is:
        !           160: 
        !           161: .ti +.5i
        !           162: %4(putnumf(msg))%<(cur)+%| %>%<{replied}\-%| %>
        !           163: 
        !           164: which says that the message number should be printed in four digits,
        !           165: if the message is the current message then a `+' else a space should be
        !           166: printed,
        !           167: and if a \*(lqReplied:\*(rq field is present then a `\-' else a space should
        !           168: be printed.
        !           169: Next:
        !           170: 
        !           171: .ti +.5i
        !           172: %02(putnumf(mon{date}))/%02(putnumf(mday{date}))
        !           173: 
        !           174: the hours and minutes are printed in two digits (zero filled).
        !           175: Next,
        !           176: 
        !           177: .ti +.5i
        !           178: %<{date} %|*>
        !           179: 
        !           180: If no \*(lqDate:\*(rq field was present,
        !           181: then a `*' is printed, otherwise a space.
        !           182: Next,
        !           183: 
        !           184: .ti +.5i
        !           185: %<(mymbox{from})To:%14(putstrf(friendly{to}))
        !           186: 
        !           187: if the message is from me,
        !           188: print `To:' followed by a \*(lquser\-friendly\*(rq rendering of the 
        !           189: first address in the \*(lqTo:\*(rq field.
        !           190: Continuing,
        !           191: 
        !           192: .ti +.5i
        !           193: %|%17(putstrf(friendly{from}))%>
        !           194: 
        !           195: if the message isn't from me,
        !           196: then the print the \*(lqFrom:\*(rq address is printed.
        !           197: And finally,
        !           198: 
        !           199: .ti +.5i
        !           200: %{subject}%<{body}<<%{body}%>
        !           201: 
        !           202: the subject and initial body are printed.
        !           203: 
        !           204: Although this seems complicated,
        !           205: in point of fact,
        !           206: this method is flexible enough to extract individual fields and print them in
        !           207: any format the user desires.
        !           208: 
        !           209: If the `\-form\ formatfile' switch is given,
        !           210: \fIscan\fR will treat each line in the named file as a format string and act
        !           211: accordingly.
        !           212: This lets the user employ canned scan listing formats.
        !           213: Take a look at the three files
        !           214: @(MHETCPATH)/scan.time, @(MHETCPATH)/scan.size, and @(MHETCPATH)/scan.timely.
        !           215: .Fi
        !           216: None
        !           217: .Pr
        !           218: None
        !           219: .Sa
        !           220: ap(8), dp(8)
        !           221: .De
        !           222: None
        !           223: .Co
        !           224: None
        !           225: .Bu
        !           226: On hosts where \fIMH\fR was configured with the BERK option,
        !           227: address parsing is not enabled.
        !           228: .En

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.