![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mh-format.me CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / mh / doc|
Return to mh-format.me CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / mh / doc |
1.1 root 1: .\" This file is automatically generated. Do not edit!
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: /usr/contrib/mh/lib/scan.time, /usr/contrib/mh/lib/scan.size, and /usr/contrib/mh/lib/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.