awf(1)

NAME
     awf - amazingly workable (text) formatter

SYNOPSIS
     awf -macros [ file ] ...

DESCRIPTION
     Awf formats the text from the input file(s) (standard input if none) in
     an imitation of The -macro option is mandatory and must be `-man' or
     `-ms'.

     Awf implements the following raw  requests:

          .\"  .ce  .fi  .in  .ne  .pl  .sp
          .ad  .de  .ft  .it  .nf  .po  .ta
          .bp  .ds  .ie  .ll  .nr  .ps  .ti
          .br  .el  .if  .na  .ns  .rs  .tm

     and the following in-text codes:

     \$   \%   \*   \c   \f   \n   \s

     plus the full list of /troff special characters in the original V7 troff
     manual.

     Many restrictions are present; the behavior in general is a subset of Of
     particular note are the following:

     o Point sizes do not exist; .ps and \s are ignored.

     o Conditionals implement only numeric comparisons on \n(.$, string
       comparisons between a macro parameter and a literal, and n (always
       true) and t (always false).

     o The implementation of strings is generally primitive.

     o Expressions in (e.g.) .sp are fairly general, but the |, &, and :
       operators do not exist, and the implementation of \w requires that
       quote (') be used as the delimiter and simply counts the characters
       inside (so that, e.g., \w'\(bu' equals 4).

     White space at the beginning of lines, and imbedded white space within
     lines, is dealt with properly.  Sentence terminators at ends of lines are
     understood to imply extra space afterward in filled lines.  Tabs are
     implemented crudely and not quite correctly, although in most cases they
     work as expected.  Hyphenation is done only at explicit hyphens, em-
     dashes, and discretionary hyphens.

MAN MACROS
     The -man macro set implements the full V7 manual macros, plus a few
     semi-random oddballs.  The full list is:

     .B   .DT  .IP  .P   .RE  .SM
     .BI  .HP  .IR  .PD  .RI  .TH
     .BR  .I   .LP  .PP  .RS  .TP
     .BY  .IB  .NB  .RB  .SH  .UC

     .BY and .NB each take a single string argument (respectively, an
     indication of authorship and a note about the status of the manual page)
     and arrange to place it in the page footer.

MS MACROS
     The -ms macro set is a substantial subset of the V7 manuscript macros.
     The implemented macros are:

     .AB  .CD  .ID  .ND  .QP  .RS  .UL
     .AE  .DA  .IP  .NH  .QS  .SH  .UX
     .AI  .DE  .LD  .NL  .R   .SM
     .AU  .DS  .LG  .PP  .RE  .TL
     .B   .I   .LP  .QE  .RP  .TP

     Size changes are recognized but ignored, as are .RP and .ND.  .UL just
     prints its argument in italics.  .DS/.DE does not do a keep, nor do any
     of the other macros that normally imply keeps.

     Assignments to the header/footer string variables are recognized and
     implemented, but there is otherwise no control over header/footer
     formatting.  The DY string variable is available.  The PD, PI, and LL
     number registers exist and can be changed.

OUTPUT
     The only output format supported by awf, in its distributed form, is that
     appropriate to a dumb terminal, using overprinting for italics (via
     underlining) and bold.  The  special characters are printed as some vague
     approximation (it's sometimes very vague) to their correct appearance.

     Awf's knowledge of the output device is established by a device file,
     which is read before the user's input.  It is sought in awf's library
     directory, first as dev.term (where term is the value of the TERM
     environment variable) and, failing that, as dev.dumb.  The device file
     uses special internal commands to set up resolution, special characters,
     fonts, etc., and more normal  commands to set up page length etc.

FILES
     All in /usr/lib/awf (this can be overridden by the AWFLIB environment
     variable):

     common     common device-independent initialization
     dev.*      device-specific initialization
     mac.m*     macro packages
     pass1      macro substituter
     pass2.base central formatter
     pass2.m*   macro-package-specific bits of formatter
     pass3      line and page composer
SEE ALSO
     awk(1), nroff(1), man(5), ms(5).

DIAGNOSTICS
     Unlike nroff, awf complains whenever it sees unknown commands and macros.
     All diagnostics (these and some internal ones) appear on standard error
     at the end of the run.

HISTORY
     Written at University of Toronto by Henry Spencer, more or less as a
     supplement to the C News project.

     => None of the above really want to admit it.  <=

BUGS
     There are plenty, but what do you expect for a text formatter written
     entirely in (old) awk?

     The -ms stuff has not been checked out very thoroughly.