![[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] / 43BSD / contrib / mh / doc|
Return to mh-format.me CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / mh / doc |
1.1 root 1: .\" This file is automatically generated. Do not edit!
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: /usr/new/lib/mh/scan.time, /usr/new/lib/mh/scan.size, and /usr/new/lib/mh/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.