CP/M/CPM_CDROM.iso/enterprs/cpm/utils/f/pwtour.arc/ROFFGUID.DOC

Text File | 1993-03-27 | 12.5 KB | 465 lines

.                            ROFFTOUR




1. Introduction

This  document  describes  additional functionality added to ROFF to
support  the  TOUR  (c)  Program.  No  changes   to   the   existing
functionality of ROFF have been made.

The  changes  made  support  decimalization.  Decimalization  is the
automatic numbering of heading and subheading labels in a document.

Some formatting control for headings has also been included.


2. Extension to the Roff program



2.1 Specifying heading labels

You may label sections of  a  document  by  using  a  heading  label
directive.  Heading labels are entered by using the new .hl command.
The command which labeled this section was

.hl Specifying heading labels

When the document  is  run-off'ed  ROFF  will  automatically  number
heading  labels in sequence. This feature allows you to move section
of document around  without  worrying  about  renumbering  sections.
TOUR (c) is ideal for this purpose.


2.2 Specifying sub-headings

If  you  are working on a more complicated document, you may wish to
place  numbered  headings  within  headings.  Using  this   feature,
sub-headings  are  also automatically numbered. The same .hl command
is  used  to  specify  sub-headings.  Sub-headings,   however,   are
bracketed by "set level" commands. The set level commands are

.sl +

to begin a series of sub-headings and

.sl -

to  end a series of sub-headings. Headings may be nested 8 deep with
the new version of ROFF. For example

.hl Top Level Label One
.sl +
.hl One-One
.hl One-Two
.sl -
.hl Top Level Label Two
.sl +
.hl Two-one
.sl +


.                               1


.                            ROFFTOUR


.hl Two-one-one
.hl Two-one-two
.sl -
.hl Two-two
.sl -
.hl Top Level Label Three

Any number of lines of text may follow a .hl command. Text does  not
normally  follow a .sl + command, but it may follow a .sl - command.
(It would function as a section summary.)


2.3 Page formating for heading labels

Five additional commands help control  the  look  of  your  document
when  you  use  heading  labels. In the (lazy) spirit of ROFF's ".M"
commands, five ".D" commands have been added. They are

.d1 <number of lines to skip before a heading label is printed>
.d2 <additional skip before first sub-heading>
.d3 <number of lines to skip after a heading label is printed>
.d4 <number of spaces to indent sub-headings and text>
.d5 <additional indent for text after heading label>

Note that .d4 and .d5 can be used to create "hanging titles".

                              WARNING

The indent feature makes internal use of ROFF's .in command. If  you
use  the  .in  command within your document, you should take care to
use it in relative mode (with "+"'s and "-"'s) rather than  absolute
mode.


2.4 Periods in the first column

By  placing  two  periods  in  a row, ROFF now allows you to place a
period in the first column. The first period is  stripped  by  ROFF,
all successive periods will be output. For example,

..I want a period in the first column

would appear after processing
.I want a period in the first column


3. Roff Command Reference

May 7, 1981

                        ROFF

        This version of ROFF, based on the formatter  in  Kernighan
and Plauger's book SOFTWARE TOOLS, is written in BDS C, and employs
the  directed  i/o functions that go along with that package. Well,
half of the directed I/O anyway - it doesn't use  redirected  input
because  I wanted to be able to format more than one file at a run.
Please ignore any "odd" comments to myself in ROFF1.C and  ROFF2.C;


.                               2


.                            ROFFTOUR


I tried to find them all but there may be a few extra silly remarks
around.

        For more details on the directed I/O (NDIO in our version)
see NDIO.C


Sample calls:

A>roff filename1 filename2 filename3 +}

        this would send the formatted version of these three files
        to the console and to the printer


A>roff filename1 +}]>filename1

        this would format filename1 and send it to the printer,
        console, robot-typewriter, and back to filename1.



For more details on using the directed I/O, see NDIO.C



        Using  ROFF,  you  can  make nice printouts of a file, with as
little  or as much help from the program as you want, depending on the
commands.  There  are  default  values  for  all parameters, so if you
don't put any commands in at all, your file will come out with filled,
right-justified  lines.   The  default line-length is  80  characters;
the  default  page-length  is  66 lines per page. "Filled lines" means
that  as many input words as possible are packed onto a line before it
is   printed;   "non-filled"   lines  go  through  the  formatter  w/o
rearrangement.  "Right-justified"  simply  means that spaces are added
between words to make all the right margins line up nicely.
        To  set  a  parameter, use the appropriate commands below. All
commands  have the form of a period followed by two letters. A command
line  should  have nothing on it but the command and its arguments (if
any); any text would be lost.

        A command argument can be either ABSOLUTE or RELATIVE :

.in    5    sets the indent value to 5 spaces

.in    +5    sets the indent value to the CURRENT value plus 5

.ls     -1    sets the line spacing value to the current value
                        minus one

        Also,  all commands have a minimum and maximum value that will
weed out any odd command settings (like setting the line spacing to
zero, for example. It won't let you do that, but it could be changed
if you REALLY have a burning desire to do so).

        Some  commands  cause  a  "break", which is noted in the table
below.  Before  such  a  command goes into effect, the current line of
text  is  put  out,  whether  it is completely filled or not. (this is


.                               3


.                            ROFFTOUR


what  happens  at  the  end  of  a  paragraph,  for  example.)  A line
beginning  with  spaces  or  a  tab  will  cause  a break, and will be
indented  by that many spaces (or tabs) regardless of the indent value
at  that  time  (this  is  a "temporary indent", which can also be set
explicitly).  An all blank line also causes a break.  If you find that
seem  to  have  some  lines that are indented strangely,  and it's not
obvious WHY,  look  at which commands  are causing a break,  and which
aren't. For instance:

.fi
.ti 0
this is a line of text
.in 8
                                        <- blank line
more text for the machine to play with


At first glance it seems obvious that the line "this is a line of text"
will   be indented zero spaces,  but it won't - it will be indented  8.
The indent  command  does  NOT cause a break   (although the .ti  does)
so it will not cause the line to  be put out before  setting the indent
value to 8.  Then,  when the  blank line is encountered,  it will cause
a break - and "this is a line of text" will be indented incorrectly.


*********************** Table of Commands *****************************

Command          Break?    Default        Function
-------       ------    -------         ---------
.bp n        yes    n =  +1        begin page numbered n

.br        yes            cause a break

.ce n        yes    n = 1        center next n lines

.fi        yes            start filling lines

.fo string    no    empty        sets footer to string

.he string    no    empty        sets header to string

.in n        no    n = 0        sets indent value to n

.ls n        no    n = 1        sets line spacing to n

.m1        no    n = 2        sets topmost margin to n

.m2        no    n = 2        sets 2nd top margin to n lines

.m3        no     n = 2        1st bottom margin to n lines

.m4        no    n = 2        bottom-most margin to n lines

.nf        yes            stop filling lines

.pl n        no     n = 66        sets page length to n

.rm n        no    n = 80        sets right margin to n


.                               4


.                            ROFFTOUR



.sp n        yes    n = 1        space down n lines

.ti n        yes    n = 0        sets temporary indent of n

.ul n        no    n = 1        underline next n lines

----------------------------------------------------------------------



Here's what the page parameters look like:

_    _________________________________________________
|    |    top margin - (includes header)        |
|    |-----------------------------------------------|
|    |        top margin 2            |
|    |-----------------------------------------------|
P    |    :                :    |
A    |    :<-indent            :    |
G    |    :                :    |
E    |    :lots and lots of silly text and:    |
L    |    :other garbage. Get the picture?:    |
E    |       :This is a temp.  indentation:    |
N    |    :                :    |
G    |    :        right margin -> :    |
T    |    :                :    |
H    |    :                :    |
|    |-----------------------------------------------|
|    |        margin 3            |
|    |-----------------------------------------------|
|    |    margin 4 - (includes footer)        |
-    -------------------------------------------------


To change the default for any parameter, simply alter ROFFGLOB
recompile ROFF1.c and ROFF2.c, and re-clink them with NDIO.CRL
(you can use DIO.CRL, but it doesn't have all the features of
NDIO )



************************************************************
A Few Extra Comments on Some of the Commands:
************************************************************

                If you want to center lots of lines, but don't
        want to count them, do something like this:

.ce    1000
lots and
lots of words to
be centered
.ce 0

        --------------------------------------

        To underline a few words on a line:


.                               5


.                            ROFFTOUR



.fi
.ul
Some
of the words in
.ul
this
sentence are
.ul
underlined

        WOULD PRODUCE:

Some of the words in this sentence are underlined.
----                 ----              -----------

(obviously you don't have to turn the fill on and off if it's
 already on )

        ------------------------------------

A new paragrah may be caused by using the temporary indent
command, like

.ti +5

or by simply beginning the paragraph with a tab, as you would if
you were just typing.

        ------------------------------------

Headers and Footers.

        A page number can be incorporated into any header or
footer by putting a "#" in the title where you want the number
to go:

.he    This is a witty header title for page #

Each time this is printed at the top of a page, the current
page number will be substituted for the "#".

        ------------------------------------
If you want to send the output to a file, and don't want the page
breaks in there ( that's what I did for this ) set margins 1-4 to
zero.


4. I/O redirection

 6 MAY 81 :: NDIOC.PAK distributed with ROFF.COM
25 Jan 85 :: Edited to form DIO.DOC by Ed Taychert

        To activate redirection: Four special arguments may be given
        on the command line to the generated COM file...

                >foo    causes "putchar" to place characters into the file
                        named "foo" instead of to the console.


.                               6


.                            ROFFTOUR



                +foo    like >foo except that the characters are ALSO sent
                        to the console.

                <foo    causes "getchar" to return characters from the file
                        named "foo" instead of from the keyboard.

                )    send to CPM list device

                }    send to printer

                ]    send to robot-typewriter

         (Note that there must never be any spaces between >,+,< or | and the
          corresponding filename.)

        You can send the output to more than one thing at once, like so:
                A>ROFFTOUR infile +)}]>outfile


5. Use and Limitations

The  extensions  made  to  ROFF are paterned after DSR, a registered
trademark of Digital Equipment Corporation. DSR is one of  Digital's
runoff   programs.   ROFFTOUR   supports  only  a  subset  of  DSR's
decimalization commands. In the future, ROFFTOUR  will  be  enhanced
to   recognise  more  of  the  DSR  commands.  To  guarantee  upward
compatability with furture versions of ROFFTOUR, do not use  numbers
as the first charaters of a heading label. For example:

.hl 4 Things to Remember

will cause future problems, while

.hl Four Things to Remember

will always work.























.                               7

    }    send to printer

                ]    send to robo