Return to mh-format.rf CVS log

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

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

1.1     ! root        1: .\"    @(MHWARNING)
        !             2: .TH MH\-FORMAT 5 "April 22, 1986" 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'integer  'u +\w'integer  '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: putnum integer         print \fInum\fR
        !            78: putnumf        integer         print \fInum\fR in the specified width
        !            79:                        (e.g., %4(putnumf(msg))
        !            80: msg            integer message number
        !            81: cur            integer message is current
        !            82: size           integer size of message
        !            83: strlen string  integer length of \fIstr\fR
        !            84: me             string  the user's mailbox
        !            85: plus           integer add width to \fInum\fR
        !            86: minus          integer subtract \fInum\fR from width
        !            87: charleft               integer space left in output buffer
        !            88: timenow                integer seconds since the UNIX epoch
        !            89: .re
        !            90: .fi
        !            91: 
        !            92: When \fIstr\fR is a date, these escapes are useful:
        !            93: .nf
        !            94: .ta \w'formataddr  'u +\w'integer  'u +\w'integer  'u
        !            95: \fIescape\fR   \fIargument\fR  \fIreturns\fR   \fIinterpretation\fR
        !            96: sec    string  integer seconds of the minute
        !            97: min    string  integer minutes of the day
        !            98: hour   string  integer hours of the day (24 hour clock)
        !            99: mday   string  integer day of the month
        !           100: mon    string  integer month of the year
        !           101: wday   string  integer day of the week (Sunday=0)
        !           102: year   string  integer year of the century
        !           103: yday   string  integer day of the year
        !           104: dst    string  integer daylight savings in effect
        !           105: zone   string  integer timezone
        !           106: sday   string  integer day of the week known
        !           107:                        1 for explicit in date
        !           108:                        0 for implicit (\fIMH\fR figured it out)
        !           109:                        \-1 for unknown (\fIMH\fR couldn't figure it out)
        !           110: clock  string  integer seconds since the UNIX epoch
        !           111: rclock string  integer seconds prior to current time
        !           112: month  string  string  month of the year
        !           113: lmonth string  string  month of the year (long form)
        !           114: tzone  string  string  timezone
        !           115: day    string  string  day of the week
        !           116: weekday        string  string  day of the week (long)
        !           117: tws    string  string  official 822 rendering of the date
        !           118: pretty string  string  a more user\-friendly rendering
        !           119: nodate string          date wasn't parseable
        !           120: .re
        !           121: .fi
        !           122: 
        !           123: When \fIstr\fR is an address, these escapes are useful:
        !           124: .nf
        !           125: .ta \w'formataddr  'u +\w'integer  'u +\w'integer  'u
        !           126: \fIescape\fR   \fIargument\fR  \fIreturns\fR   \fIinterpretation\fR
        !           127: pers   string  string  the personal name of the address
        !           128: mbox   string  string  the local part of the address
        !           129: host   string  string  the domain part of the address
        !           130: path   string  string  the route part of the address
        !           131: type   string  integer the type of host
        !           132:                        \-1 for uucp
        !           133:                        0 for local
        !           134:                        1 for network
        !           135:                        2 for unknown
        !           136: nohost string  integer no host was present in the address
        !           137: ingrp  string  integer the address appeared inside a group
        !           138: gname  string  string  name of the group (present for first
        !           139:                        address only)
        !           140: note   string  string  commentary text
        !           141: proper string  string  official 822 rendering of the address
        !           142: friendly       string  string  a more user\-friendly rendering
        !           143: mymbox string          the address refers to the user's mailbox
        !           144: formataddr     string          print \fIstr\fR in an address list
        !           145: .re
        !           146: .fi
        !           147: 
        !           148: With all this in mind,
        !           149: here's the default format string for \fIscan\fR.
        !           150: It's been divided into several pieces for readability.
        !           151: The first part is:
        !           152: 
        !           153: .ti +.5i
        !           154: %4(putnumf(msg))%<(cur)+%| %>%<{replied}\-%| %>
        !           155: 
        !           156: which says that the message number should be printed in four digits,
        !           157: if the message is the current message then a `+' else a space should be
        !           158: printed,
        !           159: and if a \*(lqReplied:\*(rq field is present then a `\-' else a space should
        !           160: be printed.
        !           161: Next:
        !           162: 
        !           163: .ti +.5i
        !           164: %02(putnumf(mon{date}))/%02(putnumf(mday{date}))
        !           165: 
        !           166: the hours and minutes are printed in two digits (zero filled).
        !           167: Next,
        !           168: 
        !           169: .ti +.5i
        !           170: %<{date} %|*>
        !           171: 
        !           172: If no \*(lqDate:\*(rq field was present,
        !           173: then a `*' is printed, otherwise a space.
        !           174: Next,
        !           175: 
        !           176: .ti +.5i
        !           177: %<(mymbox{from})To:%14(putstrf(friendly{to}))
        !           178: 
        !           179: if the message is from me,
        !           180: print `To:' followed by a \*(lquser\-friendly\*(rq rendering of the 
        !           181: first address in the \*(lqTo:\*(rq field.
        !           182: Continuing,
        !           183: 
        !           184: .ti +.5i
        !           185: %|%17(putstrf(friendly{from}))%>
        !           186: 
        !           187: if the message isn't from me,
        !           188: then the print the \*(lqFrom:\*(rq address is printed.
        !           189: And finally,
        !           190: 
        !           191: .ti +.5i
        !           192: %{subject}<<%{body}>>
        !           193: 
        !           194: the subject and initial body are printed.
        !           195: 
        !           196: Although this seems complicated,
        !           197: in point of fact,
        !           198: this method is flexible enough to extract individual fields and print them in
        !           199: any format the user desires.
        !           200: 
        !           201: If the `\-form\ formatfile' switch is given,
        !           202: \fIscan\fR will treat each line in the named file as a format string and act
        !           203: accordingly.
        !           204: This lets the user employ canned scan listing formats.
        !           205: Take a look at the three files
        !           206: @(MHETCPATH)/scan.time, @(MHETCPATH)/scan.size, and @(MHETCPATH)/scan.timely.
        !           207: .Fi
        !           208: None
        !           209: .Pr
        !           210: None
        !           211: .Sa
        !           212: ap(8), dp(8)
        !           213: .De
        !           214: None
        !           215: .Co
        !           216: None
        !           217: .Bu
        !           218: On hosts where \fIMH\fR was configured with the BERK option,
        !           219: address parsing is not enabled.
        !           220: .En

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