# cawf(1)

## NAME

         cawf, nroff - C version of  the  nroff-like,  Amazingly  Workable  (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 section).

              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 configuration file.  See the DEVICES section for  more
              information.

              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 constructing 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 conditionals; 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 beginning 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 terminators at ends of lines are
         understood to imply extra space afterward in filled lines.  Tabs are  im-
         plemented  crudely  and  not  exactly,  although  usually  they  work  as
         expected.  Hyphenation 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 section 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     .DS     .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  (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.  .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 borrowed 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 processing.)

## OUTPUT

         The default output format supported by cawf, 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  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   device
         configuration  files.   The  device file typically defines characters and
         constant output parameters.  The output device 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
         configuration 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 specification is permitted
         with the ANSI device.

         When the NONE device is selected, cawf uses no special  output  codes  to
         represent  the type faces.  No -ffont specification 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 organization  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 contains an entry for
         the named font.  The DEVICE  CONFIGURATION  FILE  section  describes  how
         fonts are defined in device configuration 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 - comments 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 device, 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=x1b&l0Ox1b(8Ux1b(s0p12h10v0s0b3T
                      f=c12ibm=x1b&l0Ox1b(10Ux1b(s0p10.00h12.0v0s0b3T
                      f=lg12=x1b&l0Ox1b(8Ux1b(s12h12v0s0b6T

         The distribution device.cf file defines the following devices 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  directory  -
         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 device,  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 config, -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).