

AWF(1)                     Unix Programmer's Manual                     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 nroff's style with the -man or -ms macro packages.  The
     -macro option is mandatory and must be `-man' or `-ms'.

     Awf implements the following raw nroff 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 nroff/troff special characters in the  original  V7
     troff manual.

     Many restrictions are present; the behavior in general  is  a  subset  of
     nroff's.  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  com-
       parisons  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  im-
     plemented  crudely  and  not quite correctly, although in most cases they
     work as expected.  Hyphenation is done  only  at  explicit  hyphens,  em-
     dashes, and nroff 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


U of Toronto                          13 July 1990                           1




AWF(1)                     Unix Programmer's Manual                     AWF(1)


     .BY and .NB each take a single string argument  (respectively,  an  indi-
     cation  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 nroff 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 nroff 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(7), ms(7)







U of Toronto                          13 July 1990                           2




AWF(1)                     Unix Programmer's Manual                     AWF(1)


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.










































U of Toronto                          13 July 1990                           3


