NAME

     cawf, nroff - C version of the nroff-like,  Amazingly  Work-
     able (text) Formatter


SYNOPSIS

     cawf [-cconfig]  [-ddevice]  [-e]  [-ffont]  [-h]  [-macros]
     [file ...]


DESCRIPTION

     Cawf formats the text from the input file(s) (standard input
     if  none) in an approximation of nroff.  It comes closest to
     duplicating nroff's man or ms macro package styles.  It  has
     some limited support for nroff's me macros.


OPTIONS

     Options must precede file names.

     -cconfig
          defines an alternate path to the  device  configuration
          file.   Normally the device configuration file is found
          in device.cf in the cawf library (see  the  FILES  sec-
          tion).

          The device configuration file contains device character
          strings for selecting fonts and the bold or italic type
          faces.  See the DEVICES section for more information.

     -ddevice
          specifies the name of the  output  device.   There  are
          three  built-in  devices  - ANSI, NONE and NORMAL - and
          other devices may be defined in the  device  configura-
          tion  file.   See the DEVICES section for more informa-
          tion.

          The NORMAL device is the default.

     -e   directs cawf to issue an eject (FF  or  ^L)  after  the
          last page.

     -ffont
          specifies the one font for the  device,  declared  with
          the  -ddevice option, that is to be used for the entire
          document.  Font must match a font associated  with  the
          device's  stanza in the device configuration file.  See
          the DEVICES section for more information.

          No font may be specified for the built-in devices ANSI,
          NONE or NORMAL.

     -h   requests a help display.

     -macro
          specifies the macro file to be used.  The standard cawf
          distribution  supplies macro files to support ``-man'',
          ``-me'' or ``-ms''.  Cawf finds a macro  file  by  con-
          structing  its  name  from  `m', acro and .mac - e. g.,
          -man is converted to man.mac.   The  default  directory
          for  macro files is defined when cawf is compiled; it's
          C:\SYS\LIB\CAWF    in    the    MS-DOS     environment;
          /usr/lib/cawf in the UNIX environment.

     file ...
          are the names of files containing nroff source text.


NROFF COMPATIBILITY

     Cawf accepts the following raw nroff requests:

          .\"  .ad  .bp  .br  .ce  .de  .di  .ds
          .el  .fi  .fl  .ft  .i0  .ie  .if  .in
          .it  .lg  .li  .ll  .ls  .na  .ne  .nf
          .nr  .ns  .pl  .po  .ps  .rm  .rn  .rr
          .rs  .so  .sp  .ta  .ti  .tm  .tr

     and the following in-text codes:

          \$   \%   \*   \"   \c   \f   \h   \k
          \n   \s   \w

     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 The fully supported nroff request control character is the
       period.   There  is  limited  support  for the  non-break,
       acute accent control character.

     o Point sizes do not exist; .ps is ignored.

     o Special vertical spacing - the .vs request included  -  is
       ignored.

     o Conditionals cover only the numeric comparisons >,  =,  <,
       >=  and  <=  on  \n(.$; string comparisons between a macro
       parameter and a literal; n (always true);  and  t  (always
       false).   Only  single  line input is accepted from condi-
       tionals; multi-line input - e.g., \(anything\)  -  is  not
       supported.

     o The handling of strings is generally primitive.

     o Horizontal motion via \h must be supplied  with  a  number
       register  interpolation  and  must  be  positive  - e. g.,
       \w\n(NN, where the value in NN is >= 0.

     o The \k function is reliable only after TAB characters,  so
       it is useful only for measuring table positions.

     o The .di request only turns output on and off -  any  macro
       name is ignored.

     o Expressions - e. g., .sp - are reasonably general, but the
       |,  &,  and  : operators do not exist, there must be white
       space between the end of the nroff function and the begin-
       ning  of the expression, and \w requires that quote (') be
       used as the delimiters.  \w counts the  characters  inside
       the  quotes  and  scales  the  result in ens, so that, for
       example, \w'\(bu' equals 4n, and \w'\(bu'/1n equals 4.

     o The only acceptable count for the .it request is one,  and
       it is effective only with man, me or ms macros.

     o The default scaling factor is `v' for the  .ne,  .sp,  and
       .pl  raw  nroff  requests;  it is `u' for .nr; and `n' for
       .in, .ll, .ls, .po, .ta and  .ti.   (A  different  scaling
       factor may be specified with a trailing character.)

     o Some obsolete or meaningless requests - .i0, .lg and .li -
       are silently ignored.

     White space at the beginning of lines,  and  embedded  white
     space  within lines is dealt with properly.  Sentence termi-
     nators at ends of lines are understood to imply extra  space
     afterward in filled lines.  Tabs are implemented crudely and
     not exactly, although usually they work as expected.  Hyphe-
     nation  is  done  only  at  explicit hyphens, em-dashes, and
     nroff discretionary hyphens.  By  default  bold  and  italic
     characters  are  emulated with backspacing and overprinting,
     but the -d and -f options, combined with the contents of the
     device  configuration  file, may be used to generate special
     codes for bold and italic characters.  (See the DEVICES sec-
     tion for more information.)


MAN MACROS

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

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

     .BY and .NB each take  a  single  string  argument  (respec-
     tively,  an  indication  of  authorship and a note about the
     status of the manual page) and arrange to place  it  in  the
     page footer.  .AT and .IX do nothing.


ME MACROS

     The me macro subset has been derived from the cawf ms macros
     by Chet Creider <creider@csd.uwo.ca>.  It includes:

          .(l  .(q  .)l  .)q  .b   .bu  .i   .ip
          .lp  .np  .pp  .r   .sh  .sm  .u   .uh

     The .(l C and .(l L options are supported.  In addition, the
     .AB,  .AE,  .AI, .AU, .DA, .ND, .TL and .UX macros have been
     retained from the ms set, and the .XP macro  has  been  bor-
     rowed from the Berkeley additions to the ms macro set.


MS MACROS

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

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

     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.

     The DY string variable is available.  The  PD,  PI,  and  LL
     number registers exist and can be changed.


HEADERS AND FOOTERS

     Cawf allows the placement of text into the five line  header
     and  footer  sections  from  the  LH, CH, RF, LF, CF, and RF
     string variables, via the control of the .^b request:

     .^b fh 1   enables header string placement on the first page
     .^b fh 0   disables header string placement on the first page
     .^b HF 1   enables header/footer string placement
     .^b HF 0   disables header/footer string placement

     There are appropriate .^b requests in the distribution  man,
     me  and  ms  macro  files.   (The  me and ms macro files use
     another .^b request, .^b NH, to enable numbered header  pro-
     cessing.)


OUTPUT

     The default output format supported by cawf, in its  distri-
     buted  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 approxi-
     mation (it's sometimes extremely  vague)  to  their  correct
     appearance.

     One part of cawf's knowledge of the output  device,  related
     to  the  formation of characters, is established by a device
     file, which is read before the user's input.  The search for
     it  begins  in  cawf's  library  directory,  under  the name
     term.dev (where term is the value of  the  TERM  environment
     variable).    Failing   to  find  that,  cawf  searches  for
     dumb.dev.  (See the FILES section for a description  of  the
     path  to  cawf's  library  directory.)  The device file uses
     special internal requests  to  set  up  resolution,  special
     characters  and  more  normal nroff functions to set up page
     length, etc.

     Cawf has limited support for fonts special forms of bold and
     italic  characters.   It  is provided through the -c config,
     -ddevice and -ffont options.  See the  DEVICES  section  for
     more information.

     Note the distinction between the device and the output  dev-
     ice  configuration files.  The device file typically defines
     characters and constant output parameters.  The output  dev-
     ice configuration file defines font and type face codes.  It
     is usually not necessary to define a  separate  device  file
     for  each device represented in the output device configura-
     tion file - the dumb.dev device file will suffice for almost
     all representations.


DEVICES

     Cawf supports primitive output device configuration for font
     and  type  face  control.   One font may be selected for the
     entire document by directing cawf to issue a font  selection
     control  character  string at the beginning of the document,
     and control character strings may be selected for  switching
     between the bold, italic and Roman type faces.

     The -c config, -ddevice and -ffont options direct  the  font
     and type face selections.

     The -ddevice option specifies the name of the device.   Cawf
     has  three  built-in  devices - ANSI, NONE and NORMAL.  When
     the ANSI device is selected, cawf  issues  the  ANSI  shadow
     mode  control  codes,  ``ESC  [ 7 m'', to represent the bold
     face; the ANSI underscore control codes, ``ESC [ 4  m'',  to
     represent the italic face; and the ANSI control codes, ``ESC
     [ 0 m'', to represent the ROMAN face.  No -ffont  specifica-
     tion is permitted with the ANSI device.

     When the NONE device is selected, cawf uses no special  out-
     put codes to represent the type faces.  No -ffont specifica-
     tion is permitted with the ANSI device.

     The  NORMAL  output  device  is  the  default.   When   it's
     selected,  cawf  overprints  each  bold character two times,
     using three issuances of each bold character,  separated  by
     backspace  characters; it issues an underscore and backspace
     before each italic character.  No  -ffont  specification  is
     permitted with the ANSI device.  The bsfilt(1) filter may be
     used to further process the backspace  codes  output  for  a
     NORMAL device.

     All other devices named  in  the  -ddevice  option  must  be
     represented  by  a  stanza in the device configuration file.
     The  device  configuration  file  is  usually  contained  in
     device.cf in cawf's library directory (see the FILES section
     for more information).  An  alternate  device  configuration
     file path may be specified with the -cconfig option.

     The DEVICE CONFIGURATION FILE section describes the  organi-
     zation  of the device configuration file.  It is easy to add
     devices to the device.cf supplied in the cawf distribution.

     The -ffont option may be used with the -ddevice option, when
     the appropriate stanza in the device configuration file con-
     tains an entry for the named font.  The DEVICE CONFIGURATION
     FILE  section describes how fonts are defined in device con-
     figuration file stanzas.


DEVICE CONFIGURATION FILE

     The device configuration file defines the special  character
     codes necessary to direct output devices to select fonts and
     to produce bold, italic and Roman type faces.

     The configuration file is  usually  found  in  device.cf  in
     cawf's  library  directory  (see  the FILES section for more
     information).  It is organized into two main  parts  -  com-
     ments and device stanzas.  Comments are any lines that begin
     with the pound sign (`#') character.  They are informational
     only  and cawf ignores them.  Cawf also ignores empty lines,
     so they may be used as vertical white space.

     Stanzas name devices and define their  font  and  type  face
     control  strings.  A stanza begins with the name of the dev-
     ice, starting at the beginning of a line and  occupying  the
     entire  line.   The  body  of the stanza, defining fonts and
     type faces, is formed of lines beginning with white space (a
     TAB  or  space  characters)  that directly follow the device
     name.

     Individual lines of the stanza body contain a key character,
     followed  by  a  equal sign, followed by the font name (if a
     font key) and the output device control codes.  Cawf  issues
     the  font control codes once, at the beginning of output, so
     only one font may be selected.  The type face control  codes
     are issued at each change of type face.

     The key characters are:

          b          for bold
          f          for font definition
          i          for italic
          r          for Roman

     The `b', `i' and `r' key codes are followed by an equal sign
     (`=')  and  their control code definition.  The `f' key code
     is followed by an equal sign (`='), the font  name,  another
     equal sign and the font control code definition.

     Control code definitions may  contain  any  printable  ASCII
     characters.   Non-printable  characters  may  be  encoded in
     octal notation with the `\nnn' form or in  hexadecimal  with
     the   `\xnn'   form.   The  special  code,  `\E'  (or  `\e')
     represents the ESC control character (\033 or \x1b).

     Here's a sample showing the definition for the  HP  LaserJet
     III.   The  stanza  name  is ``lj3''.  All its non-printable
     characters are ESCs; the first is coded in octal  form;  the
     second  with  '\E';  the  rest, in hexadecimal form.  TAB is
     used as the leading white space  character  for  the  stanza
     body lines.

          # HP LaserJet III

          lj3
                  b=\033(s7B
                  i=\E(s1S
                  r=\x1b(s0B\x1b(s0S
                  f=c10=&l0O(8U(s0p12h10v0s0b3T
                  f=c12ibm=&l0O(10U(s0p10.00h12.0v0s0b3T
                  f=lg12=&l0O(8U(s12h12v0s0b6T

     The distribution device.cf file defines the  following  dev-
     ices and fonts.

     epson     dot matrix printer in Epson FX-86e/FX-800 mode
               Bold:     Double-strike
               Fonts:    none

     ibmppds   IBM Personal Printer Data Stream (PPDS) protocol
               Bold:     Double-strike
               Italic:   Underline
               Fonts:    none




     kxp1124   Panasonic KX-P1124 dot matrix printer in PGM mode
               Bold:     Emphasized
               Fonts:    c10        10 Characters Per Inch (CPI) Courier
                         c12        12 CPI Courier
                         bps10      10 CPI Bold PS
                         bps12      12 CPI Bold PS
                         p10        10 CPI Prestige
                         p12        12 CPI Prestige
                         s10        10 CPI Script
                         s12        12 CPI Script
                         ss10       10 CPI Sans Serif
                         ss12       12 CPI Sans Serif

     kxp1180   Panasonic KX-P1180 dot matrix printer in PGM mode
               Bold:     Emphasized
               Fonts:    c10        10 Characters Per Inch (CPI) Courier
                         c12        12 CPI Courier
                         bps10      10 CPI Bold PS
                         bps12      12 CPI Bold PS
                         p10        10 CPI Prestige
                         p12        12 CPI Prestige
                         ss10       10 CPI Sans Serif
                         ss12       12 CPI Sans Serif

     lj3       HP LaserJet III
               Fonts:    c10        10 point, 12 Characters Per Inch (CPI)
                                    Courier
                         c12ibm     12 point, 10 CPI Courier, IBM-PC
                                    Symbol Set
                         lg12       12 point, 12 CPI Letter Gothic

     vgamono   VGA monochrome monitor for MS-DOS
               (ANSI.SYS driver required for MS-DOS)
               Italic:   Reverse-video
               Fonts:    none


FILES

     Cawf resource files are located in the cawf  library  direc-
     tory  -  C:\SYS\LIB\CAWF, the MS-DOS environment default; or
     /usr/lib/cawf, the UNIX environment default.  These defaults
     can  be  overridden  by the CAWFLIB environment variable, or
     changed in the cawflib.h header file.

     common      common device-independent initialization
     device.cf   output device configurations
     *.dev       device-specific initialization
     m*.mac      macro package files


DIAGNOSTICS

     Unlike  nroff,  cawf  complains  whenever  it  sees  unknown
     requests.   All  diagnostics  appear  on  the standard error
     file.


HISTORY

     Vic Abell of Purdue University  <abe@cc.purdue.edu>  derived
     cawf  from awf, ``the Amazingly Workable (text) Formatter,''
     written by Henry Spencer of the University of Toronto.   The
     Toronto  work  was  a supplement to the C News project.  The
     Purdue effort was aimed at producing a  C  language  version
     that  would  run on small systems, particularly MS-DOS ones.
     The adaptation of the me macros was  done  by  Chet  Creider
     <creider@csd.uwo.ca>.   Chet also contributed ideas for dev-
     ice, font and type face support.

     The MS-DOS version of cawf has been  compiled  with  version
     2.5  of  Microsoft's  Quick-C  compiler.   It runs under the
     Mortis  Kern  Systems   Toolkit   KornShell,   ksh(1),   and
     COMMAND.COM.


BUGS

     Nroff and troff mavens will have many complaints.  Some  may
     even represent bugs and not deliberate omissions.

     Watch out for scaling factors - especially on requests  like
     \w.

     The overprinting required  to  create  bold  and  italicized
     characters  is  tiresome  on  a slow printer.  The bsfilt(1)
     post-filter from this distribution may be used to  alleviate
     that  nuisance by managing the backspacing codes from cawf's
     NORMAL device output.

     The printing of bold  and  italic  characters  is  sometimes
     better handled by special printer codes.  Use cawf's -c con-
     fig, -ddevice and -ffont options to produce special font and
     device output control codes.

     Cawf has a small amount of built-in code for the man, me and
     ms macro packages, but none for any others.

     The stacking for the .so request is limited.


SEE ALSO

     bsfilt(1), colcrt(1), man(7), me(7), ms(7) and nroff(1).