Usenet 1994 October/usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso/unix/volume21/ro/part03

Text File | 1990-02-05 | 50KB | 1,637 lines

Subject:  v21i005:  A text formatter with some nroff-like capabilities, Part03/03
Newsgroups: comp.sources.unix
Sender: sources
Approved: [e-mail]

Submitted-by: [e-mail] (Ted A. Campbell)
Posting-number: Volume 21, Issue 5
Archive-name: ro/part03

#! /bin/sh
#
# This is a shell archive.  Save this into a file, edit it
# and delete all lines above this comment.  Then give this
# file to sh by executing the command "sh file".  The files
# will be extracted into the current directory owned by
# you with default permissions.
#
# The files contained herein are:
#
# -rw-r--r--  1 tcamp   users     36027 Nov 24 12:50 ro.doc
# -rw-r--r--  1 tcamp   users      6666 Nov 10 12:57 ro.qrf
# -rw-r--r--  1 tcamp   users      2829 Nov 24 12:50 tmac.m
# -rw-r--r--  1 tcamp   users       663 Nov 24 12:50 test.doc
#
echo 'x - ro.doc'
if test -f ro.doc; then echo 'shar: not overwriting ro.doc'; else
sed 's/^X//' << '________This_Is_The_END________' > ro.doc
X..    \"-------------------------------------------------------
X..    \"
X..    \"    ro.doc
X..    \"
X..    \"    documentation for the ro text formatter
X..    \"
X..    \"    NOTE:  This documentation is in "ro"
X..    \"    format and will not read correctly unless
X..    \"    it is processed by ro and postprocessed by
X..    \"    an ro filter.  To read the document on
X..    \"    a computer with the "more" pager, the
X..    \"    command line:
X..    \"
X..    \"        ro ro.doc | termnull | more
X..    \"
X..    \"    should work.
X..    \"
X..    \"-------------------------------------------------------
X.so tmac.m
X.PH "'ro v1.00''\*(DT'"
X.PF "''Page  #''"
X.nr Pi 5
X.nr Ps 1
X.ls 1
X.ll 65
X.sp 2
X.ce
X\fBRO.DOC\fR
X.sp 1
X.ce
X\fBDocumentation for the RO Text Formatter\fR
X.sp 2
X.ce
X\fICopyright Information\fR:
X.nf
X
X    ro, version 1.00:
X
X    Portions copyright (c) 1989 by Ted A. Campbell
X        Bywater Software
X        P. O. Box 4023
X        Duke Station
X        Durham, NC  27706
X
X    Contains portions of ROFF4, Version 1.61
X                (c) 1985 by Konrad Kwok
X        20 3rd Street, Section M
X        Fariview Park,
X        Hong Kong
X
X    Contains portions of ROFF4, Version 1.60
X                (c) 1983, 4 by Ernest E. Bergmann
X        Physics, Building #16
X        Lehigh University
X        Bethlehem, Pa. 18015
X.fi
X.P
X\"ro" and its predecessor ROFF4 are based on
Xthe ROFF text processor described in Brian W. Kernigan
Xand P. J. Plauger's now-classic text \fISoftware Tools\fR
X(Reading, MA: Addison-Wesley, 1976).
X.P
XPermission is hereby granted for all commercial and
Xnon-commercial reproduction and distribution of this
Xmaterial provided this notice is included.
X.ne 4
X.sp 2
X.ce
X\fIGeneral Description\fR
X.P
X\"ro" is a text formatter.  It is based on the
XCP/M ROFF4 formatter,
Xwhich was an expanded version of ROFF, itself based on the
Xformatter in Kernigan and Plauger's \fISoftware Tools\fR.
XIt is written in the C programming language, and has
Xbeen successfully compiled on both Unix and DOS
Xcomputers.
X.P
X\"ro" is designed to be downwardly-compatible
Xwith the Unix-based "nroff" text formatter,
Xand efforts have been made to make this
Xversion of ro as much like nroff as possible,
Xalthough many nroff features (like
Xwithholding traps) are not yet implemented
Xin ro.
X\"ro" adds some features to nroff, such as
Xdebug and verbose modes (using the "-x" and "-v"
Xflags, respectively), and a number of predefined
Xcommands which are usually implemented as macros
Xin nroff (e.g., .HE, which sets a three-part
Xpage header).
X.P
XIncluded with this implementation of ro
Xis a package of macros named "tmac.m".
XThis implements some of the macros
Xfound in the popular nroff-based
X\"-mm" macro package.
X.ne 8
X.sp 2
X.ce
X\fIUsing ro\fR
X.sp 1
X\fIInvoking the Program\fR:
X.P
X\"ro" is command-line based,
Xand by default takes its input
Xfrom "standard input."
XAll output is sent to "standard output."
XThe command
X.sp
X.ti 5
X\ro
X.sp
Xby itself would simply read input from
Xthe keyboard and output to the screen.
XUtilizing the command-line "<" and ">"
Xoperators in Unix and DOS, you can redirect
Xboth the standard input and the standard output.
XThus the command
X.sp
X.ti 5
X\ro <infile >outfile
X.sp
Xwould take its input from "infile" and send output
Xto "outfile."
X.P
XIt is possible to send output
Xdirectly to the printer utilizing
Xoutput redirection.  In Unix, the command
X.sp
X.ti 5
X\ro <infile >/dev/lp
X.sp
Xwould take its input from "infile" and
Xsend the output to "/dev/lp",
Xwhich is usually implemented as the line printer.
XSimilarly, in DOS, the command
X.sp
X.ti 5
X\ro <infile >prn
X.sp
Xwould send output to the "PRN" device,
Xwhich is normally attached to the printer.
X\fBHowever\fR, it is usually undesirable
Xto send output directly to a printer
X(or the screen, for that matter),
Xsince ro output will likely
Xinclude unprocessed printer escape codes.
XFor this reason, it is deirable to use an
Xoutput "post-processor" (see below
Xunder \fIUsing a Post-Processor\fR).
X.P
X\"ro" can also take its input from files named
Xdirectly on the command line (without the
X\"<" operator).  The command
X.sp
X.ti 5
X\ro infile
X.sp
Xwould read input directly from "filename",
Xand the command
X.sp
X.ti 5
X\ro file1 file2 file3
X.sp
Xwould read input from files "file1",
X\"file2", and "file3" successively.
XNote that input must be from named files
X(and not from standard input)
Xif you wish to utilize the "-s" flag
Xoption (described below).
X.ne 4
X.sp 2
X\fICommand-Line Flags\fR
X.P
X\"ro" utilizes a number of command-line flags
Xto control the program.
XAll flags are processed before text input is received.
X.P
XThe \fB-s\fR flag, causes the formatter to stop (pause)
Xat the start of each page of output; a tone at the
Xconsole is sounded and the program
Xwaits until the RETURN key is pressed.  It
Xis essential for printers that are fed single sheets
Xat a time!
X\fBPlease note\fR that to utilize this feature,
Xyou must name files directly on the command
Xline.  (This is because the key-press to resume
Xprinting must itself come from standard input.)
X.P
XThe \fB-o[page or range]\fR flag
Xis used to selectively generate output of ONLY certain
Xpages.  It is useful to retype pages that got "eaten"
Xby the printer (Henry Harpending's aptly put language).
XTo retype only page 23, say, make the option: -o23
XTo retype pages 23 through 29 use: -o23-29
XTo retype pages 23 to the end use: -23-
XThese options changes the values of the internal
Xvariables, FIRSTPAGE and LASTPAGE which originally
Xhave the values of 1 and 30000, respectively.
X.P
XThe comamnd-line flag \fB-f\fR will introduce a formfeed (0CH)
Xinto the output stream at the bottom of every page.
XThis is usefull, e.g., if you want to output in compressed
Xpitch where the end of the printed page might not
Xcorrrespond to the end of the physical page.
X.P
XThe flag \fB-v\fR turns on "verbose" mode.
XIn this mode, some chit-chatty messages are
Xprinted to "standard error" (almost always
Xthe console), including some rather important
Xerror messages.  Normally, only fatal error
Xmessages are printed when verbose mode is not on
X(because ro is expected
Xto do much of its work in the background).
X.P
XThe option \fB-x\fR turns on the "debug" flag so as to
Xprint out lots of diagnostics to the STDERR [console].
XProbably only useful for those who are trying to
Xtrace the operation of the formatter for elusive
X\"bugs".
XSpecifying the "-x" flag will also turn on
Xthe "verbose" mode (but not \fIvice versa\fR).
X.ne 4
X.sp 2
X\fIDefault Values\fR
X.P
XUsing ro, you can make nice printouts of a file,
Xwith as little or as much help from the program as you want,
Xdepending on the commands.  There are default values for all
Xparameters, so if you don't put any commands in at all, your
Xfile will come out with filled, right-justified lines.  The
Xdefault line-length is 65 characters; the default page-
Xlength is 66 lines per page.  "Filled lines" means that as
Xmany input words as possible are packed onto a line before
Xit is printed; "non-filled" lines go through the formatter
Xw/o rearrangement.  "Adjusted" or "right-justified" simply means that
Xspaces are added between words to make all the right margins
Xline up nicely.  To change a parameter, use the appropriate
Xcommands below. All commands have the form of a period
Xfollowed by two letters. A command line should have nothing
Xon it but the command and its arguments (if any); any text
Xwould be lost.
X.ne 4
X.sp 2
X\fIUsing a Postprocessor\fR
X.P
X\"ro" does not handle printer-specific control codes itself;
Xinstead, it sends out simple (but consistent) escape
Xsequences which have to be "post-processed" by another program
Xto fit a particular terminal or printer.
XThree example post-processors are provided
Xwith ro:
X.sp
X.nf
X    termnull     strips out all printer codes
X    termansi    prepares sequences for an ANSI-
X            compatible terminal
X    termnx10    prepares sequences for the Star
X            NX10 printer
X.fi
X.sp
XAll of these postprocessors take their input
Xfrom standard input, and send their output
Xto standard output.
X.P
XYou can use the "|" ("pipe") operator
Xto send the output from ro directly to
Xa postprocessor, and you can use "|" again
Xto send the post-processor's output to
Xa print spooler, pager, or other program.
XHere are some useful examples:  The command
X.sp
X.ti +5
X\ro filename | termnull | more
X.sp
Xinvoles ro with input from "filename",
Xpipes its output to termnull, where all
Xprinter sequences are stripped away,
Xand then sends its output to the "more"
Xpager.  Utilizing this sequence, one
Xcould preview "filename" on any terminal,
Xalthough no printer-specific sequences would
Xbe shown.  For ANSI-compatible terminals
X(including DOS computers which have ANSI.SYS
Xinstalled), the sequence
X.sp
X.ti +5
X\ro filename | termansi | more
X.sp
Xwould do the same as the previous command,
Xexcept that boldface would appear
Xin bold, and italics would appear underlined
Xin the output.
XThe Unix sequence
X.sp
X.ti +5
X\ro filename | termnx10 | lp
X.sp
Xwould take input from "filename",
Xset up sequences for the Star NX10
Xprinter, and send the output
Xto the "lp" print spooler.
XSimilarly, under DOS,
X.sp
X.ti +5
X\ro filename | termnull >prn
X.sp
Xwould take input from "filename",
Xstrip out all printer codes, and
Xsend the output to the PRN device
X(normally attached to the printer).
X.P
XThe escape codes sent out by ro are simple, and are
Xlisted at the end of this document.
XWith these and the source code to termnx10 (included),
Xit should
Xbe relatively easy to write a post-processor
Xfor almost any terminal or device.
X.ne 8
X.sp 2
X.ce
X\fIInput to ro\fR
X.sp 1
X\fIInput Text\fR
X.P
X\"ro" generally reads input until it can fill out
Xa complete line of text (specfied by the "line length"
Xvariable, set by the command .ll).
XBy default, it then "adjusts" or justifies these
Xinput line when putting them out.
XBoth the "filling" and the "adjustment" of lines
Xcan be toggled on and off (see the commands
Xdescribed below, .fi, .nf, .ad, .na).
X.P
XExtra space will separate text sentences.  The sentence
Xis recognized by a trailing ':',';','!','?', or a '.'.  For
Xthe '.' there is the additional requirement that either two
Xor more spaces must spaces must follow it, or that it is at the
Xend of the source line.
X.ne 4
X.sp 2
X\fIInput Commands and Their Arguments\fR
X.P
X\"ro" is controlled internally by commands
Xthat are identified by a period ('.') in the
Xfirst place on a line.
XBe carefull:  if you inadvertently place
Xa period in the first place in a line,
X\"ro" will try to interpret it
Xas a command.
X\"ro" commands are either one or two letters
Xin length, and are all case-sensitive,
Xi.e., the command
X.sp
X.ti +5
X .In
X.sp
Xis different from the command
X.sp
X.ti +5
X .in
X.sp
Xand so on.
XBy convention, built-in commands are lower-case,
Xand macros (see below) are upper-case;
Xhowever, this is not a rule, and we have elected
Xto place all non-nroff compatible commands
Xin upper case, since this is how they appear
Xin nroff implementations.
X.P
XA command argument can be either ABSOLUTE or RELATIVE :
X.br
X.nf
X.sp
X .in     5       sets the indent value to 5 spaces
X .in     +5      sets the indent value to the CURRENT value+5
X .ls     -1      sets the line spacing to the current value-1
X.fi
X.P
XAlso,  all commands have a minimum and maximum value
Xthat will weed out any odd command settings (like setting
Xthe line spacing to zero, for example. It won't let you do
Xthat, but it could be changed (by recompiling
Xthe program).
X.P
XSome commands cause a "break", which is noted in the
Xtable below.  Before such a command goes into effect, the
Xcurrent line of text is put out, whether it is completely
Xfilled or not. (this is what happens at the end of a
Xparagraph, for example.)  A line beginning with spaces or a
Xtab will cause a break, and will be indented by that many
Xspaces (or tabs) regardless of the indent value at that time
X(this is a "temporary indent", which can also be set
Xexplicitly).  An all blank line also causes a break.  If you
Xfind that some lines that are indented strangely, and it's
Xnot obvious WHY, look at which commands are causing a break,
Xand which aren't. For instance:
X.sp
X.nf
X .fi
X .ti 0
X this is a line of text
X .in 8
X                                        <- blank line
X more text for the machine to play with
X.fi
X.P
XAt first glance it seems obvious that the line "this is a
Xline of text" will be indented zero spaces, but it won't -
Xit will be indented 8. The indent command does NOT cause a
Xbreak (although the .ti does) so it will not cause the line
Xto be put out before setting the indent value to 8.  Then,
Xwhen the blank line is encountered, it will cause a break -
Xand "this is a line of text" will be indented incorrectly.
XThe above example will give the following lines.
X.sp
X.fi
X.ti +5
Xthis is a line of text
X.sp
X.ti +5
Xmore text for the machine to play with
X.br
X.in
X.P
XIt is worthwhile considering placing a ".br", the
Xbreak command, before each use of ".in".
X.P
XCertain system variables are "stacked" to enable
Xreversion to earlier environments instead of "hardcoded"
Xdefaults.  For example:
X.sp
X.nf
X .ls 1
X  .
X  .
X .ls
X.sp
X.fi
XThe first command will produce single line spacing (which is
Xthe default, but which may have been set otherwise at the
Xbeginning of the manuscript).  The second command causes
Xresumption of the original line spacing (either the default
Xor whatever had been chosen previously).  Stacked variables
Xinclude: linespacing, indent column, line length,
Xtranslation flag character, page length, top and bottom
Xmargin sizes, unexpandable space character, output width,
Xand tabsize.
X.nf
X.ne 8
X.sp 4
X*********************** Table of Commands *********************
X
X Command       Break?    Default stacked Function
X -------       ------    ------- ------- ---------
X
XA. nroff-compatible commands (* denotes compatibility limitation)
X   --------------------------------------------------------------
X
X .. string       no                      string is "mere" comment
X                                         (or end of macro definition)
X
X .ad             no      initially on    turn right justification
X                                         on (use .na to turn off);
X                                         only applicable if
X                                         "filling" is also on.
X
X .bp n           yes     n =  +1         begin page numbered n
X
X .br             yes                     cause a break (this
X                                         line is not justified)
X
X .ce n           yes     n = 1           center next n lines
X
X .di name (*)    no      junk.$$$        diversion file
X                                         (see "PREPROCESSOR")
X
X .de name        no                      define (multiline)
X                                         macro ("PREPROCESSOR")
X
X .ds name string no      null string     define string replace-
X                                          ment ("PREPROCESSOR")
X
X .em                                     end macro
X                                         (see "PREPROCESSOR")
X
X .ex             no                      immediate abort back to
X                                         system
X
X .fi             yes                     start filling lines
X
X .ig string      no                      "ignore" string (see ..)
X
X .in n           no      n = 10  Yes     set indent value to n
X
X .ll n           no      n = 65  Yes     set line length (right
X                                         margin)
X
X .ls n           no      n = 1   Yes     set line spacing to n
X
X .na             no      initially on    turn right justification
X                                         off (use .ad to turn on)
X
X .ne n           no/yes  n = 2           "need" n lines; if have
X                                         them no action; else
X                                         begins new page
X
X .nf             yes                     stop filling lines
X
X .nr name n      no      n=0     No      create or modify
X                                         register variable
X                                         (see "PREPROCESSOR")
X
X .pl n           no      n = 66  Yes     sets page length to n
X
X .pm                                     print macros defined
X                                         (for debugging)
X
X .po         no      0       No      sets page offset (spaces
X                                         at left margin of every
X                                         line.
X
X .so filename    no      ignored Yes     reads named file into
X                                         input stream; cannot be
X                                         invoked from keyboard
X                                         input.
X
X .sp n           yes     n = 1           space down n lines
X
X .ta n           no      n = 8   Yes     sets value of tab space
X
X .tc c           no      ~       Yes     set translation flag
X                                         character, see .tr
X
X .ti n           yes     n = 0           set temp. indent of n
X
X .tm string                              send message to terminal
X                                         (console); like a comment
X                                         but displayed to
X                                         operator during run.
X
X
X.ne 8
XB. non-nroff-compatible commands (must be upper-case)
X   --------------------------------------------------
X
X .BJ             yes                     break with right
X                                         justification (current
X                                         line only)
X
X .DB n           no      n = 0(NO)       set debug flag 1 for
X                                         diagnostics
X
X .EF /../../../  no      blanks          even footer titling
X
X .EH /../../../  no      blanks          even header titling
X
X .FF n           no      n = 1(yes)      initially, formfeeds
X                                         are "off". Can turn
X                                         them on.  Each page
X                                         then terminated with
X                                         one formfeed.
X
X .FO /../../../  no      empty           sets both even and odd
X                                         page footers
X
X .HE /../../../  no      empty           sets both even and odd
X                                         page headers
X
X .M1             no      n = 2   Yes     set topmost margin to n
X
X .M2             no      n = 2   Yes     set 2nd top margin to n
X                                         lines
X
X .M3             no      n = 2   Yes     1st bottom margin to n
X                                         lines
X
X .M4             no      n = 2   Yes     bottom-most margin to n
X                                         lines
X
X .OF /../../../  no      empty           odd page footer title
X
X .OH /../../../  no      empty           odd page header title
X
X .SC c           no      blank   Yes     space character; the
X                                         visible character
X                                         that will be trans-
X                                         literated to unexpanded
X                                         blank.
X
X .SR                                     show registers defined
X
X .SS                                     show strings defined
X
X .ST n           no      n = 1   (yes)   stop (pause) at each page
X                                         start; initially off;
X                                         may also be enabled by
X                                         the -s option.
X
X.ne 27
X.sp 2
XHere's what the page parameters look like:
X
X        |<--------output width ------------------------>|
X
X|- po --| ( "po = page offset")
X_       _________________________________________________
X|       |       top margin(m1) - (includes header)      |
X|       |-----------------------------------------------|
X|       |               top margin 2                    |
X|       |-----------------------------------------------|
XP       |       :                               :       |
XA       |       :<-indent                       :       |
XG       |       :                               :       |
XE       |       :lots and lots of silly text and:       |
XL       |       :other garbage. Get the picture?:       |
XE       |          :This is a temp.  indentation:       |
XN       |       :                               :       |
XG       |       :               right margin -> :       |
XT       |       :                               :       |
XH       |       :                               :       |
X|       |-----------------------------------------------|
X|       |               margin 3                        |
X|       |-----------------------------------------------|
X|       |  margin 4 - (includes footer,perhaps ff)      |
X-       -------------------------------------------------
X
X.fi
XMinimum acceptable values for M1, M2, M3, and M4: if M1 is set
Xto zero, no header will be shown (even if one was declared).
XSimilarly, if M4 is set to zero, no footer will be displayed.
X.P
XTo change the default for any parameter, you must alter ro.h
Xand recompile.
X.ne 4
X.sp 2
X\fISome Notes on Input Commands\fR
X.P
X\fB".ce"\fR.
XIf you want to center lots of lines, but don't
Xwant to count them, do something like this:
X.sp
X.nf
X .ce     1000
X lots and
X lots of words to
X be centered
X .ce 0
X.sp
Xwill give the lines:
X.ce 1000
Xlots and
Xlots of words to
Xbe centered
X.ce 0
X.fi
X.sp
X.P
X\fB".ti"\fR.
XA new paragraph may be caused by using the temporary indent
Xcommand, like
X.sp
X.nf
X .ti +5
X.fi
X.sp
Xor by simply beginning the paragraph with a tab.
X.ne 4
X.sp 2
X\fIHeader and Footer Commands\fR
X.P
XA page number can be incorporated into any header or
Xfooter by putting a "#" in the title where you want the number
Xto go:
X.nf
X .he     //This is a witty header title for page #//
X.fi
XEach time this is printed at the top of a page, the current
Xpage number will be substituted for the "#".
XEach footer and header are ".in 0", even if text is
Xindented.
X.P
XHeaders and footers are in three parts.  These parts are left
Xjustified, centered, and right justifed.  Any of these three
Xparts may be left out.  One may pick the
Xheaders and footers separately for even and odd pages.  For
Xexample, one could place even and odd page numbers at the
Xbottom outside of each page by:
X.sp
X.nf
X .EF /Page #///
X .OF ///Page #/
X.fi
X.P
XAny printable character, here the '/', can be used to
Xdelimit the three strings that make up the titles, so long
Xas it is not the backslash character ('\\') and is
Xnot present in any of the three strings.
X.P
XThe program can be made to wait for the operator to
Xload single sheets of paper by the -s option and/or by the
Xcommand: .ST
X.P
XIf you want to send the output to a file, and don't want the
Xpage breaks in there set margins 1-4 to zero.
X.ne 4
X.sp 2
X\fIPrinter Control Input\fR
X.P
XAt present, ro recognizes only five sequences
Xfor printer control.  These, with their input
Xsymbols, are:
X.sp
X.nf
X    \\fR    Switch to Roman Font
X
X     \\fI    Switch to \fIItalic\fR Font
X
X    \\fB    Switch to \fBBold\fR Font
X
X    \\u    Up \uone-half\d line
X
X    \\d    Down \done-half\u line
X.fi
X.sp
XThe "Roman" (or perhaps "Regular") font turns off
Xboth Italic and Bold fonts.  The \\u and \\d
Xcommands are useful in depicting superscripts
Xand subscripts.
X.P
XFonts can also be switched using the ".ft"
Xinput command.  For example, the command
X.sp
X.ti +5
X .ft R
X.sp
Xwould set the Roman font for subsequent input.
X.ne 8
X.sp 2
X.ce
X\fIThe Preprocessor\fR
X.sp 1
X\fIString Definitions\fR
X.P
XIn the following we describe the advanced macro
Xpreprocessing features of this formatter which provide users
Xwith labor saving tools but which are probably not necessary
Xat first.  The beginning user may be able to achieve most
Xgoals without the "preprocessing", but by using an editor
Xmore then otherwise.  The more advanced user will begin to
Xappreciate these features more.
X.P
XFor example, in:
X.sp
XToday, \\*(da, is special.
X.sp
Xthe block, "\\*(da", would be replaced as this sentence is
Xbeing input.  If a prior string definition of the form:
X
X .ds da "January 1, 1983"
X.ds da "January 1, 1983"
X
Xhad been processed previously then the example, after text
Xsubstitution, would become:
X.sp
X.ti +5
XToday, \*(da, is special.
X.P
XThe string definition command, .ds, expects two arguments:
Xa name of one or two characters (case is significant),
Xand then either a single word (no whitespace) or
Xa string delimited by double quotation marks ("...").
XA single-letter string name is expanded on output
Xwhen the letter is preceded by "\\*".
XFor example, one could define a string N using
X.sp
X.ti +5
X .ds N "Alfred E. Newman"
X.sp
Xand then whenever the sequence \\*N appears
Xin the input text, the string "\*N" would
Xbe output.
XA two-letter string name is expanded on output
Xwhen it is preceded by "\\*(".
XThus, in the example above, the string "da"
Xis defined, and output with "\\*(da",
Xyielding "\*(da".  Did it work?
X.ne 4
X.sp 2
X\fINumber Registers\fR
X.P
XSimilar to string definitions are number register
Xvariables, which are created and modified with the \fB.nr\fR
Xcommand.  Variables are useful for enumeration such as
Xequation numbering:
X.sp
X.ti +5
X .nr eq 1
X.nr eq 1
X.sp
Xwould create a register named "eq" with the current value
Xof 1.  The the text might use it with, say:
X.sp
X.ti +5
Xx = y+1          \\n(eq
X.sp
Xwhich would be converted on input into:
X.sp
X.ti +5
Xx = y+1          \n(eq
X.sp
XA subsequent instruction:
X.sp
X.ti +5
X .nr eq +1
X.nr eq +1
X.sp
Xwould take the current value of "eq" and increase it by 1
X(so that it would now be 2 in our example:
X.sp
X.ti +5
Xa = b+c          \\n(eq
X.sp
Xwould become:
X.sp
X.ti +5
Xa = b+c          \n(eq
X.P
XNumber Register values are expanded on output
Xin a manner similar to string variables, except
Xthat "n" (must be lower-case) is used in place
Xof "*".  Thus the register variable "P" would
Xbe expanded by "\\nP", and the register "Pi"
Xwould be expanded by "\\n(Pi", just as "eq"
Xis expanded by "\\n(eq" above.
X.P
XThere is a special, reserved insertion, \#\, which
Xwill provide the current page number.  It should prove
Xuseful in setting up tables of contents (see "diversions",
Xbelow).
X.P
XSince we have defined a special register name, '#',
Xwe should comment on what happens if you create a register
Xinstruction with that name, such as:
X.sp
X.ti +5
X .nr # +1
X.sp
XYou will be changing the value of the page number of the
XFOLLOWING pages.  This is useful for leaving gaps in the
Xpagination for later inclusion of full page illustrations.
XThis feature is demonstrated (tested) in the file, MARGINS.
XI wish to thank Henry Harpending for suggesting this.
X.P
X\"ro" includes some predefined number registers
Xthat are available to users.  These are:
X.sp
X.nf
X    dy    current day of the month
X    mo    current month as integer (1-12)
X    yr    current year -1900
X.fi
X.sp
XThus, a user could say,
X\"Today's date is \\n(dy/\\n(mo/\\n(yr",
Xand this would be ouput as
X\"Today's date is \n(dy/\n(mo/\n(yr".
X.ne 4
X.sp 2
X\fIUsing Backslashes\fR
X.P
XThe backslash character has other properties.
XIt can be placed into the input by repeating
Xit, namely, "\\\\" becomes "\\".  (useful for delaying
Xsubstitutions).  For example, defining:
X.sp
X.ti +5
X .ds EN "\\n(eq"
X.ds EN "\\n(eq"
X.sp
Xwill identify "EN" with "\\n(eq" and so our equation
Xexample above could have been:
X.sp
X.ti +5
Xa = b + c          \*(EN
X.sp
XDelaying the evaluation of "eq" until EN is invoked
X(instead of when it was defined) means that the proper
Xnumbering of equations will occur instead of wrongly
Xsupplying the value of "eq" from the time that EN was
Xfirst created.
XUtilizing this technique,
Xthe "tmac.m" package defines a macro for the
Xcurrent date, which is:
X.sp
X.ti +5
X .ds DT "19\\\\n(yr/\\\\n(mo/\\\\n(dy"
X.ds DT "19\\n(yr/\\n(mo/\\n(dy"
X.sp
XThis would be expanded using "\\*(DT",
Xwhich would produce "\*(DT" (did it work?).
X.ne 4
X.sp 2
X\fIMacro Definitions\fR
X.P
X"Macro" definitions are used when we wish to
Xidentify several lines with an insertion.  Such definitions
Xare created with the .de ["define macro"] and completed with
Xthe .. ["end macro"] commands.  For example, we might wish
Xto use the following sequence over and over again at the
Xstart of paragraphs:
X.sp
X.nf
X .sp 1
X .ne 2
X .ti +5
X.fi
X.P
Xto separate the paragraphs by blank lines, keep them from
Xstarting excessively close to the bottom of the page, and
Xindenting them 5 spaces to the right of the current left
Xmargin.
X.nf
X.sp
X .de P
X .sp 1
X .ne 2
X .ti +5
X ..
X.fi
X.P
XSubsequently, whenever we wished to start a paragraph we
Xwould create a command line:
X.sp
X.ti +5
X .P
X.sp
Xinstead of more tediously creating every time the three
Xcommands we mentioned above.
X.P
XThe names of all macros, strings, and number
Xregisters are "case sensitive".  That is to say that
Xcapitalization and/or lower case are distinguished and, say,
X.sp
X.ti +5
X .p
X.sp
XWould not be recognized as the same as the sample macro we
Xjust defined.
XThe macro is read until a line beginning with ".em" (end macro)
Xor simply ".." is reached.
X.P
XA macro command may contain parameters(s). For example
X.sp
X.nf
X .de He
X $0
X ..
X.de He
X$0
X..
X.fi
X.sp
Xdefines a simple macro for printing a heading.
XWhen the line ".He Heading"
Xappears at the beginning of a line, the word "Heading"
Xwill be printed, i.e.:
X.sp
X.He Heading
X.P
XThe maximum number of parameters for a macro is 10 ($0-$9).
XThe parameter(s) must be on the same line of the macro call.
XThe parameters are separate by a non-alphanumeric character
Xexcept '+' and '-' which
Xappear as the first character of the parameter line. If the
Xfirst character is a alphanumeric character, then white space
Xwill be assumed as the delimiter. An example can be found
Xabove. If the require parameter(s) is/are not defined by the
Xmacro call, then the parameter(s) will be treated as null
Xstring.
X.ne 4
X.sp 2
X\fIDiversions\fR
X.P
XThere is another object formed and used somewhat
Xlike a macro;  it is called a "diversion (file)" and is
Xuseful for making lists such as references [notes] and
Xtables of contents.  A diversion is created or continued
Xwith the command: \fB.di\fR [diversion].
XIt is ended with the same command
X(the command to begin the diversion should
Xhave a one- or two-letter name argument;
Xthe command to end it should have no argument.
XA diversion can grow to be quite large and is, in "ro", a
Xdisk file.  To "regurgitate" the diversion file, its
Xname must be entered as a command at the beginning of a line.
X.P
XFor example, the "tmac.m" macros define .FS
X(start footnote -- actually and endnote)
Xas including the command ".di no".
XInternally, at this point, ro creates a disk file
Xnamed "no_ro.div" and begins placing all input
Xin this file.
XThe macro ".FE" (footnote end) includes the command ".di".
XAt this point the diversion to "no_ro.div" is
Xceased, and input is again read as normal.
XFor each .FS - .FE pair, this sequence is
Xrepeated, so that the diversion file collects
Xall the footnotes.
XFinally, the macro ".PN" (printout notes)
Xincludes the command ".no" which ro
Xrecognizes as the signal to send out all
Xthe material collected in the diversion file.
X\".PN" is placed last in the text file, so that
Xthe notes follow after the text.
X.ne 8
X.sp 2
X.ce
X\fIUsing the tmac.m Macro Package\fR
X.P
XThe file "tmac.m" included with this distribution
Xdefines some macros for use in processing documents.
XThese are roughly equivalent to the nroff "-mm" macros
Xof similar names.
XYou can very easily customize this package and add
Xto it for your own uses.
X.P
X\fIParagraph Control\fR.
XUsing the tmac.m macros, the command
X.sp
X.ti +5
X .P
X.sp
Xis used to begin a paragraph.
XThere are two number registers associated with
Xthis command:
X.sp
X.ti +5
X.nf
X     Ps        paragraph spacing, and
X.ti +5
X     Pi        paragraph indent.
X.fi
X.sp
XEach time .P is called, "Ps" lines are skipped, and a
Xtemporary indent of "Pi" characters is set.
X.P
X\fIThe Date String\fR.
XWith the tmac.m package, the current date
Xis stored in the string "DT" and can
Xtherefore be output at any point with \\*(DT.
XThis yields "\*(DT", and is used in the page
Xheader for this documentation (see at the top of this page).
X.P
X\fIEndnote Control\fR.
XAlthough ro does not currently support footnotes
X(because it does not implement a withholding trap),
Xthere are three macros and a string definition to
Xsupport endnotes.  These are:
X.sp
X.nf
X    \\*F    prints current note number, superscript
X    .FS    starts text of note
X    .FE    ends text of note
X    .PN    prints out all notes collected
X.fi
X.sp
XThe command ".FS" begins diversion to a separate file,
Xso you must be careful to end the text of the note with
Xthe ".FE" command.  Also, be sure to include the ".PN"
Xcommand at the point where you want the notes to be
Xprinted out (normally at the very end of the file).
X.P
X\fIFont Control\fR.
XThe tmac.m package contains three macros
Xconsistent with the "-mm" package for switching
Xfonts.  These are:
X.sp
X.nf
X    .R    switch to Roman (regular) font
X    .I    switch to Italic font
X    .B    switch to Bold font
X.fi
X.P
X\fIPage Header and Footer Control\fR.
XThe tmac.m package defines two macros
Xconsistent with "-mm" which reset page
Xheaders and footers:
X.sp
X.nf
X    .PH    page header
X    .PF    page footer
X.fi
X.sp
XNote that the arguments to these must be three-part titles
Xenclosed in double quotation marks, e.g.,
X.sp
X.fi
X    .PH "'left'center'right'"
X.sp
XThis differs from the usage of the built-in .HE
Xand .FO commands.
X.P
X\fIText and Block Macros\fR.
XFinally, the tmac.m package defines macros
Xnot found in "-mm" that I have found helpful
Xin writing papers.  These are:
X.sp
X.nf
X    .TA    begin double-spaced text segment
X    .TZ    end double-spaced text segment
X    .BA    begin single-spaced indented block
X    .BZ    end single-spaced indented block
X.fi
X.ne 8
X.sp 2
X.ce
X\fIro Output and Post-Processor Development\fR
X.P
XThe five sequences to control the printer are
Xsen, on output, as the ESCAPE character (0x1b hex,
X27 decimal) followed by a single ASCII character.
XThese sequences are:
X.sp
X.nf
X    ESCAPE    'R'    Set Roman Font
X
X    ESCAPE     'I'    Set Italic Font
X
X    ESCAPE  'B'    Set Bold Font
X
X    ESCAPE    'u'    Up One-Half Line
X
X    ESCAPE    'd'    Down One-Half Line
X.fi
X.sp
XAn ro postprocessor should intercept any
XESCAPE character, then determine based
Xon the next character following it what
Xcodes to send out.
X.P
XAs an example, the folowing is the entire
Xtext of the "termnx10" postprocessor.
XIt should be relatively easy to alter
Xthe escape code sequences here to suit any
Xprinter.
X\fBPlease note\fR that in the version below
Xwe have had to doule each backslash character
Xso that it would print correctly when output
Xby ro.  If you want to cut this program
Xout of ro.doc to compile it, you'll need
Xto convert each double backslash to a single one.
X.sp
X.nf
X
X#include "stdio.h"
X#include "term.h"
X
Xchar progname[] = "termnx10";
X
Xmain()
X    {
X    register int c;
X
X    while( !feof( stdin ))
X        {
X        c = getchar();
X        switch( c )
X            {
X            case ESCAPE:
X                getpc();
X                break;
X            case EOF:
X                break;
X            default:
X                putchar( c );
X                break;
X            }
X        }
X    }
X
Xgetpc()
X    {
X    register int c;
X
X    c = getchar();
X    switch( c )
X        {
X        case ROMAN:
X            roman();
X            break;
X        case ITALIC:
X            italic();
X            break;
X        case BOLD:
X            bold();
X            break;
X        case HALFUP:
X            halfup();
X            break;
X        case HALFDOWN:
X            halfdown();
X            break;
X        default:
X            fprintf( stderr, "%s:  unrecognized output escape sequence ESC-0x%x \n", progname, c );
X            break;
X        }
X    }
X
Xroman()
X    {
X    printf( "\\0335\\033H" );
X    }
X
Xitalic()
X    {
X    printf( "\\0334" );
X    }
X
Xbold()
X    {
X    printf( "\\033G" );
X    }
X
Xhalfup()
X    {
X    printf( "\\033j\\022" );
X    }
X
Xhalfdown()
X    {
X    printf( "\033J\022" );
X    }
X
X--------------------------------------------
X
XHere's the included "term.h" file:
X
X--------------------------------------------
X
X#define    ESCAPE        0x1b
X
X/**    Single-character printer code designations ***/
X
X#define    ROMAN        'R'    /* Restore "roman" or "regular" font */
X                /* Should turn off Bold and Italic */
X#define    ITALIC        'I'    /* Switch to italics or underline */
X#define    BOLD        'B'    /* Switch to bold */
X#define    HALFUP        'u'    /* Half-line up */
X#define    HALFDOWN    'd'    /* Half-line down */
X
X.fi
X
________This_Is_The_END________
if test `wc -l < ro.doc` -ne 1254; then
    echo 'shar: ro.doc was damaged during transit (should have been 1254 bytes)'
fi
fi        ; : end of overwriting check
echo 'x - ro.qrf'
if test -f ro.qrf; then echo 'shar: not overwriting ro.qrf'; else
sed 's/^X//' << '________This_Is_The_END________' > ro.qrf
X*********************** Table of Commands *********************
X
X Command       Break?    Default stacked Function
X -------       ------    ------- ------- ---------
X
XA. nroff-compatible commands (* denotes compatibility limitation)
X   --------------------------------------------------------------
X
X .. string       no                      string is "mere" comment
X                                         (or end of macro definition)
X
X .ad             no      initially on    turn right justification
X                                         on (use .na to turn off);
X                                         only applicable if
X                                         "filling" is also on.
X
X .bp n           yes     n =  +1         begin page numbered n
X
X .br             yes                     cause a break (this
X                                         line is not justified)
X
X .ce n           yes     n = 1           center next n lines
X
X .di name (*)    no      JUNK.$$$        diversion file
X                                         (see "PREPROCESSOR")
X
X .de name        no                      define (multiline)
X                                         macro ("PREPROCESSOR")
X
X .ds /../../../  no      null string     define string replace-
X                                          ment ("PREPROCESSOR")
X
X .ed (*)         no                      end diversion
X                                         (see "PREPROCESSOR")
X
X .em                                     end macro
X                                         (see "PREPROCESSOR")
X
X .ex             no                      immediate abort back to
X                                         system
X
X .fi             yes                     start filling lines
X
X .ig string      no                      "ignore" string(see ..)
X
X .in n           no      n = 10  Yes     set indent value to n
X
X .ll n           no      n = 70  Yes     sets line length (right
X                                         margin) to n
X
X .ls n           no      n = 1   Yes     set line spacing to n
X
X .na             no      initially on    turn right justification
X                                         off (use .ad to turn on)
X
X .ne n           no/yes  n = 2           "need" n lines; if have
X                                         them no action; else
X                                         begins new page
X
X .nf             yes                     stop filling lines
X
X .nr name n      no      n=0     No      create or modify
X                                         register variable
X                                         (see "PREPROCESSOR")
X
X .pl n           no      n = 66  Yes     sets page length to n
X
X .pm             no                      prints currently defined
X                                         macros
X
X .so filename    no      ignored Yes     reads named file into
X                                         input stream; cannot be
X                                         invoked from keyboard
X                                         input.
X
X .sp n           yes     n = 1           space down n lines
X
X .ta n           no      n = 8   Yes     sets value of tab space
X
X .tc c           no      ~       Yes     set translation flag
X                                         character, see .tr
X
X .ti n           yes     n = 0           set temp. indent of n
X
X .tm string                              send message to terminal
X                                         (console); like a comment
X                                         but displayed to
X                                         operator during run.
X
X
XB. non-nroff-compatible commands (must be upper-case)
X   --------------------------------------------------
X
X .BJ             yes                     break with right
X                                         justification (current
X                                         line only)
X
X .CF c           no      c = '^' Yes     to be used as a prefix
X                                         to a character that
X                                         controls print func-
X                                         tions such as ^+,^-
X                                         might be used to
X                                         bracket superscripts,
X                                         somewhat like
X                                         WORDSTAR(TM).
X
X .DB n           no      n = 0(NO)       set debug flag 1 for
X                                         diagnostics
X
X .EF /../../../  no      blanks          even footer titling
X
X .EH /../../../  no      blanks          even header titling
X
X .FF n           no      n = 1(yes)      initially, formfeeds
X                                         are "off". Can turn
X                                         them on.  Each page
X                                         then terminated with
X                                         one formfeed.
X
X .FO /../../../  no      empty           sets both even and odd
X                                         page footers
X
X .HE /../../../  no      empty           sets both even and odd
X                                         page headers
X
X .IC c           no      c = '\' Yes?    to specify the char-
X                                         acter used for macro
X                                         preprocessing to denote
X                                         the token that follows.
X
X .M1             no      n = 2   Yes     set topmost margin to n
X
X .M2             no      n = 2   Yes     set 2nd top margin to n
X                                         lines
X
X .M3             no      n = 2   Yes     1st bottom margin to n
X                                         lines
X
X .M4             no      n = 2   Yes     bottom-most margin to n
X                                         lines
X
X .OF /../../../  no      empty           odd page footer title
X
X .OH /../../../  no      empty           odd page header title
X
X .OW             no      n = 80          sets output width for
X                                         header and footer title
X
X .SC c           no      blank   Yes     space character; the
X                                         visible character
X                                         that will be trans-
X                                         literated to unexpanded
X                                         blank.
X
X .ST n           no      n=1(yes)        stop(pause)at each page
X                                         start; initially off;
X                                         may also be enabled by
X                                         the -s option.
X
X  -------------------------------------------------------------
X
________This_Is_The_END________
if test `wc -l < ro.qrf` -ne 161; then
    echo 'shar: ro.qrf was damaged during transit (should have been 161 bytes)'
fi
fi        ; : end of overwriting check
echo 'x - tmac.m'
if test -f tmac.m; then echo 'shar: not overwriting tmac.m'; else
sed 's/^X//' << '________This_Is_The_END________' > tmac.m
X..    \"===================================================
X..    \"
X..    \"    tmac.m
X..    \"
X..    \"    text macros for the "ro" text formatter
X..    \"    by Ted A. Campbell
X..    \"
X..    \"===================================================
X..    \"
X..    \"===================================================
X..    \"    Reset top and bottom margin registers
X.M1 6
X.M2 2
X.M3 2
X.M4 6
X.ll 65
X.po 8
X..    \"===================================================
X..    \"    Number register "P" -- current page number
X.nr P 0
X..    \"===================================================
X..    \"    String "DT" -- current date
X.ds DT "19\\n(yr/\\n(mo/\\n(dy"
X..    \"===================================================
X..    \"    Macro "PH" -- page header
X.de PH
X.nr P +1
X.HE $0
X..
X..    \"===================================================
X..    \"    Macro "PF" -- page footer
X.de PF
X.FO $0
X..
X..    \"===================================================
X..    \"    Number register "Ps" -- paragraph spacing
X.nr Ps 1
X..    \"===================================================
X..    \"    Number register "Pi" -- paragraph indent
X.nr Pi 0
X..    \"===================================================
X..    \"    Macro "P" -- begin paragraph
X.de P
X.sp \\n(Ps
X.ne 2
X.ti \\n(Pi
X..
X..    \"===================================================
X..    \"    Macro "R" -- set Roman font
X.de R
X.ft R
X..
X..    \"===================================================
X..    \"    Macro "I" -- set Italic font
X.de I
X.ft I
X..
X..    \"===================================================
X..    \"    Macro "B" -- set Bold font
X.de B
X.ft B
X..
X..    \"===================================================
X..    \"    Number register "Fn" -- current footnote number
X.nr Fn 1
X..    \"===================================================
X..    \"    String "F" -- print current footnote number superscript
X.ds F "\\u\\n(Fn\\d"
X..    \"===================================================
X..    \"    Macro "FS" -- start footnote
X.de FS
X.di no
X.sp
X.ti +5
X\\u\\n(Fn\\d
X..
X..    \"===================================================
X..    \"    Macro "FE" -- end footnote
X.de FE
X.di
X.nr Fn +1
X..
X..    \"===================================================
X..    \"    Macro "PN" -- print footnotes
X.de PN
X.sp 2
X.ls 1
X.na
X.ne 6
X.ce
XNOTES
X.sp 1
X.no
X..
X..    \"===================================================
X..    \"    Macro "TA" -- text segment beginning
X.de TA
X.ls 2
X.nr Pi 5
X.nr Ps 0
X.sp
X..
X..    \"===================================================
X..    \"    Macro "TZ" -- text segment ending
X.de TZ
X.ls 1
X.nr Ps 1
X..
X..    \"===================================================
X..    \"    Macro "BA" -- block segment beginnning
X.de BA
X.ls 1
X.nr Pi 0
X.nr Ps 1
X.in +5
X.ll -5
X.sp
X..
X..    \"===================================================
X..    \"    Macro "BZ" -- block segment ending
X.de BZ
X.in -5
X.ll +5
X..
X..    \"===================================================
X..    \"
X..    \"    End of tmac.m
X..    \"
X..    \"===================================================
________This_Is_The_END________
if test `wc -l < tmac.m` -ne 129; then
    echo 'shar: tmac.m was damaged during transit (should have been 129 bytes)'
fi
fi        ; : end of overwriting check
echo 'x - test.doc'
if test -f test.doc; then echo 'shar: not overwriting test.doc'; else
sed 's/^X//' << '________This_Is_The_END________' > test.doc
X.so tmac.m
X.ls 2
X.nr Pi 5
X.ce
X\fBA Test Document\fR
X.P
XThis is a test document that has been written
Xutilizing MicroEMACS 3.9e, and is intended
Xto be formatted with the "ro" text formatter.
X.P
XThis should be \usuper\dscript,
Xand this should be \fIitalicized\fR,
Xand this should be \fBbold\fR.
XHow did it all come out?
X.P
XThis sentence should be followed by
Xthe first end note.\*F
X.FS
XThis is the text of the first end note.
X.FE
XThis sentence should be followed
Xby the second end note.\*F
X.FS
XThis is the text of the second end note.
X.FE
XThis sentence should be followed by
Xthe third end note.\*F
X.FS
XThis is the third end note.
X.FE
X.sp
X.PN
X
________This_Is_The_END________
if test `wc -l < test.doc` -ne 33; then
    echo 'shar: test.doc was damaged during transit (should have been 33 bytes)'
fi
fi        ; : end of overwriting check
exit 0