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