home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / fileutil / cawf / cawf.man < prev    next >
Encoding:
Text File  |  1991-02-21  |  8.2 KB  |  265 lines
  1.  
  2.  
  3. CAWF(1)                    Unix Programmer's Manual                    CAWF(1)
  4.  
  5.  
  6. NAME
  7.      cawf - C version of the nroff-like, Amazingly Workable (text) Formatter
  8.  
  9. SYNOPSIS
  10.      cawf [ -macros ] [ file ... ]
  11.  
  12. DESCRIPTION
  13.      Cawf formats the text from the input file(s) (standard input if none)  in
  14.      an  approximation  of nroff.  It comes closest to duplicating nroff's man
  15.      or ms macro package styles.  The -macro argument is optional, and it must
  16.      be  first.   (The  standard  cawf  distribution  supplies  macro files to
  17.      support `-man' or `-ms'.)
  18.  
  19.      Cawf accepts the following raw nroff requests:
  20.  
  21.           .\"  .ad  .bp  .br  .ce  .de  .ds  .el  .fi
  22.           .ft  .i0  .ie  .if  .in  .it  .lg  .li  .ll
  23.           .ls  .na  .ne  .nf  .nr  .ns  .pl  .po  .ps
  24.           .rm  .rr  .rs  .so  .sp  .ta  .ti  .tm
  25.  
  26.      and the following in-text codes:
  27.  
  28.           \$   \%   \*   \c   \f   \h   \n   \s
  29.  
  30.      plus the full list of nroff/troff special characters in the  original  V7
  31.      troff manual.
  32.  
  33.      Many restrictions are present; the behavior in general  is  a  subset  of
  34.      nroff's.  Of particular note are the following:
  35.  
  36.      o Point sizes do not exist; .ps is ignored.
  37.  
  38.      o Special vertical spacing - the .vs command included - is ignored.
  39.  
  40.      o Conditionals cover only numeric comparisons on  \n(.$,  string  compar-
  41.        isons  between a macro parameter and a literal, and n (always true) and
  42.        t (always false).
  43.  
  44.      o The handling of strings is generally primitive.
  45.  
  46.      o Horizontal motion via \h  must  be  supplied  with  a  number  register
  47.        interpolation and must be positive - e. g., \w\n(NN, where the value in
  48.        NN is >= 0.
  49.  
  50.      o Expressions - e. g., .sp - are reasonably general, but the |, &, and  :
  51.        operators  do  not  exist, there must be white space between the end of
  52.        the nroff command and the beginning of the expression, and \w  requires
  53.        that  quote  (')  be  used as the delimiters.  \w counts the characters
  54.        inside the quotes and scales the result in ens, so that,  for  example,
  55.        \w'\(bu' equals 4n, and \w'\(bu'/1n equals 4.
  56.  
  57.      o The only acceptable count for  the  .it  command  is  one,  and  it  is
  58.        effective only with man or ms macros.
  59.  
  60.  
  61.  
  62.  
  63.  
  64. Purdue University                       February, 1991                       1
  65.  
  66.  
  67.  
  68.  
  69. CAWF(1)                    Unix Programmer's Manual                    CAWF(1)
  70.  
  71.  
  72.      o The default scaling factor is `v' for the .ne, .sp, and .pl  raw  nroff
  73.        requests;  it  is  `u' for .nr; and `n' for .in, .ll, .ls, .po, .ta and
  74.        .ti.  (A different scaling factor may  be  specified  with  a  trailing
  75.        character.)
  76.  
  77.      o Some obsolete or meaningless commands - .i0, .lg and .li - are silently
  78.        ignored.
  79.  
  80.      White space at the beginning of lines, and embedded  white  space  within
  81.      lines  is dealt with properly.  Sentence terminators at ends of lines are
  82.      understood to imply extra space afterward in filled lines.  Tabs are  im-
  83.      plemented  crudely  and  not  exactly,  although  usually  they  work  as
  84.      expected.  Hyphenation is done only at explicit hyphens,  em-dashes,  and
  85.      nroff  discretionary  hyphens.   Bolding  and italicization are done with
  86.      backspacing and overprinting.
  87.  
  88. MAN MACROS
  89.      The man macro set replicates the full V7 manual macros, plus a few  semi-
  90.      random oddballs.  The full list is:
  91.  
  92.           .AT  .B   .BI  .BR  .BY  .DE  .DS  .DT  .HP  .I
  93.           .IB  .IP  .IR  .IX  .LP  .NB  .P   .PD  .PP  .RB
  94.           .RE  .RI  .RS  .SH  .SM  .TH  .TP  .UC
  95.  
  96.      .BY and .NB each take a single string argument  (respectively,  an  indi-
  97.      cation  of authorship and a note about the status of the manual page) and
  98.      arrange to place it in the page footer.  .AT and .IX do nothing.
  99.  
  100. MS MACROS
  101.      The ms macro set is a substantial subset of  the  V7  manuscript  macros.
  102.      The macros are:
  103.  
  104.           .AB  .AE  .AI  .AU  .B   .CD  .DA  .DE  .DS  .I
  105.           .ID  .IP  .LD  .LG  .LP  .ND  .NH  .NL  .PP  .QE
  106.           .QP  .QS  .R   .RE  .RP  .RS  .SH  .SM  .TL  .TP
  107.           .UL  .UX
  108.  
  109.      Size changes are recognized but ignored, as are .RP and  .ND.   .UL  just
  110.      prints  its  argument in italics.  .DS/.DE does not do a keep, nor do any
  111.      of the other macros that normally imply keeps.
  112.  
  113.      The DY string variable is available.  The PD, PI, and LL number registers
  114.      exist and can be changed.
  115.  
  116. HEADERS AND FOOTERS
  117.      Cawf can do limited header and footer processing from the LH, CH, RF, LF,
  118.      CF, and RF string variables, via the control of the .^b command:
  119.  
  120.      .^b fh 1   enables a header on the first page
  121.      .^b fh 0   disables the header on the first page
  122.      .^b HF 1   enables header/footer processing
  123.      .^b HF 0   enables header/footer processing
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130. Purdue University                       February, 1991                       2
  131.  
  132.  
  133.  
  134.  
  135. CAWF(1)                    Unix Programmer's Manual                    CAWF(1)
  136.  
  137.  
  138.      There are appropriate .^b commands in the distribution man and  ms  macro
  139.      files.   (The  ms  macro file uses another .^b command, .^b NH, to enable
  140.      numbered header processing.)
  141.  
  142. OUTPUT
  143.      The only output format supported by cawf, in  its  distributed  form,  is
  144.      that  appropriate to a dumb terminal, using overprinting for italics (via
  145.      underlining) and bold.  The nroff special characters are printed as  some
  146.      vague  approximation  (it's  sometimes  extremely vague) to their correct
  147.      appearance.
  148.  
  149.      Cawf's knowledge of the output device is established by  a  device  file,
  150.      which  is  read  before  the  user's  input.  The search for it begins in
  151.      cawf's library directory, under the name  term.dev  (where  term  is  the
  152.      value  of  the  TERM  environment  variable).  Failing to find that, cawf
  153.      searches for dumb.dev.  The device file uses special internal commands to
  154.      set up resolution, special characters, fonts, etc., and more normal nroff
  155.      commands to set up page length, etc.
  156.  
  157. FILES
  158.      All files are located in c:/sys/lib/cawf (the author's MS-DOS environment
  159.      default).   This  default  can  be  overridden by the CAWFLIB environment
  160.      variable, or changed in the source code.
  161.  
  162.      common   common device-independent initialization
  163.      *.dev    device-specific initialization
  164.      m*.mac   macro package files
  165.  
  166. SEE ALSO
  167.      bsfilt(1), colcrt(1), nroff(1), man(7), and ms(7).
  168.  
  169. DIAGNOSTICS
  170.      Unlike nroff, cawf  complains  whenever  it  sees  unknown  commands  and
  171.      macros.   All  diagnostics  (these  and some internal ones) appear on the
  172.      standard error file.
  173.  
  174. HISTORY
  175.      Vic Abell of Purdue University <abe@mace.cc.purdue.edu> derived cawf from
  176.      awf,  ``the  Amazingly  Workable  (text)  Formatter'' that was written by
  177.      Henry Spencer of the University of  Toronto.   The  Toronto  work  was  a
  178.      supplement  to  the  C  News  project.   The  Purdue  effort was aimed at
  179.      producing  a  C  language  version  that  would  run  on  small  systems,
  180.      particularly MS-DOS ones.
  181.  
  182.      The MS-DOS version of cawf has been  compiled  with  Microsoft's  Quick-C
  183.      compiler.   It  runs  under  the  Mortis  Kern Systems Toolkit KornShell,
  184.      ksh(1), and COMMAND.COM.
  185.  
  186. BUGS
  187.      Nroff and  troff  mavens  will  have  many  complaints.   Some  may  even
  188.      represent bugs and not deliberate omissions.
  189.  
  190.      Watch out for scaling factors - especially on commands like \w.
  191.  
  192.  
  193.  
  194.  
  195.  
  196. Purdue University                       February, 1991                       3
  197.  
  198.  
  199.  
  200.  
  201. CAWF(1)                    Unix Programmer's Manual                    CAWF(1)
  202.  
  203.  
  204.      The overprinting required to create bold  and  italicized  characters  is
  205.      tiresome  on  a  slow  printer.   Use bsfilt(1) from this distribution to
  206.      remove all the backspacing from cawf's output.
  207.  
  208.      Cawf has a small amount of  built-in  code  for  the  man  and  ms  macro
  209.      packages, but none for any others.
  210.  
  211.      The stacking for the .so command is limited.
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262. Purdue University                       February, 1991                       4
  263.  
  264.  
  265.