0ecb791ba91d23d55c4231b008ab6e3a68b32696
[mmh] / mh-format.man
1 .\"
2 .\" %nmhwarning%
3 .\"
4 .TH MH-FORMAT %manext5% "%nmhdate%" MH.6.8 [%nmhversion%]
5 .SH NAME
6 mh-format \- format file for nmh message system
7 .SH DESCRIPTION
8 Several
9 .B nmh
10 commands utilize either a
11 .I format
12 string or a
13 .I format
14 file during their execution.  For example,
15 .B scan
16 uses a format string which directs it how to generate the scan listing
17 for each message;
18 .B repl
19 uses a format file which directs it
20 how to generate the reply to a message, and so on.
21 .PP
22 There are a few alternate scan listing formats available
23 in
24 .IR nmh/etc/scan.time ,
25 .IR nmh/etc/scan.size ,
26 and
27 .IR nmh/etc/scan.timely .
28 Look in
29 .I nmh/etc
30 for other
31 .B scan
32 and
33 .B repl
34 format files which may have been written at your site.
35 .PP
36 It suffices to have your local
37 .B nmh
38 expert actually write new format
39 commands or modify existing ones.  This manual section explains how to
40 do that.  Note: familiarity with the C
41 .B printf
42 routine is assumed.
43 .PP
44 A format string consists of ordinary text, and special multi-character
45 escape sequences which begin with `%'.  When specifying a format
46 string, the usual C backslash characters are honored: `\\b', `\\f',
47 `\\n', `\\r', and `\\t'.  Continuation lines in format files end with
48 `\\' followed by the newline character.
49
50 .\" TALK ABOUT SYNTAX FIRST, THEN SEMANTICS
51 .SS SYNTAX
52 Format strings are built around
53 .IR "escape sequences" .
54 There are three types of escape sequences: header
55 .IR components ,
56 built-in
57 .IR functions ,
58 and flow
59 .IR control .
60 Comments may be inserted in most places where a function argument is
61 not expected.  A comment begins with `%;' and ends with a (non-escaped)
62 newline.
63 .PP
64 A
65 .I component
66 escape is specified as
67 .RI `%{ component }',
68 and
69 exists for each header found in the message being processed.  For example
70 .RI `%{ date }'
71 refers to the \*(lqDate:\*(rq field of the appropriate message.
72 All component escapes have a string value.  Normally, component values are
73 compressed by converting any control characters (tab and newline included)
74 to spaces, then eliding any leading or multiple spaces.  However, commands
75 may give different interpretations to some component escapes; be sure
76 to refer to each command's manual entry for complete details.  Some commands
77 (such as
78 .B ap
79 and
80 .BR mhl )
81 use a special component
82 .RI `%{ text }'
83 to refer to the text being processed; see their respective man pages for
84 details and examples.
85 .PP
86 A
87 .I function
88 escape is specified as
89 .RI `%( function )'.
90 All functions are built-in, and most have a string or numeric value.
91 A function escape may have an
92 .IR argument .
93 The argument follows the function escape: separating
94 whitespace is discarded:
95 .RI `%( function " " argument )'.
96 .PP
97 In addition to literal numbers or strings, 
98 the argument to a function escape can be another function, a component,
99 or a control escape.  When the argument is a function or a
100 component, they are listed without a leading `%'.  When control escapes
101 are used as function arguments, they written as normally, with
102 a leading `%';
103
104 .SS "Control escapes"
105 .PP
106 A
107 .I control
108 escape is one of: `%<', `%?', `%|', or `%>'. 
109 These are combined into the conditional execution construct:
110 .PP
111 .RS 5
112 .nf
113 .RI "%< " condition " " "format-text"
114 .RI "%? " condition " " "format-text"
115     \&...
116 .RI "%| " "format-text"
117 %>
118 .fi
119 .RE
120 .PP
121 Extra white space is shown here only for clarity.  These
122 constructs may be nested without ambiguity.  They form a general
123 .B if\-elseif\-else\-endif
124 block where only one of the
125 format-texts
126 is interpreted.  In other 
127 words, `%<' is like the "if", `%?' is like the "elseif", `%|' is like 
128 "else", and `%>' is like "endif".
129 .PP
130 A `%<' or `%?' control escape causes its condition to be evaluated.  
131 This condition is a
132 .I component
133 or
134 .IR function .
135 For integer valued functions or components, the condition is true
136 if the function return or component value is non-zero, and false if zero.
137 For string valued functions or components, the condition is true
138 if the function return or component value is 
139 a non-empty string, and false for an empty string.
140
141 .PP
142 The `%?' control escape is optional, and may there may be more
143 than one `%?' control escape in a conditional block.
144 The `%|' control escape
145 is also optional, but may be included at most once.
146
147 .SS "Function escapes"
148 Functions expecting an argument generally
149 require an argument of a particular type.
150 In addition to the number and string types,
151 these include:
152 .PP
153 .RS 5
154 .nf
155 .ta +\w'Argument 'u +\w'An optional component, 'u
156 .I "Argument    Description     Example Syntax"
157 literal A literal number        %(\fIfunc\fR 1234)
158         or string               %(\fIfunc\fR text string)
159 comp    Any component           %(\fIfunc\fR\^{\fIin-reply-to\fR\^})
160 date    A date component        %(\fIfunc\fR\^{\fIdate\fR\^})
161 addr    An address component    %(\fIfunc\fR\^{\fIfrom\fR\^})
162 expr    Nothing %(\fIfunc\fR)
163         or a subexpression      %(\fIfunc\fR\^(\fIfunc2\fR\^))
164         or control escape       %(\fIfunc\fR %<{\fIreply-to\fR\^}%|%{\fIfrom\fR\^}%>)
165 .fi
166 .RE
167 .PP
168 The types
169 .I date
170 and
171 .I addr
172 have the same syntax as
173 .IR comp ,
174 but require that the header component be a date string, or address
175 string, respectively.
176 .PP
177 Most arguments not of type
178 .IR expr
179 are required.
180 When escapes are nested (via expr arguments), evaluation is done from inner-most to outer-most.
181 As noted above, for the
182 expr
183 argument type, 
184 functions and components are written without a
185 leading `%'.
186 Control escape arguments must use a leading `%', preceded by a space.
187 .PP
188 For example,
189 .PP
190 .RS 5
191 .nf
192 %<(mymbox{from}) To: %{to}%>
193 .fi
194 .RE
195 .PP
196 writes  the  value of the header component \*(lqFrom:\*(rq to the
197 internal register named str; then (\fImymbox\fR\^) reads str and
198 writes its result to the internal register named 
199 .IR num ; 
200 then the control escape evaluates 
201 .IR num .  
202 If
203 .IR num
204 is non-zero, the
205 string \*(lqTo:\*(rq is printed  followed  by  the  value  of  the
206 header component \*(lqTo:\*(rq.
207 .SS Evaluation
208 The evaluation of format strings is performed
209 by a small virtual machine.
210 The machine is capable of evaluating nested expressions
211 as described above, and in addition
212 has an integer register
213 .IR num ,
214 and a text string register
215 .IR str .
216 When a function escape that
217 accepts an optional argument is processed,
218 and the argument is not present, the current value of either
219 .I num
220 or
221 .I str
222 is used as the argument: which register is
223 used depends on the function, as listed below.
224 .PP
225 Component escapes write the value of their message header in
226 .IR str .
227 Function escapes write their return value in
228 .I num
229 for functions returning integer or boolean values, and in
230 .I str
231 for functions returning string values.  (The boolean type is a subset
232 of integers with usual values 0=false and 1=true.)  Control escapes
233 return a boolean value, setting
234 .I num
235 to 1 if the last explicit condition
236 evaluated by a `%<' or `%?' control
237 succeeded, and 0 otherwise.
238 .PP
239 All component escapes, and those function escapes which return an
240 integer or string value, evaluate to their value as well as setting
241 .I str
242 or
243 .IR num .
244 Outermost escape expressions in
245 these forms will print
246 their value, but outermost escapes which return a boolean value
247 do not result in printed output.
248 .SS Functions
249 The function escapes may be roughly grouped into a few categories.
250 .PP
251 .RS 5
252 .nf
253 .ta \w'Fformataddr 'u +\w'Aboolean 'u +\w'Rboolean 'u
254 .I "Function    Argument   Result       Description"
255 msg             integer message number
256 cur             integer message is current (0 or 1)
257 unseen          integer message is unseen (0 or 1)
258 size            integer size of message
259 strlen          integer length of \fIstr\fR
260 width           integer output buffer size in bytes
261 charleft                integer bytes left in output buffer
262 timenow         integer seconds since the UNIX epoch
263 me              string  the user's mailbox (username)
264 myhost          string  the user's local hostname
265 myname          string  the user's name
266 localmbox               string  the complete local mailbox
267 eq      literal boolean \fInum\fR == \fIarg\fR
268 ne      literal boolean \fInum\fR != \fIarg\fR
269 gt      literal boolean \fInum\fR > \fIarg\fR
270 match   literal boolean \fIstr\fR contains \fIarg\fR
271 amatch  literal boolean \fIstr\fR starts with \fIarg\fR
272 plus    literal integer \fIarg\fR plus \fInum\fR
273 minus   literal integer \fIarg\fR minus \fInum\fR
274 divide  literal integer \fInum\fR divided by \fIarg\fR
275 modulo  literal integer \fInum\fR modulo \fIarg\fR
276 num     literal integer Set \fInum\fR to \fIarg\fR.
277 num             integer Set \fInum\fR to zero.
278 lit     literal string  Set \fIstr\fR to \fIarg\fR.
279 lit             string  Clear \fIstr\fR.
280 getenv  literal string  Set \fIstr\fR to environment value of \fIarg\fR
281 profile literal string  Set \fIstr\fR to profile component \fIarg\fR 
282                         value
283 .\" dat literal int     return value of dat[arg]
284 nonzero expr    boolean \fInum\fR is non-zero
285 zero    expr    boolean \fInum\fR is zero
286 null    expr    boolean \fIstr\fR is empty
287 nonnull expr    boolean \fIstr\fR is non-empty
288 void    expr            Set \fIstr\fR or \fInum\fR
289 comp    comp    string  Set \fIstr\fR to component text
290 compval comp    integer Set \fInum\fR to \*(lq\fBatoi\fR(\fIcomp\fR\^)\*(rq
291 .\" compflag    comp    integer Set \fInum\fR to component flags bits (internal)
292 .\" decodecomp  comp    string  Set \fIstr\fR to RFC-2047 decoded component text
293 decode  expr    string  decode \fIstr\fR as RFC-2047 (MIME-encoded) 
294                         component
295 unquote expr    string  remove RFC-2822 quotes from \fIstr\fR
296 trim    expr            trim trailing white-space from \fIstr\fR
297 putstr  expr            print \fIstr\fR
298 putstrf expr            print \fIstr\fR in a fixed width
299 putnum  expr            print \fInum\fR
300 putnumf expr            print \fInum\fR in a fixed width
301 .\" addtoseq literal    add msg to sequence (LBL option)
302 putlit  expr            print \fIstr\fR without space compression
303 nodate  string  integer Argument not a date string (0 or 1)
304 formataddr      expr            append \fIarg\fR to \fIstr\fR as a
305                         (comma separated) address list
306 concataddr      expr            append \fIarg\fR to \fIstr\fR as a
307                         (comma separated) address list,
308                         including duplicates,
309                         see Special Handling
310 putaddr literal         print \fIstr\fR address list with
311                         \fIarg\fR as optional label;
312                         get line width from \fInum\fR
313 .fi
314 .RE
315 .PP
316 The (\fIme\fR\^) function returns the username of the current user.  The
317 (\fImyhost\fR\^) function returns the
318 .B localname
319 entry in
320 .IR mts.conf ,
321 or the local hostname if
322 .B localname
323 is not configured.  The (\fImyname\fR\^) function will return the value of
324 the
325 .B SIGNATURE
326 environment variable if set, otherwise will return the passwd GECOS field for
327 the current user.  The (\fIlocalmbox\fR\^) function will return the complete
328 form of the local mailbox, suitable for use in a \*(lqFrom\*(rq header.
329 It will return the
330 .RI \*(lq Local-Mailbox \*(rq
331 profile entry if it is set; if it is not, it will be equivalent to:
332 .PP
333 .RS 5
334 .nf
335 %(myname) <%(me)@%(myhost)>
336 .fi
337 .RE
338 .PP
339 The following functions require a date component as an argument:
340 .PP
341 .RS 5
342 .nf
343 .ta \w'Fformataddr 'u +\w'Aboolean 'u +\w'Rboolean 'u
344 .I "Function    Argument        Return  Description"
345 sec     date    integer seconds of the minute
346 min     date    integer minutes of the hour
347 hour    date    integer hours of the day (0-23)
348 wday    date    integer day of the week (Sun=0)
349 day     date    string  day of the week (abbrev.)
350 weekday date    string  day of the week
351 sday    date    integer day of the week known?
352                         (1=explicit,0=implicit,\-1=unknown)
353 mday    date    integer day of the month
354 yday    date    integer day of the year
355 mon     date    integer month of the year
356 month   date    string  month of the year (abbrev.)
357 lmonth  date    string  month of the year
358 year    date    integer year (may be > 100)
359 zone    date    integer timezone in hours
360 tzone   date    string  timezone string
361 szone   date    integer timezone explicit?
362                         (1=explicit,0=implicit,\-1=unknown)
363 date2local      date            coerce date to local timezone
364 date2gmt        date            coerce date to GMT
365 dst     date    integer daylight savings in effect? (0 or 1)
366 clock   date    integer seconds since the UNIX epoch
367 rclock  date    integer seconds prior to current time
368 tws     date    string  official 822 rendering
369 pretty  date    string  user-friendly rendering
370 .fi
371 .RE
372 .PP
373 These functions require an address component as an argument.  
374 The return value of functions noted with `*' is computed from
375 the first address present in the header component.
376 .PP
377 .RS 5
378 .nf
379 .ta \w'Fformataddr 'u +\w'Aboolean 'u +\w'Rboolean 'u
380 .I "Function    Argument        Return  Description"
381 proper  addr    string  official 822 rendering
382 friendly        addr    string  user-friendly rendering
383 addr    addr    string  mbox@host or host!mbox rendering*
384 pers    addr    string  the personal name*
385 note    addr    string  commentary text*
386 mbox    addr    string  the local mailbox*
387 mymbox  addr    integer List has the user's address? (0 or 1)
388 host    addr    string  the host domain*
389 nohost  addr    integer no host was present (0 or 1)*
390 type    addr    integer host type* (0=local,1=network,
391                         \-1=uucp,2=unknown)
392 path    addr    string  any leading host route*
393 ingrp   addr    integer address was inside a group (0 or 1)*
394 gname   addr    string  name of group*
395 .fi
396 .RE
397 .PP
398 (A clarification on (\fImymbox\fR\^{\fIcomp\fR\^}) is in order.
399 This function checks each of the addresses in the header component
400 \*(lq\fIcomp\fR\*(rq against the user's mailbox name and any
401 .RI \*(lq Alternate-Mailboxes \*(rq.
402 It returns true if any address matches,
403 however, it also returns true if the \*(lq\fIcomp\fR\*(rq header is not
404 present in the message.  If needed, the (\fInull\fR\^) function can be
405 used to explicitly test for this case.)
406 .SS Formatting
407 When a function or component escape is interpreted and the result will
408 be immediately printed, an optional field width can be specified to
409 print the field in exactly a given number of characters.  For example, a
410 numeric escape like %4(\fIsize\fR\^) will print at most 4 digits of the
411 message size; overflow will be indicated by a `?' in the first position
412 (like `?234').  A string escape like %4(\fIme\fR\^) will print the first 4
413 characters and truncate at the end.  Short fields are padded at the right
414 with the fill character (normally, a blank).  If the field width argument
415 begins with a leading zero, then the fill character is set to a zero.
416 .PP
417 The functions (\fIputnumf\fR\^) and (\fIputstrf\fR\^)
418 print their result in exactly the number of characters
419 specified by their leading field width argument.  For example,
420 %06(\fIputnumf\fR\^(\fIsize\fR\^)) will print the message
421 size in a field six characters wide filled with leading zeros;
422 %14(\fIputstrf\^\fR{\fIfrom\^\fR}) will print the \*(lqFrom:\*(rq header
423 component in fourteen characters with trailing spaces added as needed.
424 For \fIputstrf\fR, using a negative value for the field width causes
425 right-justification of the string within the field, with padding on
426 the left up to the field width.
427 The functions (\fIputnum\fR\^) and
428 (\fIputstr\fR\^) are somewhat special: they print their result in the minimum number of characters
429 required, and ignore any leading field width argument.  The (\fIputlit\fR\^)
430 function outputs the exact contents of str register without any changes
431 such as duplicate space removal or control character conversion.
432 .PP
433 The available output width is kept in an internal register; any output
434 past this width will be truncated.
435 .SS Special Handling
436 A few functions have different behavior depending on what command they are
437 being invoked from.
438 .PP
439 In
440 .BR repl
441 the (\fIformataddr\fR\^) function stores all email addresses encountered into
442 an internal cache and will use this cache to suppress duplicate addresses.
443 If you need to create an address list that includes previously-seen
444 addresses you may use the (\fIconcataddr\fR\^) function, which is identical
445 to (\fIformataddr\fR\^) in all other respects.  Note that (\fIconcataddr\fR\^)
446 will NOT add addresses to the duplicate-suppression cache.
447 .SS Other Hints and Tips
448 Sometimes to format function writers it is confusing as to why output is
449 duplicated.  The general rule to remember is simple: If a function or
450 component escape is used where it starts with a %, then it will generate
451 text in the output file.  Otherwise, it will not.
452 .PP
453 A good example is a simple attempt to generate a To: header based on
454 the From: and Reply-To: headers:
455 .PP
456 .RS 5
457 .nf
458 %(formataddr %<{reply-to}%|%{from})%(putaddr To: )
459 .fi
460 .RE
461 .PP
462 Unfortuantely if the Reply-to: header is NOT present, the output line that is
463 generated will be something like:
464 .PP
465 .RS 5
466 .nf
467 My From User <from@example.com>To: My From User <from@example.com>
468 .fi
469 .RE
470 .PP
471 What went wrong?  When performing the test for the
472 .B if
473 clause (%<), the component is not output because it is considered an
474 argument to the
475 .B if
476 statement (hence the rule about the lack of % applies).  But the component
477 escape in our
478 .B else
479 statement (everything after the `%|') is NOT an argument to anything; the
480 syntax is that it is written with a %, and thus the value of that component
481 is output.  This also has the side effect of setting the 
482 .I str
483 register, which is later picked up by the (\fIformataddr\fR\^) function
484 and then output by (\fIputaddr\fR\^).  This format string has another bug
485 as well; there should always be a valid width value in the
486 .I num
487 register when (\fIputaddr\fR\^) is called, otherwise bad formatting can take
488 place.
489 .PP
490 The solution is to use the (\fIvoid\fR\^) function; this will prevent the
491 function or component from outputting any text.  With this in place (and
492 using (\fIwidth\fR\^) to set the
493 .I num
494 register for the width, a better implementation would look like:
495 .PP
496 .RS 3
497 .nf
498 %(formataddr %<{reply-to}%|%(void{from})%(void(width))%(putaddr To: )
499 .fi
500 .RE
501 .PP
502 It should be noted here that the side-effects of functions and component
503 escapes still are in force: as a result each component
504 test in the 
505 .B if\-elseif\-else\-endif
506 clause sets the
507 .I str
508 register.
509 .PP
510 As an additional note, the (\fIformataddr\fR\^) and (\fIconcataddr\fR\^)
511 functions have some behavior when it comes to the
512 .I str
513 register.  The starting point of the register is saved and is used to
514 build up entries in the address list.
515 .PP
516 You will find the
517 .B ap
518 and
519 .B fmtdump
520 utilities invaluable in debugging problems with format strings.
521 .SS Examples
522 With all this in mind,
523 here's the default format string for
524 .BR scan .
525 It's been divided into several pieces for readability.
526 The first part is:
527 .PP
528 .RS
529 .nf
530 %4(msg)%<(cur)+%| %>%<{replied}\-%?{encrypted}E%| %>
531 .fi
532 .RE
533 .PP
534 which says that the message number should be printed in four digits.
535 If the message is the current message then a `+' else a space should
536 be printed; if a \*(lqReplied:\*(rq field is present then a `\-'
537 else if an \*(lqEncrypted:\*(rq field is present then an `E' otherwise
538 a space should be printed.  Next:
539 .PP
540 .RS
541 .nf
542 %02(mon{date})/%02(mday{date})
543 .fi
544 .RE
545 .PP
546 the month and date are printed in two digits (zero filled) separated by
547 a slash. Next,
548 .PP
549 .RS 5
550 .nf
551 %<{date} %|*%>
552 .fi
553 .RE
554 .PP
555 If a \*(lqDate:\*(rq field was present,
556 then a space is printed, otherwise a `*'.
557 Next,
558 .PP
559 .RS 5
560 .nf
561 %<(mymbox{from})%<{to}To:%14(decode(friendly{to}))%>%>
562 .fi
563 .RE
564 .PP
565 if the message is from me, and there is a \*(lqTo:\*(rq header,
566 print \*(lqTo:\*(rq followed by a \*(lquser-friendly\*(rq rendering of the
567 first address in the \*(lqTo:\*(rq field; any MIME-encoded
568 characters are decoded into the actual characters.
569 Continuing,
570 .PP
571 .RS 5
572 .nf
573 %<(zero)%17(decode(friendly{from}))%>
574 .fi
575 .RE
576 .PP
577 if either of the above two tests failed,
578 then the \*(lqFrom:\*(rq address is printed
579 in a mime-decoded, \*(lquser-friendly\*(rq format.
580 And finally,
581 .PP
582 .RS 5
583 .nf
584 %(decode{subject})%<{body}<<%{body}>>%>
585 .fi
586 .RE
587 .PP
588 the mime-decoded subject and initial body (if any) are printed.
589 .PP
590 For a more complicated example, next consider
591 a possible
592 .I replcomps
593 format file.
594 .PP
595 .RS 5
596 .nf
597 %(lit)%(formataddr %<{reply-to}
598 .fi
599 .RE
600 .PP
601 This clears
602 .I str
603 and formats the \*(lqReply-To:\*(rq header 
604 if present.  If not present, the else-if clause is executed.
605 .PP
606 .RS 5
607 .nf
608 %?{from}%?{sender}%?{return-path}%>)\\
609 .fi
610 .RE
611 .PP
612 This formats the 
613 \*(lqFrom:\*(rq, \*(lqSender:\*(rq and \*(lqReturn-Path:\*(rq
614 headers, stopping as soon as one of them is present.  Next:
615 .PP
616 .RS 5
617 .nf
618 %<(nonnull)%(void(width))%(putaddr To: )\\n%>\\
619 .fi
620 .RE
621 .PP
622 If the \fIformataddr\fR result is non-null, it is printed as
623 an address (with line folding if needed) in a field \fIwidth\fR
624 wide with a leading label of \*(lqTo:\*(rq.
625 .PP
626 .RS 5
627 .nf
628 %(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\\
629 .fi
630 .RE
631 .PP
632 .I str
633 is cleared, and the \*(lqTo:\*(rq and \*(lqCc:\*(rq headers, along with the user's
634 address (depending on what was specified with
635 the \*(lq\-cc\*(rq switch to \fIrepl\fR\^) are formatted.
636 .PP
637 .RS 5
638 .nf
639 %<(nonnull)%(void(width))%(putaddr cc: )\\n%>\\
640 .fi
641 .RE
642 .PP
643 If the result is non-null, it is printed as above with a
644 leading label of \*(lqcc:\*(rq.
645 .PP
646 .RS 5
647 .nf
648 %<{fcc}Fcc: %{fcc}\\n%>\\
649 .fi
650 .RE
651 .PP
652 If a
653 .B \-fcc
654 .I folder
655 switch was given to
656 .B repl
657 (see
658 .BR repl (1)
659 for more details about %{\fIfcc\fR\^}),
660 an \*(lqFcc:\*(rq header is output.
661 .PP
662 .RS 5
663 .nf
664 %<{subject}Subject: Re: %{subject}\\n%>\\
665 .fi
666 .RE
667 .PP
668 If a subject component was present,
669 a suitable reply subject is output.
670 .PP
671 .RS 5
672 .nf
673 %<{message-id}In-Reply-To: %{message-id}\\n%>\\
674 %<{message-id}References: %<{references} %{references}%>\\
675 %{message-id}\\n%>
676 \-\-\-\-\-\-\-\-
677 .fi
678 .RE
679 .PP
680 If a message-id component was present, an \*(lqIn-Reply-To:\*(rq header is
681 output including the message-id, followed by a \*(lqReferences:\*(rq
682 header with references, if present, and the message-id.
683 As with all
684 plain-text, the row of dashes are output as-is.
685 .PP
686 This last part is a good example for a little more elaboration.
687 Here's that part again in pseudo-code:
688 .PP
689 .RS 5
690 .nf
691 .ta .5i 1i 1.5i 2i
692 if (comp_exists(message-id))  then
693         print (\*(lqIn-reply-to: \*(rq)
694         print (message-id.value)
695         print (\*(lq\\n\*(rq)
696 endif
697 if (comp_exists(message-id)) then
698         print (\*(lqReferences: \*(rq)
699         if (comp_exists(references)) then
700               print(references.value);
701         endif
702         print (message-id.value)
703         print (\*(lq\\n\*(rq)
704 endif
705 .fi
706 .RE
707 .PP
708 .\" (Note that this pseudocode begs the question ``why not just
709 .\" support this syntax?''  MH has been hacked on for a long time...)
710 .\".PP
711 One more example: Currently,
712 .B nmh
713 supports very
714 large message numbers, and it is not uncommon for a folder
715 to have far more than 10000 messages.
716 .\" (Indeed, the original MH
717 .\" tutorial document by Rose and Romine is entitled "How to
718 .\" process 200 messages a day and still get some real work
719 .\" done."  The authors apparently only planned to get
720 .\" real work done for about 50 days per folder.)
721 Nontheless (as noted above)
722 the various scan format strings are inherited
723 from older MH versions, and are generally hard-coded to 4
724 digits of message number before formatting problems
725 start to occur.  
726 The nmh format strings can be modified to behave more sensibly with larger
727 message numbers:
728 .PP
729 .RS
730 .nf
731 %(void(msg))%<(gt 9999)%(msg)%|%4(msg)%>
732 .fi
733 .RE
734 .PP
735 The current message number is placed in \fInum\fP.
736 (Note that
737 .RI ( msg )
738 is an int function, not a component.)
739 The
740 .RI ( gt )
741 conditional
742 is used to test whether the message number
743 has 5
744 or more digits.
745 If so, it is printed at full width: otherwise
746 at 4 digits.
747 .SH "SEE ALSO"
748 scan(1), repl(1), ap(8), dp(8)
749
750 .SH CONTEXT
751 None