awf

     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:

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

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

          + The implementation of strings is generally primitive.

          + 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 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

          .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
          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/skunk/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)

     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.