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