8 date 95.12.06.23.33.39; author jromine; state Exp;
13 date 94.04.21.19.11.19; author jromine; state Exp;
18 date 93.08.19.20.26.17; author jromine; state Exp;
23 date 93.06.12.06.49.57; author jromine; state Exp;
28 date 92.12.02.18.41.50; author jromine; state Exp;
33 date 92.11.20.19.35.06; author jromine; state Exp;
38 date 92.10.28.23.03.14; author jromine; state Exp;
43 date 92.10.27.00.20.03; author jromine; state Exp;
48 date 92.10.26.17.03.42; author jromine; state Exp;
53 date 92.05.12.22.23.34; author jromine; state Exp;
58 date 92.02.18.17.28.26; author jromine; state Exp;
63 date 92.02.14.19.14.42; author jromine; state Exp;
68 date 92.02.11.05.03.41; author jromine; state Exp;
73 date 92.02.09.22.11.10; author jromine; state Exp;
78 date 92.02.09.07.18.01; author jromine; state Exp;
83 date 92.02.07.01.08.25; author jromine; state Exp;
88 date 92.02.06.00.13.07; author jromine; state Exp;
93 date 92.01.29.22.55.31; author jromine; state Exp;
98 date 91.01.11.09.17.35; author mh; state Exp;
103 date 91.01.11.09.15.19; author mh; state Exp;
108 date 90.12.27.17.22.27; author mh; state Exp;
113 date 90.04.05.15.09.13; author sources; state Exp;
118 date 90.04.04.23.07.22; author sources; state Exp;
123 date 90.04.02.18.07.25; author sources; state Exp;
128 date 90.04.02.17.56.48; author sources; state Exp;
133 date 90.04.02.17.49.02; author sources; state Exp;
138 date 90.03.31.18.24.07; author sources; state Exp;
143 date 90.03.22.11.31.15; author sources; state Exp;
148 date 90.03.20.22.21.11; author sources; state Exp;
153 date 90.03.20.19.41.54; author sources; state Exp;
158 date 90.03.20.17.36.10; author sources; state Exp;
163 date 90.03.20.10.20.21; author sources; state Exp;
168 date 90.03.19.16.02.45; author sources; state Exp;
173 date 90.03.18.23.27.00; author sources; state Exp;
178 date 90.03.18.20.55.16; author sources; state Exp;
183 date 90.03.18.19.54.04; author sources; state Exp;
188 date 90.03.18.16.49.19; author sources; state Exp;
193 date 90.03.15.20.11.07; author sources; state Exp;
198 date 90.03.15.11.27.04; author sources; state Exp;
203 date 90.03.15.11.20.39; author sources; state Exp;
208 date 90.03.15.10.50.08; author sources; state Exp;
213 date 90.03.15.10.40.21; author sources; state Exp;
218 date 90.03.15.10.11.44; author sources; state Exp;
223 date 90.03.15.00.06.45; author sources; state Exp;
228 date 90.03.14.17.34.00; author sources; state Exp;
233 date 90.03.14.09.51.17; author sources; state Exp;
238 date 90.03.14.09.50.29; author sources; state Exp;
253 .\" @@(#)$Id: mh-format.rf,v 1.46 1994/04/21 19:11:19 jromine Exp jromine $
256 mh-format \- format file for MH message system
258 some \fIMH\fR commands
260 Several \fIMH\fR commands utilize either a \fIformat\fR string or a
261 \fIformat\fR file during their execution.
263 \fIscan\fR\0(1) uses a format string which directs it how to generate the
264 scan listing for each message;
265 \fIrepl\fR\0(1) uses a format file which directs it how to generate the
266 reply to a message, and so on.
268 Format strings are designed to be efficiently parsed by \fIMH\fR which
269 means they are not necessarily simple to write and understand.
270 This means that novice, casual, or even advanced users of \fIMH\fR should
271 not have to deal with them.
272 Some canned scan listing formats are in
273 @@(MHETCPATH)/scan.time, @@(MHETCPATH)/scan.size, and @@(MHETCPATH)/scan.timely.
274 Look in @@(MHETCPATH) for other \fIscan\fR and \fIrepl\fR format files
275 which may have been written at your site.
277 It suffices to have your local \fIMH\fR expert actually write new format
278 commands or modify existing ones.
279 This manual section explains how to do that.
280 Note: familiarity with the C \fIprintf\fR routine is assumed.
282 A format string consists of ordinary text, and special
283 multi-character \fIescape\fR sequences which begin with `%'.
284 When specifying a format string,
285 the usual C backslash characters are honored:
286 `\\b', `\\f', `\\n', `\\r', and `\\t'.
287 Continuation lines in format files end with `\\' followed
288 by the newline character.
289 To put a literal `%' or `\\' in a format string, use two of them:
291 .\" talk about syntax first, then semantics
292 There are three types of \fIescape\fR sequences:
293 header \fIcomponents\fR, built-in \fIfunctions\fR, and flow \fIcontrol\fR.
295 A \fIcomponent\fR escape is specified as `%{\fIcomponent\fR\^}',
296 and exists for each header found in the message being processed.
297 For example `%{date}' refers to the \*(lqDate:\*(rq field of the appropriate
299 All component escapes have a string value.
300 Normally, component values are compressed by
301 converting any control characters (tab and newline included) to spaces,
302 then eliding any leading or multiple spaces.
304 commands may give different interpretations to some component escapes;
305 be sure to refer to each command's manual entry for complete details.
307 A \fIfunction\fR escape is specified as `%(\fIfunction\fR\^)'.
308 All functions are built-in, and most have a string or numeric value.
311 .Uh "Control-flow escapes"
312 A \fIcontrol\fR escape is one of: `%<', `%?', `%|', or `%>'.
314 These are combined into the conditional execution construct:
329 Extra white space is shown here only for clarity.
330 These constructs may be nested without ambiguity.
331 They form a general \fBif\-elseif\-else\-endif\fP block where
332 only one of the \fIformat text\fP segments is interpreted.
334 The `%<' and `%?' control escapes causes a condition to be evaluated.
336 may be either a \fIcomponent\fP or a \fIfunction\fP.
337 The four constructs have the following syntax:
346 These control escapes test whether
347 the function or component value is non-zero (for integer-valued escapes),
348 or non-empty (for string-valued escapes).
350 If this test evaulates true,
352 up to the next corresponding control escape
353 (one of `%|', `%?', or `%>')
354 is interpreted normally.
356 all format text (if any) up to the corresponding `%>' control
358 The `%>' control escape is not interpreted;
360 interpretation resumes after the `%>' escape.
362 If the test evaluates false, however,
364 up to the next corresponding control escape
365 (again, one of `%|', `%?', or `%>')
366 is skipped, instead of being interpreted.
367 If the control escape encountered was `%?',
368 then the condition associated with that control escape is
369 evaluated, and interpretation
370 proceeds after that test
371 as described in the previous paragraph.
372 If the control escape encountered was `%|',
374 up to the corresponding `%>' escape
375 is interpreted normally.
377 the `%>' escape is not interpreted and normal
378 interpretation resumes after the `%>' escape.
380 The `%?' control escape and its following format text
381 is optional, and may be included zero or more times.
382 The `%|' control escape and its following format text
383 is also optional, and may be included zero or one times.
385 .\" The '%[' and '%]' escapes form a loop construct.
386 .\" For format strings which are executed repeatedly
387 .\" (as with \fIscan\fP), these escapes delimit the main
388 .\" body of execution. Format text which occurs
389 .\" before the '%[' escape is executed once only, prior
390 .\" to processing the first message; format text occuring
391 .\" after the '%]' escape is ignored.
392 .\" (These escapes may not be nested).
394 .Uh "Function escapes"
396 Most functions expect an argument of a particular type:
399 .ta +\w'Argument 'u +\w'An optional component, 'u
400 \fIArgument\fR \fIDescription\fR \fIExample Syntax\fR
401 literal A literal number, %(\fIfunc\fR 1234)
402 or string %(\fIfunc\fR text string)
403 comp Any header component %(\fIfunc\fR\^{\fIin-reply-to\fR\^})
404 date A date component %(\fIfunc\fR\^{\fIdate\fR\^})
405 addr An address component %(\fIfunc\fR\^{\fIfrom\fR\^})
406 expr An optional component, %(\fIfunc\fR\^(\fIfunc2\fR\^))
407 function or control, %(\fIfunc\fR %<{\fIreply-to\fR\^}%|%{\fIfrom\fR\^}%>)
408 perhaps nested %(\fIfunc\fR\^(\fIfunc2\fR\^{\fIcomp\fR\^}))
412 The types \fIdate\fR and \fIaddr\fR have the same syntax
413 as \fIcomp\fR, but require that the header
414 component be a date string, or address string, respectively.
416 All arguments except those of type \fIexpr\fR are required.
417 For the \fIexpr\fR argument type,
418 the leading `%' must be omitted for component and function escape arguments,
419 and must be present (with a leading space) for control escape arguments.
421 The evaluation of format strings
422 is based on a simple machine with an
423 integer register \fInum\fR, and a text string register \fIstr\fR.
424 When a function escape is processed,
425 if it accepts an optional \fIexpr\fR argument which is not present,
426 it reads the current value of either \fInum\fR or \fIstr\fR as appropriate.
430 Component escapes write the value of their message header in \fIstr\fR.
431 Function escapes write their return value in
432 \fInum\fR for functions returning \fIinteger\fR or \fIboolean\fR values,
433 and in \fIstr\fR for functions returning string values.
434 (The \fIboolean\fR type is a subset of integers with usual
435 values 0=false and 1=true.)
436 Control escapes return a \fIboolean\fP value, and set \fInum\fP.
438 All component escapes, and those
439 function escapes which return an \fIinteger\fR or \fIstring\fR value,
440 pass this value back to their caller
441 in addition to setting \fIstr\fR or \fInum\fR.
442 These escapes will print out this value
443 unless called as part of an argument to another escape sequence.
444 Escapes which return a \fIboolean\fR value do pass this value
445 back to their caller in \fInum\fP, but will never print out the value.
448 .ta \w'Formataddr 'u +\w'Argument 'u +\w'Rboolean 'u
449 \fIFunction\fR \fIArgument\fR \fIReturn\fR \fIDescription\fR
450 msg integer message number
451 cur integer message is current
452 .\" unseen integer message is unseen
453 size integer size of message
454 strlen integer length of \fIstr\fR
455 width integer output buffer size in bytes
456 charleft integer bytes left in output buffer
457 timenow integer seconds since the UNIX epoch
458 me string the user's mailbox
459 eq literal boolean \fInum\fR == \fIarg\fR
460 ne literal boolean \fInum\fR != \fIarg\fR
461 gt literal boolean \fInum\fR > \fIarg\fR
462 match literal boolean \fIstr\fR contains \fIarg\fR
463 amatch literal boolean \fIstr\fR starts with \fIarg\fR
464 plus literal integer \fIarg\fR plus \fInum\fR
465 minus literal integer \fIarg\fR minus \fInum\fR
466 divide literal integer \fInum\fR divided by \fIarg\fR
467 modulo literal integer \fInum\fR modulo \fIarg\fR
468 num literal integer Set \fInum\fR to \fIarg\fR
469 lit literal string Set \fIstr\fR to \fIarg\fR
470 getenv literal string Set \fIstr\fR to environment value of \fIarg\fR
471 profile literal string Set \fIstr\fR to profile component \fIarg\fR value
472 .\" dat literal int return value of dat[arg]
473 nonzero expr boolean \fInum\fR is non-zero
474 zero expr boolean \fInum\fR is zero
475 null expr boolean \fIstr\fR is empty
476 nonnull expr boolean \fIstr\fR is non-empty
477 void expr Set \fIstr\fR or \fInum\fR
478 comp comp string Set \fIstr\fR to component text
479 compval comp integer \fInum\fR set to \*(lq\fBatoi\fR(\fIcomp\fR\^)\*(rq
480 .\" compflag comp integer Set \fInum\fR to component flags bits (internal)
481 trim expr trim trailing white-space from \fIstr\fR
482 putstr expr print \fIstr\fR
483 putstrf expr print \fIstr\fR in a fixed width
484 putnum expr print \fInum\fR
485 putnumf expr print \fInum\fR in a fixed width
486 .\" addtoseq literal add msg to sequence (LBL option)
490 These functions require a date component as an argument:
493 .ta \w'Formataddr 'u +\w'Argument 'u +\w'Rboolean 'u
494 \fIFunction\fR \fIArgument\fR \fIReturn\fR \fIDescription\fR
495 sec date integer seconds of the minute
496 min date integer minutes of the hour
497 hour date integer hours of the day (0-23)
498 wday date integer day of the week (Sun=0)
499 day date string day of the week (abbrev.)
500 weekday date string day of the week
501 sday date integer day of the week known?
502 (0=implicit,\-1=unknown)
503 mday date integer day of the month
504 yday date integer day of the year
505 mon date integer month of the year
506 month date string month of the year (abbrev.)
507 lmonth date string month of the year
508 year date integer year (may be > 100)
509 zone date integer timezone in hours
510 tzone date string timezone string
511 szone date integer timezone explicit?
512 (0=implicit,\-1=unknown)
513 date2local date coerce date to local timezone
514 date2gmt date coerce date to GMT
515 dst date integer daylight savings in effect?
516 clock date integer seconds since the UNIX epoch
517 rclock date integer seconds prior to current time
518 tws date string official 822 rendering
519 pretty date string user-friendly rendering
520 nodate date integer \fIstr\fR not a date string
525 These functions require an address component as an argument.
526 The return value of functions noted with `*' pertain only to
527 the first address present in the header component.
530 .ta \w'Formataddr 'u +\w'Argument 'u +\w'Rboolean 'u
531 \fIFunction\fR \fIArgument\fR \fIReturn\fR \fIDescription\fR
532 proper addr string official 822 rendering
533 friendly addr string user-friendly rendering
534 addr addr string mbox@@host or host!mbox rendering*
535 pers addr string the personal name*
536 note addr string commentary text*
537 mbox addr string the local mailbox*
538 mymbox addr integer the user's addresses? (0=no,1=yes)
539 host addr string the host domain*
540 nohost addr integer no host was present*
541 type addr integer host type* (0=local,1=network,
543 path addr string any leading host route*
544 ingrp addr integer address was inside a group*
545 gname addr string name of group*
546 formataddr expr append \fIarg\fR to \fIstr\fR as a
547 (comma separated) address list
548 putaddr literal print \fIstr\fR address list with
549 \fIarg\fR as optional label;
550 get line width from \fInum\fR
554 When escapes are nested, evaluation is done from inner-most to outer-most.
555 The outer-most escape must begin with `%'; the inner escapes must not.
559 %<(mymbox{from}) To: %{to}%>
561 writes the value of the header component \*(lqFrom:\*(rq to \fIstr\fR\^;
562 then (\fImymbox\fR\^) reads \fIstr\fR
563 and writes its result to \fInum\fR;
564 then the control escape evaluates \fInum\fR. If \fInum\fR is
565 non-zero, the string \*(lqTo: \*(rq is printed followed by
566 the value of the header component \*(lqTo:\*(rq.
568 A minor explanation of (\fImymbox\fR\^{\fIcomp\fR\^}) is in order.
569 In general, it checks each of the addresses in the header component
571 against the user's mailbox name and any \fIAlternate-Mailboxes\fR.
572 It returns true if any address matches, however, it
573 also returns true if the \*(lq\fIcomp\fR\*(rq header is not present
574 in the message. If needed, the (\fInull\fR\^) function can be
575 used to explicitly test for this condition.
577 When a function or component escape is interpreted and the result
578 will be immediately printed,
579 an optional field width can be
580 specified to print the field in exactly a given number of characters.
581 For example, a numeric escape like %4(\fIsize\fR\^) will print at most 4
582 digits of the message size; overflow will be indicated by a `?' in the
583 first position (like `?234').
584 A string escape like %4(\fIme\fR\^) will print the first 4 characters and
586 Short fields are padded at the right with the fill character (normally,
587 a blank). If the field width argument begins with a leading zero,
588 then the fill character is set to a zero.
591 the functions (\fIputnumf\fR\^) and (\fIputstrf\fR\^) print their result in
592 exactly the number of characters specified by their leading field width
595 %06(\fIputnumf\fR\^(\fIsize\fR\^)) will print the message size
596 in a field six characters wide filled with leading zeros;
597 %14(\fIputstrf\^\fR{\fIfrom\^\fR}) will print
598 the \*(lqFrom:\*(rq header component in fourteen characters with
599 trailing spaces added as needed.
601 using a negative value for the field width causes right-justification
602 of the string within the field,
603 with padding on the left up to the field width.
604 The functions (\fIputnum\fR\^) and (\fIputstr\fR\^) print their result in
605 the minimum number of characters required, and ignore any leading
606 field width argument.
608 The available output width is kept in an internal register; any output past
609 this width will be truncated.
611 Comments may be inserted in most places where a function argument
612 is not expected. A comment begins with `%;' and ends with
613 a (non-escaped) newline.
615 With all this in mind,
616 here's the default format string for \fIscan\fR.
617 It's been divided into several pieces for readability.
621 %4(msg)%<(cur)+%| %>%<{replied}\-%?{encrypted}E%| %>
623 which says that the message number should be printed in four digits,
624 if the message is the current message then a `+' else a space should be
626 and if a \*(lqReplied:\*(rq field is present then a `\-' else
627 if an \*(lqEncrypted:\*(rq field is present then an `E' otherwise
628 a space should be printed.
632 %02(mon{date})/%02(mday{date})
634 the month and date are printed in two digits (zero filled) separated by
641 If a \*(lqDate:\*(rq field was present,
642 then a space is printed, otherwise a `*'.
646 %<(mymbox{from})%<{to}To:%14(friendly{to})%>%>
648 if the message is from me,
649 and there is a \*(lqTo:\*(rq header,
650 print `To:' followed by a \*(lquser-friendly\*(rq rendering of the
651 first address in the \*(lqTo:\*(rq field.
655 %<(zero)%17(friendly{from})%>
657 if either of the above two tests failed,
658 then the \*(lqFrom:\*(rq address is printed
659 in a \*(lquser-friendly\*(rq format.
663 %{subject}%<{body}<<%{body}%>
665 the subject and initial body (if any) are printed.
667 For a more complicated example, next consider
668 the default \fIreplcomps\fR format file.
671 %(lit)%(formataddr %<{reply-to}
673 This clears \fIstr\fR and formats the \*(lqReply-To:\*(rq header
674 if present. If not present, the else-if clause is executed.
677 %?{from}%?{sender}%?{return-path}%>)\\
680 \*(lqFrom:\*(rq, \*(lqSender:\*(rq and \*(lqReturn-Path:\*(rq
681 headers, stopping as soon as one of them is present. Next:
684 %<(nonnull)%(void(width))%(putaddr To: )\\n%>\\
686 If the \fIformataddr\fR result is non-null, it is printed as
687 an address (with line folding if needed) in a field \fIwidth\fR
688 wide with a leading label of \*(lqTo: \*(rq.
691 %(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\\
693 \fIstr\fR is cleared, and the
694 \*(lqTo:\*(rq and \*(lqCc:\*(rq headers, along with the user's
696 (depending on what was specified with
697 the \*(lq\-cc\*(rq switch to \fIrepl\fR\^) are formatted.
700 %<(nonnull)%(void(width))%(putaddr cc: )\\n%>\\
702 If the result is non-null, it is printed as above with a
703 leading label of \*(lqcc: \*(rq.
706 %<{fcc}Fcc: %{fcc}\\n%>\\
708 If a \*(lq\-fcc\ folder\*(rq switch was given to \fIrepl\fR
709 (see \fIrepl\fR\0(1) for more details about %{\fIfcc\fR\^}),
710 an \*(lqFcc:\*(rq header is output.
713 %<{subject}Subject: Re: %{subject}\\n%>\\
715 If a subject component was present,
716 a suitable reply subject is output.
720 %<{date}In-reply-to: Your message of "\\
722 %<(nodate{date})%{date}%|%(pretty{date})%>."%<{message-id}
724 %{message-id}%>\\n%>\\
729 If a date component was present,
730 an \*(lqIn-Reply-To:\*(rq header is output with the preface
731 \*(lqYour message of \*(rq. If the date was parseable, it is
732 output in a user-friendly format, otherwise it is output as-is.
733 The message-id is included if present.
734 As with all plain-text,
735 the row of dashes are output as-is.
737 This last part is a good example for a little more elaboration.
738 Here's that part again in pseudo-code:
743 if (comp_exists(date)) then
744 print (\*(lqIn-reply-to: Your message of \\\*(lq\*(rq)
745 if (not_date_string(date.value) then
748 print (pretty(date.value))
750 print (\*(lq\\\*(rq\*(rq)
751 if (comp_exists(message-id)) then
752 print (\*(lq\\n\\t\*(rq)
753 print (message-id.value)
755 print (\*(lq\\n\*(rq)
761 Although this seems complicated,
763 this method is flexible enough to extract individual fields and print them in
764 any format the user desires.
770 scan(1), repl(1), ap(8), dp(8)
776 This software was contributed for MH 6.3. Prior to this, output
777 format specifications were much easier to write, but considerably
780 On hosts where \fIMH\fR was configured with the BERK option,
781 address parsing is not enabled.
788 @think about documenting %[ %]
793 .\" @@(#)$Id: mh-format.rf,v 1.45 1993/08/19 20:26:17 jromine Exp jromine $
800 @re-describe "profile"
805 .\" @@(#)$Id: mh-format.rf,v 1.44 1993/06/12 06:49:57 jromine Exp jromine $
810 .\" compflag comp integer Set \fInum\fR to component flags bits
816 @document %(profile xxx)
821 .\" @@(#)$Id: mh-format.rf,v 1.43 1992/12/02 18:41:50 jromine Exp jromine $
824 profile literal string Set \fIstr\fR to value of profile or context \fIarg\fR
835 .\" @@(#)$Id: mh-format.rf,v 1.42 1992/11/20 19:35:06 jromine Exp jromine $
847 .\" @@(#)$Id: mh-format.rf,v 1.41 1992/10/28 23:03:14 jromine Exp jromine $
850 is not expected. A comment line begins with `%;' and ends with
856 @make scan/repl strings match actual defaults
861 .\" @@(#)$Id: mh-format.rf,v 1.40 1992/10/27 00:20:03 jromine Exp jromine $
864 writes the value of the header component \*(lqFrom:\*(rq to \fIstr\fR;
875 .\" @@(#)$Id: mh-format.rf,v 1.39 1992/10/26 17:03:42 jromine Exp jromine $
878 here's a format string for \fIscan\fR.
881 %4(msg)%<(cur)+%| %>%<{replied}\-%| %>
884 and if a \*(lqReplied:\*(rq field is present then a `\-' else a space should
891 @fixup typos (from Jerry Peek)
896 .\" @@(#)$Id: mh-format.rf,v 1.38 1992/05/12 22:23:34 jromine Exp jromine $
899 here's the default format string for \fIscan\fR.
902 %<(nodate{date})%{date}%|%(tws{date})%>."%<{message-id}
905 output in official format, otherwise it is output as-is.
911 @fixup for nroff problems
916 .\" @@(#)$Id: mh-format.rf,v 1.37 1992/02/18 17:28:26 jromine Exp jromine $
919 header \fIcomponents\fR, built-in \fIfunctions\fR, and, flow \fIcontrol\fR.
922 all format text up to the corresponding `%>' control
923 escape (if any) is skipped.
926 print (rfc822(date.value))
937 .\" @@(#)$Id: mh-format.rf,v 1.36 1992/02/14 19:14:42 jromine Exp jromine $
941 mh\-format \- format file for MH message system
952 .\" @@(#)$Id: mh-format.rf,v 1.35 1992/02/11 05:03:41 jromine Exp jromine $
955 unseen integer message is unseen
966 .\" @@(#)$Id: mh-format.rf,v 1.34 1992/02/09 22:11:10 jromine Exp jromine $
969 compval comp integer \fInum\fR set to \*(lq\fBatoi\fR(\fIstr\fR\^)\*(rq
975 @document control escape return values
976 put new scan.default and replcomps format strings in.
981 .\" @@(#)$Id: mh-format.rf,v 1.33 1992/02/09 07:18:01 jromine Exp jromine $
993 .\" @@(#)$Id: mh-format.rf,v 1.32 1992/02/07 01:08:25 jromine Exp jromine $
997 Function escapes which return a \fIboolean\fR value do pass this value
998 back to their caller, but will never print out the value.
1001 .\" addtoseq literal add msg to sequence
1005 %<(mymbox{from})To:%14(friendly{to})
1009 %|%17(friendly{from})%>
1012 if the message isn't from me,
1013 then the print the \*(lqFrom:\*(rq address is printed.
1016 %(lit)%(formataddr %<{reply-to}%|
1019 if present. If not present, the else clause is executed:
1022 %<{from}%|%<{sender}%|%<{return-path}%>%>%>%>)\\
1033 .\" @@(#)$Id: mh-format.rf,v 1.31 1992/02/06 00:13:07 jromine Exp jromine $
1037 .\" dat literal int ?
1044 @remove putstr[f] -- they're not in the default file
1049 .\" @@(#)$Id: mh-format.rf,v 1.30 1992/01/29 22:55:31 jromine Exp jromine $
1052 year date integer year of the century
1063 .\" @@(#)$Id: mh-format.rf,v 1.29 1991/01/11 09:17:35 mh Exp jromine $
1066 %4(putnumf(msg))%<(cur)+%| %>%<{replied}\-%| %>
1069 %02(putnumf(mon{date}))/%02(putnumf(mday{date}))
1072 %<(mymbox{from})To:%14(putstrf(friendly{to}))
1075 %|%17(putstrf(friendly{from}))%>
1081 @change "\-" to "-" where appropriate
1086 .\" @@(#)$Id: mh-format.rf,v 1.28 91/01/11 09:15:19 mh Exp Locker: mh $
1093 @add "elseif" documentation
1099 .\" @@(#)$Id: mh-format.rf,v 1.27 90/12/27 17:22:27 mh Exp Locker: mh $
1102 multi\-character \fIescape\fR sequences which begin with `%'.
1105 header \fIcomponents\fR, built\-in \fIfunctions\fR, and, flow \fIcontrol\fR.
1108 nonzero expr boolean \fInum\fR is non\-zero
1111 nonnull expr boolean \fIstr\fR is non\-empty
1114 trim expr trim trailing white\-space from \fIstr\fR
1117 pretty date string user\-friendly rendering
1120 friendly addr string user\-friendly rendering
1123 print `To:' followed by a \*(lquser\-friendly\*(rq rendering of the
1126 If the \fIformataddr\fR result is non\-null, it is printed as
1129 If the result is non\-null, it is printed as above with a
1132 output in official format, otherwise it is output as\-is.
1135 As with all plain\-text,
1136 the row of dashes are output as\-is.
1139 Here's that part again in pseudo\-code:
1145 @document "addr" format
1151 .\" @@(#)$Id: mh-format.rf,v 1.26 90/04/05 15:09:13 sources Exp Locker: mh $
1154 All functions are built\-in, and most have a string or numeric value.
1158 A \fIcontrol\fR escape is one of: `%<', `%|', or `%>'.
1159 These form one of four conditional execution constructs with the
1164 %<(\fIfunction\fR\^)Command-String%>
1165 %<{\fIcomponent\fR\^}Command-String%>
1166 %<(\fIfunction\fR\^)Then-Command-String%|Else-Command-String%>
1167 %<{\fIcomponent\fR\^}Then-Command-String%|Else-Command-String%>
1172 In the first two forms of the construct,
1173 if the function or component value is non\-zero (for integer\-valued escapes),
1174 or non\-empty (for string\-valued escapes),
1175 then everything up to the corresponding `%>'
1176 is interpreted, otherwise, skip to the corresponding '%>' and
1177 start interpreting again.
1180 In the second two forms of the construct,
1181 the first command string is interpreted
1182 if the function or component value is non\-zero or non\-null,
1183 and the second command string is interpreted otherwise. Only one
1184 of the command strings will be interpreted.
1185 Interpreting the '%|' control escape causes
1186 a skip to the corresponding '%>'.
1191 %<(mymbox{from} To: %{to}%>
1226 %<{from}%|%<{sender}%|%<{return-path}%>%>%>%>)
1229 %<(nonnull)%(void(width))%(putaddr To: )\\n%>
1232 %(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))
1235 %<(nonnull)%(void(width))%(putaddr cc: )\\n%>
1238 %<{fcc}Fcc: %{fcc}\\n%>
1241 %<{subject}Subject: Re: %{subject}\\n%>
1244 %<{date}In-reply-to: Your message of
1247 %<(nodate{date})%{date}%|%(tws{date})%>.%<{message-id}
1250 %{message-id}%>\\n%>
1253 This is a good example for a little more elaboration.
1256 print (\*(lqIn-reply-to: Your message of \*(rq)
1268 writes the value of the header component \fI{from}\fR to \fIstr\fR;
1269 then \fI(mymbox)\fR reads \fIstr\fR
1272 the value of the header component \fI{to}\fR.
1275 in the message. If needed, the (\fInull\fR) function can be
1278 For example, a numeric escape like \fI%4(size)\fR will print at most 4
1281 A string escape like \fI%4(me)\fR will print the first 4 characters and
1284 the functions \fIputnumf\fR and \fIputstrf\fR print their result in
1287 The functions \fIputnum\fR and \fIputstr\fR print their result in
1290 %<{from}%|%<{sender}%|%{return-path}%>%>%>)
1293 the \*(lq\-cc\*(rq switch to \fIrepl\fR) are formatted.
1304 A minor explanation of (\fImymbox\fR\|{\fIcomp\fR\|}) is in order.
1307 %06(\fIputnumffR\|(\fIsizefR\|)) will print the message size
1310 %14(\fIputstrf\|\fR{\fIfrom\|\fR}) will print
1313 (see \fIrepl\fR\0(1) for more details about %{\fIfcc\fR\|}),
1319 @follow TECO manual description of conditionals
1324 A \fIcontrol\fR escape is one of:
1325 `%<(\fIfunction\fR\^)' or `%<{\fIcomponent\fR\^}', `%|', and `%>'.
1326 These form a conditional execution construct with the following syntax:
1329 %<\fIescape\fR command-string %>
1331 %<\fIescape\fR then-command-string %| else-command-string %>
1334 In the first form of the construct,
1337 In the second form of the construct,
1340 putstrf expr print \fIstr\fR in fixed width
1343 putnumf expr print \fInum\fR in fixed width
1346 When a function escape is interpreted, an optional output width can be
1347 specified to limit the field width to a maximum number of characters.
1350 truncate at the end.
1353 The functions \fIputnumf\fR and \fIputstrf\fR print their result in
1354 exactly the number of characters specified. For example,
1355 \fI%06(putnumf(size))\fR will print the message size
1358 \fI%14(putstrf{from})\fR will print
1365 @put things back, do .NA stuff another way
1370 `%<(\fIfunction\fR\^)' or `%<{\fIcomponent\fR\^}', `%|', and `%>',
1371 which correspond to if\-then\-else constructs.
1372 They may be nested without ambiguity.
1373 If the function or component value is non\-zero (for integer\-valued escapes),
1376 then everything up to the corresponding `%|' or `%>'
1377 (whichever comes first) is interpreted;
1378 otherwise, skip to the corresponding `%|' or `%>' (whichever comes first)
1379 and start interpreting again.
1385 @add example pseudo-code from Phyllis Kantar
1390 .TH MH\-FORMAT 5 @@(MHCENTERFOOT) @@(MHLEFTFOOT)
1405 \*(lqYour message of\*(rq. If the date was parseable, it is
1412 @fixup for makewhatis
1417 .TH MH\-FORMAT 5 [mh.6] MH
1423 @more fixes from Phyllis Kantar
1443 which correspond to if\-then\-else constructs:
1444 if the function or component value is non\-zero (for integer\-valued escapes),
1447 then everything up to `%|' or `%>' (whichever comes first) is interpreted;
1448 otherwise, then skip to `%|' or `%>' (whichever comes first)
1451 mymbox addr integer the user's mailbox? (0=no,1=yes)
1454 then \fI(mymbox)\fR reads \fIstr\fR and writes its result to \fInum\fR;
1458 the month and date are printed in two digits (zero filled).
1461 If no \*(lqDate:\*(rq field was present,
1462 then a `*' is printed, otherwise a space.
1465 If a \*(lq\-fcc\ folder\*(rq switch was given,
1468 A suitable reply subject is output.
1471 If a date was present,
1472 An \*(lqIn-Reply-To:\*(rq header is output. As with all plain\-text,
1481 @mention component compression
1486 putstrf expr print \fIstr\fR in fixed width.
1489 putnumf expr print \fInum\fR in fixed width.
1492 min date integer minutes of the day
1495 zsone date integer timezone explicit?
1498 leading lable of \*(lqcc: \*(rq.
1501 If a \*(lq\-fcc\*(rq switch was given, an \*(lqFcc:\*(rq header is output.
1505 An \*(lqIn-Reply-To:\*(rq header is output.
1511 @remove some info about repl - complete details in repl(1).
1516 Different commands may interpret some component escapes differently;
1522 @suggest referencing command man pages for more details
1527 the default \fIreplcomps\fR format file. \fIrepl\fR
1528 resets the line width each time after printing a `\\n'.
1531 If a subject was present, it is output prefaced with \*(lqRe: \*(rq.
1532 (The \fI{subject}\fR component has any leading \*(lqRe: \*(rq stripped).
1535 An \*(lqIn-Reply-To:\*(rq header is output. If a date was present,
1536 it is included with the preface \*(lqYour message of \*(rq.
1542 @indicate which {addr} funcs return value for first addr only'
\7f
1556 These functions require an address component as an argument:
1559 pers addr string the personal name
1560 note addr string commentary text
1561 mbox addr string the local mailbox
1564 host addr string the host domain
1565 nohost addr integer no host was present
1566 type addr integer host type (0=local,1=network,
1569 path addr string any leading host route
1570 ingrp addr integer address was inside a group
1571 gname addr string name of group
1572 (set for first address only)
1587 @final. this is a major revision -- i hope it was worth it.
1593 .\" Some functions expect an extra literal string or integer parameter,
1594 .\" and are specified as `%(\fIfunction\fR argument)'.
1595 .\" Many functions require a component argument, and are
1596 .\" specified as `%(\fIfunction\fR\^{\fIcomponent\fR\^})'.
1597 .\" Some functions will accept another function as an argument. These
1598 .\" may be nested, and are evaluated inner\-most to outer\-most.
1599 .\" This nesting is specified as `%(\fIfunction2\fR\^(\fIfunction1\fR\^))'.
1600 .\" If a function accepts an argument, it is of
1601 .\" one of these six types: \fIint\fR\^,
1602 .\" \fIstring\fR\^, \fIcomp\fR\^, \fIexpr\fR\^,
1603 .\" \fIdate\fR\^, and \fIaddr\fR\^.
1606 These functions require a date header component as an argument:
1607 .\" When \fIstr\fR is a date, these escapes are useful:
1611 These functions require an address header component as an argument:
1612 .\" When \fIstr\fR is an address, these escapes are useful:
1615 \fI%6(putnumf(size))\fR will print the message size right\-justified
1616 in a field six characters wide; \fI%14(putstrf{from})\fR will print
1617 the \*(lqFrom:\*(rq header component left\-justified in fourteen characters.
1620 %<{date}In-reply-to: Your message of \\
1628 @checkpoint before mentioning replcomps
1634 This manual section attempts to explain how to do that.
1637 If the `\-form\ formatfile' switch is given,
1638 \fIscan\fR will treat each line in the named file as a format string and act
1640 This lets the user employ canned scan listing formats.
1641 Take a look at the three files
1642 @@(MHETCPATH)/scan.time, @@(MHETCPATH)/scan.size, and @@(MHETCPATH)/scan.timely.
1653 Component escapes are all string valued.
1656 A \fIfunction\fR escape is specified as `%(\fIfunction\fR\^)',
1657 and is statically defined.
1660 if the function or component is non\-zero (for integer\-valued escapes),
1663 and must be present for control escape arguments.
1666 (The \fIboolean\fR type is a subset of integers; 0=false and 1=true are
1667 usually the only values.)
1670 putstrf expr print using width; \*(lq\fI%20(putstrf)\fR\*(rq
1673 putnumf expr print using width; \*(lq\fI%4(putnumf)\fR\*(rq
1676 When a function escape is interpreted, the output width can be
1677 limited to a maximum number of characters.
1689 A \fIcomponent\fR escape is specified as `%{\fIcomponent\fR\|}',
1692 A \fIfunction\fR escape is specified as `%(\fIfunction\fR\|)',
1695 `%<(\fIfunction\fR\|)' or `%<{\fIcomponent\fR\|}', `%|', and `%>',
1698 .\" specified as `%(\fIfunction\fR\|{\fIcomponent\fR\|})'.
1701 .\" This nesting is specified as `%(\fIfunction2\fR\|(\fIfunction1\fR\|))'.
1704 .\" one of these six types: \fIint\fR\|,
1705 .\" \fIstring\fR\|, \fIcomp\fR\|, \fIexpr\fR\|,
1706 .\" \fIdate\fR\|, and \fIaddr\fR\|.
1709 comp Any header component %(\fIfunc\fR\|{\fIin-reply-to\fR\|})
1710 date A date component %(\fIfunc\fR\|{\fIdate\fR\|})
1711 addr An address component %(\fIfunc\fR\|{\fIfrom\fR\|})
1712 expr An optional component, %(\fIfunc\fR\|(\fIfunc2\fR\|))
1713 function or control, %(\fIfunc\fR\|(\fIfunc2\fR\|{\fIcomp\fR\|}))
1714 perhaps nested %(\fIfunc\fR %<{\fIreply-to\fR\|}%|%{\fIfrom\fR\|}%>)
1719 compval comp integer \fInum\fR set to \*(lq\fBatoi\fR(\fIstr\fR\|)\*(rq
1730 means they are not necessarily simple for humans to parse.
1733 When specifying a string,
1739 The \fIescape\fR sequences are of three types:
1742 Most functions expect an argument of a particular type:
1748 .ta 4 +\w'Argument 'u +\w'a component or function, 'u
1749 \fIArgument\fR \fIDescription\fR \fISyntax\fR
1750 int a literal number %(\fIfunc\fR number)
1751 string a literal string %(\fIfunc\fR text string)
1752 comp any header component %(\fIfunc\fR\|{\fIcomp\fR\|})
1753 date a date component %(\fIfunc\fR\|{\fIdate\fR\|})
1754 addr an address component %(\fIfunc\fR\|{\fIaddr\fR\|})
1755 expr a component or function, %(\fIfunc\fR\|(\fIfunc2\fR\|))
1756 perhaps nested %(\fIfunc\fR\|(\fIfunc2\fR\|{\fIcomp\fR\|}))
1759 The types \fIdate\fR and \fIaddr\fR require that the header
1762 if it requires a non\-literal argument,
1765 Function results are written in
1766 \fInum\fR for \fIint\fR and \fIbool\fR values, or \fIstr\fR
1767 for string values. (The \fIbool\fR type
1768 is a subset of integers; usually 0=false, 1=true.)
1769 All component escapes set \fIstr\fR with the value of their message header.
1772 .\" A few function escapes accept a literal string or numeric argument,
1773 .\" but most use the value of \fInum\fR or \fIstr\fR
1774 .\" as their argument if needed.
1776 All component escapes, and
1777 nearly all function escapes return a value in addition to setting \fIstr\fR
1778 or \fInum\fR. These escapes will print out this value
1779 unless called from within another escape sequence.
1780 A few function escapes do not print their results; these are indicated
1781 in the \fIPrint Result?\fR column of the tables below.
1785 .ta \w'Rbool,no 'u +\w'Formataddr 'u +\w'Argument 'u
1786 \fIReturn\fR \fIFunction\fR \fIArgument\fR \fIDescription\fR
1788 int msg message number
1789 int cur message is current
1790 int size size of message
1791 int strlen length of \fIstr\fR
1792 int width output buffer size in bytes
1793 int charleft bytes left in output buffer
1794 int timenow seconds since the UNIX epoch
1795 string me the user's mailbox
1796 bool,no eq lit int \fInum\fR == \fIarg\fR
1797 bool,no ne lit int \fInum\fR != \fIarg\fR
1798 bool,no gt lit int \fInum\fR > \fIarg\fR
1799 int plus lit int \fIarg\fR plus \fInum\fR
1800 int minus lit int \fIarg\fR minus \fInum\fR
1801 int divide lit int \fInum\fR divided by \fIarg\fR
1802 int num lit int Set \fInum\fR to \fIarg\fR
1803 .\" int dat lit int ?
1804 bool,no match lit str \fIstr\fR contains \fIarg\fR
1805 bool,no amatch lit str \fIstr\fR starts with \fIarg\fR
1806 string lit lit str Set \fIstr\fR to \fIarg\fR
1807 bool,no nonzero expr \fInum\fR is non\-zero
1808 bool,no zero expr \fInum\fR is zero
1809 bool,no null expr \fIstr\fR is empty
1810 bool,no nonnull expr \fIstr\fR is non\-empty
1811 no void expr Set \fIstr\fR or \fInum\fR
1812 string comp comp Set \fIstr\fR to component text
1813 int compval comp \fInum\fR set to \fBatoi\fR of \fIstr\fR
1814 bool compflag comp Set \fInum\fR to component flags bits
1815 putstr expr print \fIstr\fR
1816 putstrf expr print using width; \*(lq\fI%20(putstrf)\fR\*(rq
1817 putnum expr print \fInum\fR
1818 putnumf expr print using width; \*(lq\fI%4(putnumf)\fR\*(rq
1822 When \fIstr\fR is a date, these escapes are useful:
1825 .ta \w'Rbool,no 'u +\w'Formataddr 'u +\w'Argument 'u
1826 \fIReturn\fR \fIFunction\fR \fIArgument\fR \fIDescription\fR
1828 int sec date seconds of the minute
1829 int min date minutes of the day
1830 int hour date hours of the day (0-23)
1831 int wday date day of the week (Sun=0)
1832 string day date day of the week (abbrev.)
1833 string weekday date day of the week
1834 bool sday date day of the week known?
1837 int mday date day of the month
1838 int yday date day of the year
1839 int mon date month of the year
1840 string month date month of the year (abbrev.)
1841 string lmonth date month of the year
1842 int year date year of the century
1843 int zone date timezone in hours
1844 string tzone date timezone string
1845 bool zsone date timezone explicit?
1848 bool dst date daylight savings in effect?
1849 int clock date seconds since the UNIX epoch
1850 int rclock date seconds prior to current time
1851 string tws date official 822 rendering
1852 string pretty date user\-friendly rendering
1853 bool,no nodate date \fIstr\fR not a date string
1854 no date2local date coerce date to local timezone
1855 no date2gmt date coerce date to GMT
1859 When \fIstr\fR is an address, these escapes are useful:
1862 .ta \w'Rbool,no 'u +\w'Formataddr 'u +\w'Argument 'u
1863 \fIReturn\fR \fIFunction\fR \fIArgument\fR \fIDescription\fR
1865 string proper addr official 822 rendering
1866 string friendly addr user\-friendly rendering
1867 string pers addr the personal name
1868 string note addr commentary text
1869 string mbox addr the local mailbox
1870 bool mymbox addr is this the user's mailbox?
1871 string host addr the host domain
1872 bool nohost addr no host was present
1873 bool type addr host type (0=local,1=network,
1876 string path addr any leading host route
1877 bool ingrp addr address was inside a group
1878 string gname addr name of group
1881 no formataddr expr append \fIarg\fR to \fIstr\fR as a
1884 putaddr lit str print \fIstr\fR address list with
1890 For example, \fI%<(mymbox{from} To: %{to}%>\fR writes the value of \fI{from}\f
1892 to \fIstr\fR; then \fI(mymbox)\fR reads \fIstr\fR and writes to \fInum\fR;
1893 then the control escape evaluates \fInum\fR.
1897 %{subject}%<{body}<<%{body}%>
1900 the subject and initial body are printed.
1912 Format strings are designed to be efficiently parsed by \fIMH\fR since they
1913 represent an integral part of \fIMH\fR.
1919 This manual section explains how to do just that.
1922 A format string is similar to a \fIprintf\fR\0(3) string,
1923 but uses multi\-letter `%'\-escapes.
1926 Continuation lines in format files end with `\\' followed by the newline
1930 The interpretation model is based on a simple machine with two registers,
1931 \fInum\fR and \fIstr\fR.
1932 The former contains an integer value, the latter a string value.
1933 When an escape is processed,
1934 if it requires an argument,
1935 it reads the current value of either \fInum\fR or \fIstr\fR;
1937 if it returns a value, it writes either \fInum\fR or \fIstr\fR.
1940 Escapes are of three types:
1941 \fIcomponents\fR, \fIfunctions\fR, and, \fIcontrol\fR.
1942 A component escape is specified as `%{name}',
1943 and is created for each header found in the message being processed.
1944 For example `%{date} refers to the \*(lqDate:\*(rq field of the appropriate
1947 A component escape is always string valued.
1950 A control escape is one of: `%<escape', `%|', and `%>',
1953 if `escape' is non\-zero (for integer\-valued escapes),
1956 A function escape is specified as `%(name)',
1957 and is statically defined.
1958 Some function escapes accept an extra literal parameter,
1959 like `%(name literal)'.
1963 .ta \w'Rstring 'u +\w'Formataddr 'u +\w'Astring 'u +\w'yes 'u
1966 \fItype\fR \fIPrint?\fR
1967 int num int yes Set \fInum\fR to \fIarg\fR
1968 string lit string yes Set \fIstr\fR to \fIarg\fR (could be empty)
1969 void expr no Set \fIstr\fR or \fInum\fR -- not interpreted
1970 bool eq int no \fInum\fR == \fIarg\fR
1971 bool ne int no \fInum\fR != \fIarg\fR
1972 bool gt int no \fInum\fR > \fIarg\fR
1973 bool nonzero expr no \fInum\fR is non\-zero
1974 bool zero expr no \fInum\fR is zero
1975 bool match string no \fIstr\fR contains \fIarg\fR
1976 bool amatch string no \fIstr\fR starts with \fIarg\fR
1977 bool null expr no \fIstr\fR is empty
1978 bool nonnull expr no \fIstr\fR is non\-empty
1979 int plus int yes add \fIarg\fR to \fInum\fR
1980 int minus int yes subtract \fIarg\fR from \fInum\fR, or change sign
1981 int divide int yes divide \fInum\fR by \fIarg\fR
1983 string comp comp yes ?
1984 int compval comp yes \fInum\fR set to \fBatoi\fR of \fIstr\fR
1985 bool compflag comp yes NOT WORTH IT? RETURNS -1 OR 0.?
1986 int msg yes message number
1987 int cur yes message is current
1988 int size yes size of message
1989 int strlen yes length of \fIstr\fR
1990 int width yes size (characters) of output buffer
1991 int charleft yes space left in output buffer
1992 int timenow yes seconds since the UNIX epoch
1993 string me yes the user's mailbox
1994 putstr expr yes print \fIstr\fR
1995 putstrf expr yes print using width; \*(lq\fI%20(putstrf)\fR\*(rq
1996 putnum expr yes print \fInum\fR
1997 putnumf expr yes print using width; \*(lq\fI%4(putnumf)\fR\*(rq
2000 .ta \w'Rstring 'u +\w'Formataddr 'u +\w'Astring 'u +\w'yes 'u
2003 \fItype\fR \fIPrint?\fR
2004 int sec date yes seconds of the minute
2005 int min date yes minutes of the day
2006 int hour date yes hours of the day (24 hour clock)
2007 int wday date yes day of the week (Sun=0)
2008 string day date yes day of the week (3 character abbrev.)
2009 string weekday date yes day of the week (long form)
2010 bool sday date yes day of the week known (0=implicit,\-1=unknown)
2011 int mday date yes day of the month
2012 int yday date yes day of the year
2013 int mon date yes month of the year
2014 string month date yes month of the year (3 character abbrev.)
2015 string lmonth date yes month of the year (long form)
2016 int year date yes year of the century
2017 int zone date yes timezone in hours
2018 string tzone date yes timezone string
2019 bool zsone date yes timezone explicit (0=implicit,\-1=unknown)
2020 bool dst date yes daylight savings in effect
2021 int clock date yes seconds since the UNIX epoch
2022 int rclock date yes seconds prior to current time
2023 string tws date yes official 822 rendering of the date
2024 string pretty date yes a more user\-friendly rendering
2025 bool nodate date no string not parseable as a date
2028 .ta \w'Rstring 'u +\w'Formataddr 'u +\w'Astring 'u +\w'yes 'u
2031 \fItype\fR \fIPrint?\fR
2032 string pers addr yes the personal name of the address
2033 string mbox addr yes the local part of the address
2034 string host addr yes the domain part of the address
2035 string path addr yes the route part of the address
2036 int type addr yes host type (\-1=uucp,0=local,1=network,2=unknown)
2037 bool nohost addr yes no host was present in the address
2038 bool ingrp addr yes the address appeared inside a group
2039 string gname addr yes name of the group (set for first address only)
2040 string note addr yes commentary text
2041 string proper addr yes official 822 rendering of the address
2042 string friendly addr yes a more user\-friendly rendering
2043 bool mymbox addr yes the address refers to the user's mailbox
2044 formataddr expr no append \fIarg\fR to \fIstr\fP as an address list
2045 putaddr string yes print stored address list with \fIarg\fR as
2046 optional label; get line width from \fInum\fR
2047 EXAMPLE: \fI%(void(width))%(putaddr Cc: )\fR
2053 @changes from Jerry Peek
2058 Some function escapes accept an extra literal parameter, like `%(name literal)
2060 these are shown in the list below as \fIL\fR.
2063 .ta \w'formataddr 'u +\w'argument 'u +\w'returns 'u
2064 \fIescape\fR \fIargument\fR \fIreturns\fR \fIinterpretation\fR
2065 nonzero integer integer \fInum\fR is non\-zero
2066 zero integer integer \fInum\fR is zero
2067 eq \fIL\fR integer integer \fInum\fR == \fIL\fR
2068 ne \fIL\fR integer integer \fInum\fR != \fIL\fR
2069 gt \fIL\fR integer integer \fInum\fR > \fIL\fR
2070 num \fIL\fR integer put \fIL\fR into \fInum\fR
2072 null string integer \fIstr\fR is empty
2073 nonnull string integer \fIstr\fR is non\-empty
2074 match \fIL\fP string integer \fIstr\fR contains \fIL\fR
2075 amatch \fIL\fR string integer \fIstr\fR starts with \fIL\fR
2076 compval string integer set \fIint\fR to number at start of \fIstr\fR
2077 (EXAMPLE: if \fIstr\fR is \fI20 Nov 89\fR,
2078 \fInum\fR would be set to 20.)???
2079 compflag string integer NOT WORTH IT? RETURNS -1 OR 0.?
2080 void integer integer Do not interpret; just put in \fIint\fR
2081 (EXAMPLE: \fI%(void(rclock{date}))\fR puts
2082 \fIrclock\fR value into \fIint\fR)
2083 void string string Do not interpret; just put in \fIstr\fR
2084 putstr string print \fIstr\fR
2085 putstrf string print \fIstr\fR in the specified width
2086 (e.g., %20(putstrf{subject})
2087 putnum integer print \fInum\fR
2088 putnumf integer print \fInum\fR in the specified width
2089 (e.g., %4(putnumf(msg))
2090 msg integer message number
2091 cur integer message is current
2092 size integer size of message
2093 strlen string integer length of \fIstr\fR
2094 me string the user's mailbox
2095 plus \fIL\fR integer add \fIL\fR to \fInum\fR
2096 minus \fIL\fR integer subtract \fIL\fR from \fInum\fR, then change si
2098 EXAMPLES: \fI%(void(minus))\fR, \fI%(void(minus 25))\fR
2099 width integer size (characters) of output buffer
2100 charleft integer space left in output buffer
2101 timenow integer seconds since the UNIX epoch
2104 .ta \w'formataddr 'u +\w'argument 'u +\w'returns 'u
2105 \fIescape\fR \fIargument\fR \fIreturns\fR \fIinterpretation\fR
2106 sec string integer seconds of the minute
2107 min string integer minutes of the day
2108 hour string integer hours of the day (24 hour clock)
2109 mday string integer day of the month
2110 mon string integer month of the year
2111 wday string integer day of the week (Sunday=0)
2112 year string integer year of the century
2113 yday string integer day of the year
2114 dst string integer daylight savings in effect
2115 zone string integer timezone
2116 sday string integer day of the week known
2117 1 for explicit in date
2118 0 for implicit (\fIMH\fR figured it out)
2119 \-1 for unknown (\fIMH\fR couldn't figure it out)
2120 clock string integer seconds since the UNIX epoch
2121 rclock string integer seconds prior to current time
2122 month string string month of the year
2123 lmonth string string month of the year (long form)
2124 tzone string string timezone
2125 day string string day of the week
2126 weekday string string day of the week (long)
2127 tws string string official 822 rendering of the date
2128 pretty string string a more user\-friendly rendering
2129 nodate string date wasn't parseable
2132 .ta \w'formataddr 'u +\w'argument 'u +\w'returns 'u
2133 \fIescape\fR \fIargument\fR \fIreturns\fR \fIinterpretation\fR
2134 pers string string the personal name of the address
2135 mbox string string the local part of the address
2136 host string string the domain part of the address
2137 path string string the route part of the address
2138 type string integer the type of host
2143 nohost string integer no host was present in the address
2144 ingrp string integer the address appeared inside a group
2145 gname string string name of the group (present for first
2147 note string string commentary text
2148 proper string string official 822 rendering of the address
2149 friendly string string a more user\-friendly rendering
2150 mymbox string the address refers to the user's mailbox
2151 formataddr string append \fIL\fR to \fIstr\fP as an address list
2152 (if \fIstr\fR wasn't empty, add comma and space before)
2153 putaddr \fIL\fR print stored address list;
2154 \fIL\fR is optional label;
2155 get line width from \fInum\fR
2156 EXAMPLE: \fI%(void(width))%(putaddr Cc: )\fR
2157 lit \fIL\fP string Put \fIL\fR into \fIstr\fR
2158 (if no \fIL\fR, empty \fIstr\fR)
2170 eq integer integer \fInum\fR == width
2171 ne integer integer \fInum\fR != width
2172 gt integer integer width > \fInum\fR
2176 plus integer add width to \fInum\fR
2177 minus integer subtract \fInum\fR from width
2180 formataddr string print \fIstr\fR in an address list
2184 the hours and minutes are printed in two digits (zero filled).
2187 %{subject}%<{body}<<%{body}%>