home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_100 / 145_01 / roff4.doc < prev    next >
Text File  |  1979-12-31  |  35KB  |  1,068 lines
  1. March 10, 1984
  2.             ROFF4, V1.60
  3.  
  4.            by Ernest E. Bergmann
  5.            Physics, Building #16
  6.              Lehigh University
  7.             Bethlehem, PA 18015
  8.  
  9.  
  10.     ROFF4 is an expanded version of ROFF, based on the
  11. formatter in Kernighan and Plauger's book SOFTWARE TOOLS, is
  12. written in BDS C, and employs the directed i/o functions
  13. that go along with that package.  Well, half of the directed
  14. I/O anyway - it doesn't use redirected input because more
  15. than one file can be used as input for a run.  So that some
  16. of the input files may be used to "set-up" the formatter for
  17. a particular style and for particular hardware.  It is
  18. possible to substitute keyboard input instead of files for
  19. educational and test purposes.
  20.  
  21.     ROFF was provided by Neal Somos for the public
  22. domain via the BDS 'C' Users' Group's volume, CUG -- "Just
  23. Like Mom's".  Some of this documentation started there as
  24. well.
  25.  
  26.     This formatter contains features important for the
  27. preparation of technical manuscripts.  Special symbols or
  28. fonts that can be defined by or for the user can be produced
  29. (if the hardware is capable!).  Super and subscripts can be
  30. handled as well as backspace even for printers without
  31. reverse scrolling or backspacing hardware capabilities.
  32. However, the output device should recognize separately the
  33. <CR> and <LF> functions.  The Epson MX-80 with GRAFTRAX 80
  34. was used by the author for most of the development, however
  35. he also was able to use the video display of the Exidy
  36. Sorcerer, which has user definable graphics.  "Preprocessor"
  37. directives can be used to merge stock phrases, boiler plate,
  38. make macro definitions, automate numbering, and create
  39. diversions (for footnotes, table of contents, etc.)
  40.  
  41.     To support the capabilities of WORDSTAR[tm by
  42. MicroPro] extended underlining, strikeout, and multiple
  43. strike capability are provided as well.
  44.  
  45.     For more details on the directed I/O see the files,
  46. NDIO.C and DIO.H that are included here for completeness, but
  47. came from CUG--"Just Like Mom's".
  48.  
  49.  
  50. Sample calls:(recommended to use console, files (">") and
  51.         list (")") only; printer and robot-typewriter
  52.         are not implemented for my system)
  53.  
  54. A>roff4 filename1 filename2 filename3 +}
  55.  
  56.     this would send the formatted version of these three
  57.     files to the console and to the printer
  58.  
  59.  
  60. A>roff4 filename1 +}]>filename1
  61.  
  62.     this would format filename1 and send it to the printer,
  63.     console, robot-typewriter, and back to filename1.
  64.  
  65. A>roff4 -s -f filename1 -b filename2 -f -m -r -d -i -g -*
  66.  
  67.     The option, -s, causes the formatter to stop (pause)
  68.     at the start of each page of output; the bell at the
  69.     console is sounded (if it exists!) and the program
  70.     waits until any key is pressed at the console.  It
  71.     is essential for printers that are feed single sheets
  72.     at a time!
  73.  
  74.     An option that was not shown above, -o[page or range],
  75.     is used to selectively generate output of ONLY certain
  76.     pages.  It is useful to retype pages that got "eaten"
  77.     by the printer (Henry Harpending's aptly put language).
  78.     To retype only page 23, say, make the option: -o23
  79.     To retype pages 23 through 29 use: -o23-29
  80.     To retype pages 23 to the end use: -23-
  81.     These options changes the values of the internal
  82.     variables, FIRSTPAGE and LASTPAGE which originally
  83.     have the values of 1 and 30000, respectively.  Normally
  84.     this option would be placed early enough in the
  85.     command line that no pages have been printed yet.
  86.  
  87.     The option, -f, would introduce a formfeed (0CH)
  88.     into the output stream (useful for placing blank
  89.     pages, or aligning printer pages) where it appears;
  90.     in this example, before the first page of output,
  91.     and, again, at the very end of the output.
  92.  
  93.     The option, -b,  turns on the "debug" flag so as to
  94.     print out lots of diagnostics to the STDERR[console].
  95.     Probably only useful for those who are trying to
  96.     trace the operation of the formatter for elusive
  97.     "bugs".
  98.  
  99.     The option, -m, causes a list of macro definitions
  100.     to be typed to the console.  It is a useful tool for
  101.     debugging complex macro packages where the 
  102.     preprocessor's expansions are too subtle for humans.
  103.  
  104.     The option, -d, causes a list of diversion files to
  105.     be typed to the console.  Its main virtue is to
  106.     remind the user what files are being generated and
  107.     their approximate size.
  108.  
  109.     The option, -i, causes a list of string insertions
  110.     to be typed to the console.  Useful for macro writers,
  111.     as was the -m, described above.  Also, for noting
  112.     what are the settings of "standard substitutions",
  113.     such as "today's date".
  114.  
  115.     The option, -r, causes a list of number registers to
  116.     be typed to the console.  Could be useful to find
  117.     the number of footnotes, etc.
  118.  
  119.     The option, -g, causes a glossary of defined
  120.     translated characters to be printed on the output
  121.     device.  It is useful to check the appearance of
  122.     all special definable characters and to produce
  123.     a "wall chart" of special characters available.
  124.  
  125.     The default option, -*, (the * could be any
  126.     unassigned option) means keyboard input (buffered
  127.     line-by-line with a prompt with the character used in
  128.     the option, here *).  Typing a control-Z indicates
  129.     an end-of-file; the formatter will continue with the
  130.     next named file.  It is intended as a learning aid
  131.     since one can tryout "tricky" input such as
  132.     equations.  As with standard CP/M, a control-P can
  133.     be used to toggle the printer to display output
  134.     that would normally be sent to the console; also,
  135.     one can edit the keyboard input with the backspace
  136.     key.
  137.  
  138.     Using ROFF4, you can make nice printouts of a file,
  139. with as little or as much help from the program as you want,
  140. depending on the commands.  There are default values for all
  141. parameters, so if you don't put any commands in at all, your
  142. file will come out with filled, right-justified lines.  The
  143. default line-length is 60 characters; the default page-
  144. length is 66 lines per page.  "Filled lines" means that as
  145. many input words as possible are packed onto a line before
  146. it is printed; "non-filled" lines go through the formatter
  147. w/o rearrangement.  "Right-justified" simply means that
  148. spaces are added between words to make all the right margins
  149. line up nicely.  To set a parameter, use the appropriate
  150. commands below. All commands have the form of a period
  151. followed by two letters. A command line should have nothing
  152. on it but the command and its arguments (if any); any text
  153. would be lost. 
  154.  
  155.     Extra space will separate text sentences.  The sentence
  156. is recognized by a trailing ':',';','!','?', or a '.'.  For
  157. the '.' there is the additional requirement that either two
  158. or more spaces must spaces must follow it, or that it is at the
  159. end of the source line.
  160.  
  161.         A command argument can be either ABSOLUTE or RELATIVE : 
  162.  
  163. .in    5    sets the indent value to 5 spaces
  164.  
  165. .in    +5    sets the indent value to the CURRENT value+5
  166.  
  167. .ls     -1    sets the line spacing to the current value-1
  168.  
  169.  
  170.     Also,  all commands have a minimum and maximum value
  171. that will weed out any odd command settings (like setting
  172. the line spacing to zero, for example. It won't let you do
  173. that, but it could be changed if you REALLY have a burning
  174. desire to do so).
  175.  
  176.     Some commands cause a "break", which is noted in the
  177. table below.  Before such a command goes into effect, the
  178. current line of text is put out, whether it is completely
  179. filled or not. (this is what happens at the end of a
  180. paragraph, for example.)  A line beginning with spaces or a
  181. tab will cause a break, and will be indented by that many
  182. spaces (or tabs) regardless of the indent value at that time
  183. (this is a "temporary indent", which can also be set
  184. explicitly).  An all blank line also causes a break.  If you
  185. find that some lines that are indented strangely, and it's
  186. not obvious WHY, look at which commands are causing a break,
  187. and which aren't. For instance:
  188.  
  189. .fi
  190. .ti 0
  191. this is a line of text
  192. .in 8
  193.                     <- blank line
  194. more text for the machine to play with
  195.  
  196.  
  197. At first glance it seems obvious that the line "this is a
  198. line of text" will be indented zero spaces, but it won't -
  199. it will be indented 8. The indent command does NOT cause a
  200. break (although the .ti does) so it will not cause the line
  201. to be put out before setting the indent value to 8.  Then,
  202. when the blank line is encountered, it will cause a break -
  203. and "this is a line of text" will be indented incorrectly.
  204.  
  205.     It is worthwhile considering placing a ".br", the
  206. break command, before each use of ".in"; should future
  207. versions of ROFFn have the break already part of the indent
  208. command?
  209.  
  210.  
  211.     Certain system variables are "stacked" to enable
  212. reversion to earlier environments instead of "hardcoded"
  213. defaults.  For example:
  214.  
  215. .ls 1
  216.  .
  217.  .
  218.  .
  219. .ls
  220.  
  221. The first command will produce single line spacing (which is
  222. the default, but which may have been set otherwise at the
  223. beginning of the manuscript).  The second command causes
  224. resumption of the original line spacing (either the default
  225. or whatever had been chosen previously).  Stacked variables
  226. include: linespacing, indent column, right margin,
  227. translation flag character, page length, top and bottom
  228. margin sizes, unexpandable space character, output width,
  229. tabsize, and control flag character.
  230.  
  231. *********************** Table of Commands *********************
  232.  
  233. Command          Break?    Default    stacked    Function
  234. -------       ------    ------- ------- ---------
  235. .. string    no            string is "mere"comment
  236.  
  237. .ab        no            immediate abort back to
  238.                     system
  239.  
  240. .bj        yes            break with right
  241.                     justification (current
  242.                     line only)
  243.  
  244. .bp n        yes    n =  +1        begin page numbered n
  245.  
  246. .br        yes            cause a break (this
  247.                     line is not justified)
  248.  
  249. .cf c        no    c = '^'    Yes    to be used as a prefix
  250.                     to a character that
  251.                     controls print func-
  252.                     tions such as ^+,^-
  253.                     might be used to
  254.                     bracket    superscripts,
  255.                     somewhat like
  256.                     WORDSTAR(TM).
  257.  
  258. .ce n        yes    n = 1        center next n lines
  259.  
  260. .db n        no    n = 0(NO)    set debug flag 1 for
  261.                     diagnostics
  262.  
  263. .di name    no    JUNK.$$$    diversion file
  264.                     (see "PREPROCESSOR")
  265.  
  266. .dm name    no            define (multiline)
  267.                     macro ("PREPROCESSOR")
  268.  
  269. .ds /../../../    no    null string    define string replace-
  270.                     ment ("PREPROCESSOR")
  271.  
  272. .ed        no            end diversion
  273.                     (see "PREPROCESSOR")
  274.  
  275. .ef /../../../    no    blanks        even footer titling
  276.  
  277. .eh /../../../    no    blanks        even header titling
  278.  
  279. .em                    end macro
  280.                     (see "PREPROCESSOR")
  281.  
  282. .fi        yes            start filling lines
  283.  
  284. .ff n        no    n = 1(yes)    initially, formfeeds
  285.                     are "off". Can turn
  286.                     them on.  Each page
  287.                     then terminated with
  288.                     one formfeed.
  289.  
  290. .fo /../../../    no    empty        sets both even and odd
  291.                     page footers
  292.  
  293. .fr # base - ;    no    1,no action    defines how to put
  294. - - - -    .                output device in mode
  295.                     for fractional line
  296.                     spacing(for super,sub-
  297.                     scripting);see details
  298.                     given below. Comple-
  299.                     ments .WH, below.
  300.  
  301. .he /../../../    no    empty        sets both even and odd
  302.                     page headers
  303.  
  304. .ic c        no    c = '\'    Yes?    to specify the char-
  305.                     acter used for macro
  306.                     preprocessing to denote
  307.                     the token that follows.
  308.  
  309. .ig string    no            "ignore" string(see ..)
  310.  
  311. .in n        no    n = 0    Yes    set indent value to n
  312.  
  313. .ju        no    initially on    turn on right justifi-
  314.                     cation (only applicable
  315.                     if "filling" also)
  316.  
  317. .ls n        no    n = 1    Yes    set line spacing to n
  318.  
  319. .m1        no    n = 2    Yes    set topmost margin to n
  320.  
  321. .m2        no    n = 2    Yes    set 2nd top margin to n
  322.                     lines
  323.  
  324. .m3        no     n = 2    Yes    1st bottom margin to n
  325.                     lines
  326.  
  327. .m4        no    n = 2    Yes    bottom-most margin to n
  328.                     lines
  329.  
  330. .ne n        no/yes    n = 2        "need" n lines; if have
  331.                     them no action; else
  332.                     begins new page
  333.  
  334. .nf        yes            stop filling lines
  335.  
  336. .nj        no    initially    turn off right justi-
  337.             is justifying    fication (only relevent
  338.                     if "filling" also)
  339.  
  340. .of /../../../    no    empty        odd page footer title
  341.  
  342. .oh /../../../    no    empty        odd page header title
  343.  
  344. .ou base - - ;    no    not applicable    direct output of code
  345. - - - .                    sequences to output.
  346.  
  347. .ow        no    n = 60        sets output width for
  348.                     header and footer title
  349.  
  350. .pc c base - ;    no    not applicable    used to create
  351. - - - .                    definitions for special
  352.                     printer controls, such
  353.                     as for italics.
  354.  
  355. .pl n        no     n = 66    Yes    sets page length to n
  356.  
  357. .rg name n    no    n=0    No    create or modify 
  358.                     register variable
  359.                     (see "PREPROCESSOR")
  360.  
  361. .rm n        no    n = 60    Yes    sets right margin to n
  362.  
  363. .sa string                "say": message to
  364.                     console; like a comment
  365.                     but displayed to
  366.                     operator during run.
  367.  
  368. .sc c        no    blank    Yes    space character; the
  369.                     visible character
  370.                     that will be trans-
  371.                     literated to unexpanded
  372.                     blank.
  373.  
  374. .so filename    no    ignored    Yes    reads named file into
  375.                     input stream; cannot be
  376.                     invoked from keyboard
  377.                     input.
  378.  
  379. .sp n        yes    n = 1        space down n lines
  380.  
  381. .st n        no    n=1(yes)    stop(pause)at each page
  382.                     start; initially off;
  383.                     may also be enabled by
  384.                     the -s option.
  385.  
  386. .tc c        no    ~    Yes    set translation flag
  387.                     character, see .tr
  388.  
  389. .tr c base - ;    no    not applicable    used to create
  390. - - - .                    definitions for special
  391.                     character fonts.
  392.  
  393. .ts n        no    n = 8    Yes    sets value of tab space
  394.  
  395. .ti n        yes    n = 0        set temp. indent of n
  396.  
  397. .wh        no    no action    instructs how to resume
  398.                     whole line spacing;
  399.                     complements .FR, above.
  400.  
  401. -------------------------------------------------------------
  402.  
  403.  
  404.  
  405. Here's what the page parameters look like:
  406.  
  407.     |<--------output width (.ow)------------------->|
  408.  
  409. _    _________________________________________________
  410. |    |    top margin(m1) - (includes header)    |
  411. |    |-----------------------------------------------|
  412. |    |        top margin 2            |
  413. |    |-----------------------------------------------|
  414. P    |    :                :    |
  415. A    |    :<-indent            :    |
  416. G    |    :                :    |
  417. E    |    :lots and lots of silly text and:    |
  418. L    |    :other garbage. Get the picture?:    |
  419. E    |       :This is a temp.  indentation:    |
  420. N    |    :                :    |
  421. G    |    :        right margin -> :    |
  422. T    |    :                :    |
  423. H    |    :                :    |
  424. |    |-----------------------------------------------|
  425. |    |        margin 3            |
  426. |    |-----------------------------------------------|
  427. |    |  margin 4 - (includes footer,perhaps ff)    |
  428. -    -------------------------------------------------
  429.  
  430. Minimum acceptable values for M1, M2, M3, and M4; if M1 is set
  431. to zero, no header will be shown (even if one was declared).
  432. Similarly, if M4 is set to zero, no footer will be displayed.
  433.  
  434.  
  435. To change the default for any parameter, simply alter ROFF4.H
  436. and reSUBMIT ROFF4.SUB .
  437.  
  438.  
  439. ************************************************************
  440. A Few Extra Comments on Some of the Commands:
  441. ************************************************************
  442.  
  443.                 If you want to center lots of lines, but don't
  444.         want to count them, do something like this:
  445.  
  446. .ce    1000
  447. lots and
  448. lots of words to
  449. be centered
  450. .ce 0
  451.  
  452.         --------------------------------------
  453.  
  454. A new paragraph may be caused by using the temporary indent
  455. command, like
  456.  
  457. .ti +5
  458.  
  459. or by simply beginning the paragraph with a tab, as you would
  460. if you were just typing.
  461.  
  462.         ------------------------------------
  463.  
  464.     For special cases, where you wish to place the last
  465. "word" at the right-hand margin, such as numbers of equation,
  466. for example:
  467.  
  468.             x = y+z                (12)
  469. you could input:
  470.  
  471. # x#=#y+z (12)
  472. .bj
  473.  
  474. because we force a break with justification (.bj) of the
  475. line with only "three words". (The # is assumed to be the
  476. "space character" set up with a .sc command).
  477.  
  478.         ------------------------------------
  479.  
  480. Headers and Footers.
  481.  
  482.         A page number can be incorporated into any header or
  483. footer by putting a "#" in the title where you want the number
  484. to go:
  485.  
  486. .he    /This is a witty header title for page #/
  487.  
  488. Each time this is printed at the top of a page, the current
  489. page number will be substituted for the "#".
  490.  
  491. Each footer and header are ".in 0", even if text is
  492. indented.
  493.  
  494. Headers and footers are in three parts.  These parts are left
  495. justified, centered, and right justifed.  Any of these three
  496. parts may be left out.  The right justification is fixed to the
  497. margin that is set by the .OW command.  One may pick the
  498. headers and footers separately for even and odd pages.  For
  499. example, one could place even and odd page numbers at the
  500. bottom outside of each page by:
  501.  
  502. .ef /Page #///
  503. .of ///Page #/
  504.  
  505.     Any printable character, here the '/', can be used to
  506. delimit the three strings that make up the titles, so long
  507. as it is not the "insert character" (usually, '\') and is
  508. not present in any of the three strings.
  509.  
  510.     The program can be made to wait for the operator to
  511. load single sheets of paper by the -s option and/or by the
  512. command: .st
  513.  
  514.         ------------------------------------
  515.  
  516. If you want to send the output to a file, and don't want the
  517. page breaks in there set margins 1-4 to zero.
  518.  
  519.     ------------------------------------
  520.  
  521.     Where you need to supply code sequences for
  522. immediate or for subsequent output (for .ou or for .tr) one
  523. needs to supply the number base (binary, octal, decimal, or
  524. hexadecimal) by supplying a token that begins with (upper
  525. and lowercase are both o.k.): b, o(or q), d, or h. Following
  526. the base on the same and/or subsequent lines one supplies
  527. the codes that will form the "code string". These codes are
  528. delimited by white space (not commas!) and the sequence is
  529. eventually terminated by a token beginning with a period.
  530. The ends of any of these lines may contain comments if they
  531. are set off by white space and a semicolon. For examples:
  532.  
  533. .ou hex 11 1C 8C 0
  534. 99 6C 55 ;get ready!
  535. .end
  536.  
  537. .TR = binary ;"identity"operator (triple equal sign) on MX-80
  538. 00011011 ;ESC
  539. 01001011 ;4B
  540. 00000110 ;6 bit patterns
  541. 0     ;follow:
  542. 00101010 ;left top,bot
  543. 00101010
  544. 00101010
  545. 00101010
  546. 00101010
  547. 00000000 ;right top,bot
  548. .en
  549.  
  550.     The first of these examples might be used to get
  551. some strange printer to cooperate in standing on its head or
  552. something.  
  553.  
  554.     The second, lengthier example is taken from a file,
  555. MX, that defined quite a number of special characters for
  556. the MX-80 with GRAFTRAX 80.  Because that printer uses dot
  557. graphics, I chose to make the definition in binary so that
  558. the placement of the individual dots is easier to visualize.
  559. Later, in the text the combination: ~=  will cause the
  560. printer to be sent this code so that it will print the
  561. specialized symbol.
  562.  
  563.               SPECIAL SYMBOLS
  564.  
  565.     If one includes a set of definitions such as in the
  566. MX file, one can specify the use of special symbols, which
  567. can be chosen to fit the application (and the hardware!) For
  568. example, the MX-80 printer equipped with GRAFTRAX 80 can
  569. accept dot addressed graphics.  [See the MX file for
  570. examples with this hardware].  Other printers may be able to
  571. simulate symbols by a combination of overstruck characters.
  572. Still other output devices may be capable of displaying
  573. desired special symbols by use of the "parity bit".
  574.  
  575.     The .tr and .tc commands define the codes for the
  576. special symbols and the translation character.  To create a
  577. "wall chart" that lists the special characters on the output
  578. device you could use the -g option on the command line, for
  579. example:
  580.  
  581. A>roff4 mx -g )
  582.  
  583.  
  584.         ====================================
  585.  
  586.  
  587.               PRINTER CONTROL
  588.  
  589.     It is assumed that the output device can accept
  590. carriage returns and will not linefeed in the absence of the
  591. linefeed character.  Using this assumption, super- and
  592. subscripting, backspacing, underscoring, strickout, and
  593. multiple impressions are supported in a manner somewhat
  594. analogous to WORDSTAR [tm by MicroPro], but more generally.
  595.  
  596.     If the printer can be placed in fractional
  597. linespacing mode, so much the better, as full line spacing
  598. for super- and subscripts does not look as "natural".  Also,
  599. with the half line spacing, one can build up larger
  600. characters (such as summation and integration symbols) since
  601. some overlap does occur.  To implement such fractional
  602. spacing one uses the commands, .fr and .wh (probably at the
  603. beginning of the input file, along with other information
  604. relevent to the output device and style).  These commands
  605. describe the operational codes sent to the output to switch
  606. the printer to FRactional spacing and back to WHole line
  607. spacing.
  608.  
  609.     For example,  I use for the MX-80 printer equipped
  610. with GRAFTRAX 80 the following:
  611.  
  612. .WH HEX 1B 32 . ; 6 lines/inch is standard
  613. .fr 2 hex 1b 33 12 . ; 18/216" = halfline spacing
  614.  
  615. The initial 2 in .fr tells the formattter that 2 fractional
  616. [half] lines are equivalent to a conventional whole line.
  617. The original description of the required codes were in
  618. hexadecimal, so I kept matters as simple as possible by
  619. using the same number base so that I would not make any
  620. conversion mistakes!
  621.  
  622.     The printer control requests are embedded in the
  623. text; they are NOT set off in separate lines as the "dot"
  624. commands are set apart.  Each request is made up of two
  625. printable characters, the first of which is the "control
  626. flag character" (the default is '^').  Here is a table of
  627. control functions presently supported by ROFF4, version 1.30:
  628. (additional codes can be created with the "printer control"
  629. command, .pc)
  630.  
  631. ^+    up a fractional line; may be used several times to
  632.     increase vertical rise. [used at start of a
  633.     superscript and at the end of a subscript]
  634.  
  635. ^-    down a fractional line; may be used several times to
  636.     increase vertical drop. [used at the start of a
  637.     subscript and at the end of a superscript]
  638.  
  639. ^h,^H    backspace one character column.  Do NOT backspace
  640.     over ordinary blanks ("unexpandable" space is o.k.)
  641.     if you are in "fill" mode.
  642.  
  643. ^(,^)    Note current column position; return to noted position.
  644. ^[,^]    "    "    "    "    "    "    "
  645. ^{,^}    "    "    "    "    "    "    "
  646.  
  647.     The above three pairs of controls are often more
  648.     convenient then multiple, explicit backspaces, ^H,
  649.     especially for "built-up" fractions and matrices.
  650.  
  651. ^B,^b    Start, end boldface (increase, decrease the number
  652.     of impressions by a factor of 3).
  653.  
  654. ^D,^d    Start, end doublestrike (increase, decrease the number
  655.     of impressions by a factor of 2).
  656.  
  657. ^U,^u    Start, end underscore (will not underscore
  658.     expandable white space; will ride up and down with
  659.     super and subscripts.)
  660.  
  661. ^X,^x    Start, end strikeout (similar to underscore, above,
  662.     but overprints with '-' instead of underlines).
  663.  
  664.  
  665.     Note that the last 4 pairs are "case sensitive";
  666. namely, the uppercase starts some activity, whereas the
  667. lowercase equivalent sqelches it;  these controls are
  668. NOT "toggles".
  669.  
  670.     An involved example of the use of printer controls
  671. would be to create a 3 by 3 matrix:
  672.  
  673. MATRIX =#^+^+^(|1#2#3|^)^-^-|4#5#6|^)^-^-|7#8#9|^+^+
  674.  
  675. which should produce (with a half-spacing) printer:
  676.  
  677.  
  678.          |1 2 3|
  679. MATRIX = |4 5 6|
  680.          |7 8 9|
  681.  
  682. [the demonstration file, MATRIX, has been provided as a
  683. demonstration of the above].
  684.  
  685. Several points should be observed.  There should be no
  686. expandable blank spaces if you are in fill mode, otherwise,
  687. the result might be very strange! (ROFF4 does some checks to
  688. flag such attempts). We are assuming here that the '#' are
  689. unexpandable spaces (chosen with the .sc command).  The
  690. first printable character in the complex, the '=', is at the
  691. leftmost edge; the last printable character, the '|'
  692. following the '9', is at the rightmost edge of this
  693. assemblage.  The final height is adjusted (by the trailing
  694. ^+^+ ) to match the initial height.  The present limit of
  695. the line buffering is 255 characters; I assume that is not
  696. too chancy.
  697.  
  698.     One can define additional printer control codes
  699. using the .pc command.  For example, the MX-80 printer with
  700. Graftrax is switched to italics with the sequence <ESC> '4';
  701. and italics are turned off with <ESC> '5'.  We could define
  702. ^I to start italics and ^i to end them:
  703.  
  704. .pc I hex ;italics on (MX-80 & Graftrax)
  705. 1B 34
  706. .en
  707. .pc i hex ; italics off (MX-80 & Graftrax)
  708. 1B 35
  709. .en
  710.  
  711.  
  712.  
  713.           ================================
  714.  
  715.               THE PREPROCESSOR
  716.               === ============
  717.  
  718.     In the following we describe the advanced macro
  719. preprocessing features of this formatter which provide users
  720. with labor saving tools but which are probably not necessary
  721. at first.  The beginning user may be able to achieve most
  722. goals without the "preprocessing", but by using an editor
  723. more then otherwise.  The more advanced user will begin to
  724. appreciate these features more.
  725.  
  726.     In the following discussion we will assume the
  727. default insert character, '\', and the default command
  728. character, '.', will be used.  (It is rare that you should
  729. change these anyway!)
  730.  
  731.     The insert character is used to denote where a
  732. replacement should be used.  For example, in:
  733.  
  734. Today, \date\, is special.
  735.  
  736. the block, "\date\", would be replaced as this sentence is
  737. being input.  If a prior string definition of the form:
  738.  
  739. .ds *date*January 1, 1983*
  740.  
  741. had been processed previously then the example, after text
  742. substitution, would become:
  743.  
  744. Today, January 1, 1983, is special.
  745.  
  746.     The string definition command, .ds, expects that the
  747. first visible character, here a '*', is the delimiter of the
  748. start and end ot the two parts in the definition;  any
  749. printable character (that is not present in either string!)
  750. may be used.
  751.  
  752. If no string definition had been provided for "date", the
  753. user will be prompted while the formatter is trying to input
  754. this sample line.  The console will get some message like:
  755.  
  756. [Bell]Please define <date>:
  757.  
  758. Whatever you type in will be used to form an "effective" .ds
  759. definition.  This feature should be useful in applications
  760. where information should be changed or updated each time the
  761. formatter is run, such as today's date, the addressee's name
  762. and address in a form letter, etc.  A sample file, FORM is
  763. included to demonstrate both of the above means to define
  764. string substitutions.
  765.  
  766. An important restriction must be observed when using
  767. "definitions on the run".  They must not be first used
  768. inside of multiline definitions (namely inside of .ou, .tr,
  769. .dm, .pc, .wh, and .fr) because the building of both
  770. definitions will cause them to interfere with each other.
  771. ROFF4, v1.6 will test for such contention and abort
  772. operation if one is found.  An example of such a situation
  773. and its remedy is shown below:
  774.  
  775. .sa chose 0 for DRAFT and 1 for CORRESPONDENCE
  776. .ou hex
  777. 1B
  778. 3\font\
  779. .end .ou
  780.  
  781. This example, which might be used to initialize the Okidata
  782. Microline 92 printer to go into correspondence quality or
  783. into draft quality printing would cause problems if "font"
  784. is supposed to be defined here during execution.  We are in
  785. the midst of defining an output string for the printer (ESC
  786. "0" or ESC "1") when we are asking ROFF4 to create
  787. (simultaneously) a definition for "font";  the program will
  788. abort rather than continue with the two definitions mangling
  789. each other.  Here is a modified version of above without the
  790. problem:
  791.  
  792. .sa chose 0 for DRAFT and 1 for CORRESPONDENCE
  793. .. this comment containing \font\ is "ignored"
  794. .ou hex
  795. 1B
  796. 3\font\
  797. .end .ou
  798.  
  799. The fix here is that the formatter will encounter "\font\"
  800. in the comment and complete a definition for "font" before
  801. takling the .ou command;  no simultaneous definitions, no
  802. problems!
  803.  
  804.     Similar to string definitions are register
  805. variables, which are created and modified with the .rg
  806. command.  Variables are useful for enumeration such as
  807. equation numbering:
  808.  
  809. .rg eqnum 1
  810.  
  811. would create a register named "eqnum" with the current value
  812. of 1.  The the text might use it with, say:
  813.  
  814.          x = y+1          (\eqnum\)
  815.  
  816. which would be converted on input into:
  817.  
  818.          x = y+1          (1)
  819.  
  820. A subsequent instruction:
  821.  
  822. .rg eqnum +1
  823.  
  824. would take the current value of "eqnum" and increase it by 1
  825. (so that it would now be 2 in our example:
  826.  
  827.          a = b+c          (\eqnum\)
  828.  
  829. would become:
  830.  
  831.          a = b+c          (2)
  832.  
  833.     There is a special, reserved insertion, \#\, which
  834. will provide the current page number.  It should prove
  835. useful in setting up tables of contents (see "diversions",
  836. below).  Trivial examples of its use are to be found in the
  837. files, BPTEST and MARGINS.  In rare cases it may be off one
  838. page because it may be read while between pages;  how can one
  839. handle the sentence, "This sentence is on page XXX," when the
  840. sentence straddles two pages?
  841.  
  842.     Since we have defined a special register name, '#',
  843. we should comment on what happens if you create a register
  844. instruction with that name, such as:
  845.  
  846. .rg # +1
  847.  
  848. You will be changing the value of the page number of the
  849. FOLLOWING pages.  This is useful for leaving gaps in the 
  850. pagination for later inclusion of full page illustrations.
  851. This feature is demonstrated (tested) in the file, MARGINS.
  852. I wish to thank Henry Harpending for suggesting this.
  853.  
  854.     The insert character has other properties.  The
  855. insert character can be placed into the input by repeating
  856. it, namely, "\\" becomes "\".  (useful for delaying
  857. substitutions).  For example, defining:
  858.  
  859. .ds 'EN'(\\eqnum\\)'
  860.  
  861. will identify "EN" with "(\eqnum\)" and so our equation
  862. example above could have been:
  863.  
  864.          a = b+c          \EN\
  865.  
  866. Delaying the evaluation of "eqnum" until EN is invoked
  867. (instead of when it was defined) means that the proper
  868. numbering of equations will occur instead of wrongly
  869. supplying the value of "eqnum" from the time that EN was
  870. first created.
  871.  
  872.     If the insert character is at the end of a line, it
  873. negates the following newline sequence;  thus the next line
  874. is merged with the current line.  For example:
  875.  
  876. antidisestab\
  877. lishmentarianism
  878.  
  879. is equivalent to:
  880.  
  881. antidisestablishmentarianism
  882.  
  883.     "Macro" definitions are used when we wish to
  884. identify several lines with an insertion.  Such definitions
  885. are created with the .dm ["define macro"] and completed with
  886. the .em ["end macro"] commands.  For example, we might wish
  887. to use the following sequence over and over again at the
  888. start of paragraphs:
  889.  
  890. .sp 1
  891. .ne 2
  892. .ti +5
  893.  
  894. to separate the paragraphs by blank lines, keep them from
  895. starting excessively close to the bottom of the page, and
  896. indenting them 5 spaces to the right of the current left
  897. margin.  We might want to define the "command" as
  898. "paragraph" [personally, I might call it "P", because it
  899. would be used a lot and my typing ...]:
  900.  
  901. .dm paragraph
  902. .sp 1
  903. .ne 2
  904. .ti +5
  905. .em
  906.  
  907. Subsequently, whenever we wished to start a paragraph we
  908. would creat a command line:
  909.  
  910. .paragraph
  911.  
  912. instead of more tediously creating every time the three
  913. commands we mentioned above.
  914.  
  915.     The names of all macros, strings, and number
  916. registers are "case sensitive".  That is to say that
  917. capitalization and/or lower case are distinguished and, say,
  918.  
  919. .Paragraph
  920.  
  921. Would not be recognized as the same as the sample macro we
  922. just defined.  However, all the "built-in" commands, those
  923. which were listed in the command table, are not case
  924. sensitive and are recognized on the first two letters alone,
  925. even if arbitrary letters or numbers follow immediately.
  926. If we had a line:
  927.  
  928. .time
  929.  
  930. it would be identified with a "time" macro definition, if
  931. one had been created;  It would not be confused with a
  932. "Time" macro definition.  If there is no "time" macro, then
  933. it would be matched with the "built-in", .TI ["temporary
  934. indent"].
  935.  
  936.     There is another object formed and used somewhat
  937. like a macro;  it is called a "diversion (file)" and is
  938. useful for making lists such as references [footnotes] and
  939. tables of contents.  A diversion is created or continued
  940. with the commands: .DI [diversion] and .ED [end diversion].
  941. A diversion can grow to be quite large and is, in fact, a
  942. disk file.  To "regurgitate" the diversion file, its name
  943. can be placed in the original command line, along with the
  944. other input file names; alternatively, files can be
  945. retrieved with the .SO ["source"] command.  The advantage
  946. of using .SO is that inclusion can be accomplished without a
  947. page break, nor even a line break between input files.  The
  948. .SO command is like a "CALL" or "GOSUB" in that there can be
  949. nested .SO invokations; one can access a file with .SO that
  950. contains in turn a .SO command, etc.  It is a limitation of
  951. ROFF4 at present to not be able to handle the .so command
  952. from keyboard input (it could be useful).  The files,
  953. SOTEST, ONE, TWO, and THREE are provided to test and
  954. demonstrate the .SO command.
  955.  
  956.     All file names referenced by .di and .so are
  957. automatically treated as uppercase.  The naming conventions
  958. should conform to the operating system (CP/M).  It is a
  959. limitation of the formatter at present to not realize that
  960. "A:ZZ" would be the same as "ZZ"; be sure to use the same
  961. form throughout!
  962.  
  963.     We shall present a detailed example of the use  of
  964. the above preprocessing commands to automate footnote and
  965. reference numbering and collection.
  966.  
  967.     We start by creating a register variable, "f#", to
  968. keep track of the current footnote number:
  969.  
  970. .rg f# 1
  971.  
  972.     We shall use, say, "[15]" as our means to display
  973. reference numbering.  (We could have used superscripts
  974. instead with "^+15^-"):
  975.  
  976. .ds "fn"[\\f#]"
  977.  
  978. We have used "\\" so that "fn" is defined as "[\f#\] and
  979. will be evaluated with the current footnote number at the
  980. time of use (not of the time we nade this .ds definition).
  981. By typing \fn\ we will get the reference in the form,
  982. "[number]", that we wanted.
  983.  
  984.     We want to create a diversion, "FNOTES", into which
  985. we will place all our references.  The head of this file
  986. will be titled with "REFERENCES":
  987.  
  988. .di fnotes
  989. .ls 1
  990. .sp 1
  991. .ce 1
  992. REFERENCES
  993. .sp 2
  994. .ed
  995.  
  996.     The diversion will contain (hopefully) a list of
  997. numbered footnotes.  To make the addition of these footnotes
  998. as painless as possible, we define two macros, "FS"
  999. [footnote start] and "FE" [footnote end]:
  1000.  
  1001. .dm FS
  1002. .di fnotes
  1003. .sp 1
  1004. \\fn\\\\
  1005. .em
  1006.     and:
  1007. .dm FE
  1008. .ed
  1009. .rg f# +1
  1010. .em
  1011.  
  1012. The FS macro skips a line and attaches the evaluation of
  1013. \fn\ to the start of the line that follows the macro during
  1014. execution.  The lines that follow the FS macro will be
  1015. diverted to FNOTES.  The FE macro terminates the diversion
  1016. and, also, increments the footnote number, f#.
  1017.  
  1018.     We could try a very small piece of text now:
  1019.  
  1020. .nf
  1021. It is a nice day.\fn\
  1022. .FS
  1023. conventional expression.
  1024. .FE
  1025. It's a crummy day.\fn\
  1026. .FS
  1027. unconventional!
  1028. .FE
  1029.  
  1030. The formatter will generate:
  1031.  
  1032. It is a nice day.[1]
  1033. It is a crummy day.[2]
  1034.  
  1035. and the diversion file, FNOTES, will contain:
  1036.  
  1037. .ls 1
  1038. .sp 1
  1039. .ce 1
  1040. REFERENCES
  1041. .sp 2
  1042. .sp 1
  1043. [1]conventional expression.
  1044. .sp 1
  1045. [2]unconventional!
  1046.  
  1047. which, after formatting, will be:
  1048.  
  1049.  
  1050.              REFERENCES
  1051.  
  1052.  
  1053. [1]conventional expression.
  1054.  
  1055. [2]unconventional!
  1056.  
  1057. otes.  To make the addition of these footnotes
  1058. as
  1059. It is a nice day.\fn\
  1060. .FS
  1061. conventional expression.
  1062. .FE
  1063. It's a crummy day.\fn\
  1064. .FS
  1065. unconventional!
  1066. .FE
  1067.  
  1068. The formatter