.ma 1;.br;.tp 5;.sp 1;#$;.br;.sp 1
.ma 2;.TP 10;.SP 2 ;$;.SP 1
.ma 3;.SP 2;.TP 4;$;.SP 1
.nc 1
.he RUNOFF User Manual|Page @-#
.fo Vitomir  Smolej|MPI - Stuttgart
.pl 60
.rm 79
.ce 1
RUNOFF
.sp 
.ce 2
REVISION DATE: 14/11/82
PROGRAM VERSION : V01
.sp 4
 Notice: This document describes a program which can be run on
any system supporting CP/M software. It was written by Vitomir
Smolej during his stay at MPI, Stuttgart. First a disclaimer: the
author is not responsible for any damage caused directly or indirectly
by use of this program.  This document is, however, thought to be an 
accurate description of what is going on inside the program.

.ch INTRODUCTION
.fo
 RUNOFF (rno) is a program which can
facilitate the preparation of typed or printed material,
such as memos, manuals, PhD theses etc. The user prepares
his or her material on regular computer terminal with
the help of an appropriate editor, for instance WordMaster. 
The user includes in this stored text not only
textual material itself, but also formatting commands .
RUNOFF then takes the file and reproduces it in a definitely
more pleasant form:  either in a form of another file or
directly on the printer attached to the system. The
program performs formatting commands  as directed, and
will also do line justification, pagination, titling etc.
as desired.
 
 The principal benefit of such a program is that files prepared
for use with it may be easily edited and corrected. Small or large
amounts of material may be added or deleted, and the unchanged 
material
need not to be retyped. After a set of changes, the program can be
called to produce a new copy which is again properly paged and
formatted. Documentation or work report may thus be updated
as neccessary without requiring extensive retyping.

.ch  OPERATING PROCEDURES
.hl 2 Initiating RUNOFF
 RUNOFF can be started in several ways. The general format of the
system  command looks like:
.nf
# 
	A>rno<cr>
	rno>[ file specifications by the user ]
	rno> ................
	rno>^C
.fi
.hl 2 rno Command String
 Thinking about RUNOFF as a filter, one must specify where the
input comes from and where the resulting material is to go. The syntax of
CP/M compilers and PIP, respectively, has been adopted. A standard command 
string thus has one of the following forms:
.tp 5
.sl
.le outfile=infile[,infile1,infile2....]
.le =infile[,infile1,infile2....]
.le infile[,infile1,infile2....]
.el
where infile and outfile stick to syntactical rules for file names under CP/M
(see further down for description of file names under CP/M). We can
specify as many input files as we wish; they will be concatenated into a single
output. Thus it is fairly easy to concatenate written material which
was produced at different occasions or simultanously in a team.
 Most of the time the last form of the command string is used.
In this case the text in file
infile is written to the terminal screen (and to the printer at the same
time if #^P has been pressed). No output is produced on disk units.
The second form produces an output file of the same name as infile.
They differ, however, in the file type
(see further down, if you are not familiar with the way files can
be specified under CP/M).
The third form is general and produces outfile out of infile and
files infile1,infile2..., if specified.
#
File Specifications:
.br
A file has the following general form under CP/M 
.nf
#
		dev:filename.typ
#
.fi
where dev stands for the disk unit where the file is to be found (for
instance B),
filename (1-8 characters) is the name of the file, and typ (1-3 characters)
is the type of the file. Heavily used programs
usually default to appropriate standard type (like .FOR for 
fortran source file), so the typical user will not have to
specify it. It the case of RUNOFF the following defaults have
been chosen:
.nf
#
 	 	dev		typ
 	in:     A		RNO
 	out:	A		DOC
#
.fi
Furthermore, lowercase or uppercase is irrelevant. Thus the following
file specifications amount to the same thing:
.nf
#
input:		A:MYTEXT.RNO	A:MYTEXT	mytext
output:		a:MYTEXT.doc	A:mytext.DOC	mytext
#
.fi
In all three cases, the system uses A:MYTEXT.RNO as input and
A:MYTEXT.DOC as output file.
 Now we can also discuss a little bit more the second form of the command.
It produces a file on the same device and of the same
name as the (first) input file. Only the extension will
be changed to DOC. Thus :
.nf
#
	B:mytext=B:mytext,ch1,ch2
#
.fi
can be written in a more simple way as:
.nf
#
	=B:mytext,ch1,ch2
#
.fi

.ch SOURCE FORMAT
 The source file contains the textual material which will appear
on the final copy, plus the information to specify the formatting.
All the command information consists of normal ASCII printing
characters, so that a listing of the source file may be examined
if the final copy is not exactly as desired. 
 All the material in the source file is taken to be source text
except those lines beginning with a period (.). A line beginning
with a period is assumed to be a command and must match one of those
commands, which are listed in chapter 4 (indices
in App. D and E may be used for quick reference). The
commands provide the formatting information and control various
optional modes of operation.
 Usually the text is filled and justified as it is processed. That is,
the program fills a line by adding succesive words from the source 
text until one more word would cause the right margin to be exceeded.
The line is then justified by making the word spacings larger until the
last word in the line exactly meets the right margin.
 The user may occasionally wish to reproduce the source text exactly
as it is written. This is done by disabling filling and justification. 
When the fill
mode is on, spaces, tabs, and carriage returns occuring in the source 
text (but not at the beginning of the current input line)
are treated only as word separators. Multiple separators are ignored. 

 If a space or tab (one or several) is typed at the beginning of line, then
the previous line will be output and the text after the blank begins with an
indent. Thus, for the following input text:
.tp 8
.nf
#
 The previous line has been output and the text after the blank begins 
with an indent.
#
the following output text will be produced:
#
     The previous line has been output and the text after the blank begins 
with an indent. 
#
.fi

Also, lines containing only returns (blank lines) are left alone.
Thus, a text file which was written without RUNOFF in mind can be 
processed with RUNOFF without adding specific commands for editing.
 Some of the commands cause a break in the output. A break means that the 
current
line is output without justification, and the next word goes into the next
line. A break for instance occured after the word "produced:" in the example 
above.
 The program will advance to new pages as neccessary, placing the footing
(if given) at the bottom of the previous page and the title (if given)
at the top of the present page.

.hl 2 Case Information
RUNOFF does no case conversion: anything written in uppercase letters
remains uppercase, and the same holds for the lowercase letters. The
only - sensibly chosen - exemptions to this principle are:
.sl
.le file names - in the command string 
.le RUNOFF commands - .pX is the same as .Px or .PX and .px
.le indexed words - RUNOFF will treat the indexed words "KEYWORD",
"KeyWord" and "keyword" as synonyms and will produce indexing for
them under the term "Keyword" (see indexing commands).
.el
.hl 2  Special Characters
 The character at-sign (_@, shift-out 3) is used to specify underscoring.
This holds for any place you put it, except in headers and footers
(commands .he and .fo), where this character stands for the chapter
number. In all other cases the at-sign will cause underlining of the
following non-blank characters. This will persist until a new 
at-sign is found in the line. Then the underlining is turned off.
Underlining will not continue over the current line.
 It is occasionally necessary to include spaces in the text which
should not be treated as word separators. For this purpose, RUNOFF
treats the number-sign character_# as a quoted space, i.e. it
will print as exactly one space in the output and
will never be expanded nor changed to a carriage return. 
 The characters _@,_# and | have special meanings when used in
page footers and headers (see commands .fo and .he). Also, the up-arrow
character#^ , when preceding a word, is understood as a request for
inserting the word into the index buffer. An underscore (__) immediately
preceding a special character prevents this character from being interpreted
by RUNOFF. While the underscore is printed as one blank, the special
character is printed as it stands. This feature was heavily used in this text.

.ch RUNOFF COMMANDS
 The following commands will be recognized if they are at the 
beginning of a line started with a period. Any line in the source file 
beginning with a period is assumed to be one of these commands. If it is
not, RUNOFF ignores the line. 
 Some of the commands (in fact, most of them) take a decimal
argument. These are separated from the command by (one or more)
spaces and/or tabs. These numbers can also have a preceding
sign. In this case they have a relative (as opposed to an absolute)
meaning. Thus the command ".rm 10" means "set right margin to
the position ten", while ".rm -10" means "decrease the right margin ten
places". In the first case the line will end at the position ten, i.e.
it will be only ten characters long (if the indent is zero).
In the second case, we will have lines ten characters shorter than before.
.hl 2  Text Formatting
.m1 .br - BREAK
causes a break, i.e. the current line will be output with no
justification and the next word of the source text will be
placed at the beginning of the next line.
.m1 .sp n - SPACE
causes a break after which n is multiplied by the number of spaces
between lines. The result is the number of lines skipped. You 
cannot skip past the end of the page. Thus, if you want to
skip to the end of the page, .sp 1000 will do it. Mind, that
bottom of the previous page is not the same thing as top of the
current one. Use .bp if you want a new page.
.m1 .bl n  - BLANK
causes the current line to be output with no justification and
skips n line spaces. .bl is similar to .sp, except that the space
to be left is independent of the current line spacing.
.m1 .fg n  - FIGURE
leaves n lines blank to make room for a figure or diagram. If fewer 
than n lines remain on the current page, text continues to fill this page,
then the page is advanced and n blank lines are left at the top
of the next page.
.m1 .ce n - CENTER
causes a break and centers the following n lines of the text. The centering
is over the column in the middle between the left and right margin
If you intend to add new lines to these already written n lines,
here is a way to avoid changing every time the value n in .ce n:
.br
.nf
.in +10
#
#.ce 1000
#... your lines ...
#.ce 0
#
.fi
.in -10
.m1 .fn n - FOOTNOTE
saves n lines at the bottom of the current page for a footnote. n 
is multiplied by the line spacing. If insufficient spacing remains on the
current page, space is allocated at the bottom of the next one. The text
of the footnote begins in the next line. Text is copied to the output
exactly as typed in, i.e. no filling takes place. However, indentation, 
margins, spacing etc. are taken care of.
The footnote is terminated with a line beginning with an exclamation 
mark (!). The rest of the line is ignored.
.m1 .sl	n - START LIST
starts an indented list with n spacings, moves the left margin 9 spaces 
to the right for the first list command, and 4 more spaces for each of 
the subsequent nested lists. 
.m1 .le text - LIST ELEMENT
starts an item in the list, used in conjunction with the list command.
List elements are numbered sequentially and the number is given a negative
indent, so that the list lines up. The number is followed by a period
and two spaces so that the indent will be by -4. List elements
are separated by the standard paragraph spacing and test page. If you want 
to type the text on the same line as the command, you must separate
the text from the comand with tabs or spaces.
.m1 .el - END LIST
terminates the list command and returns to settings before the last .sl
command.
.hl 2 Page Formatting
.m1 .bp n - BEGIN PAGE
causes a break and a skip to the bottom of the page including footnotes,
if present, and the footer. The text following the command will
be printed on the page numbered n. If n is not given, the current page
number is incremented by one. You can also give a relative n, for 
instance .bp +5, to leave place for five pages which will come to this place
later on.
.m1 .tp n - TEST PAGE
causes a break by a conditional page advance. If fewer than n lines are
left on the current page, it skips to the next page. Thus one can be sure that
the next n lines will all be on the same page.
.m1 .ch text - CHAPTER
starts a new chapter using the text as the title of the chapter. It causes
a break, a new page, 12 blank lines, and centered text "Chapter n". n is
the chapter number which is incremented automatically by RUNOFF itself.
Then two new blank lines are typed on the page, the centered text from the
call, and finally three new blank lines (see for instance, what 
the command ".ch RUNOFF COMMANDS" at the start of this chapter produced).
The command also clears all header numbers (see further down).
.m1 .nc n - NUMBER CHAPTER 
supplies number n to be used in the subsequent chapter command. Number
chapter whould be used when a chapter of a document occupies a source file
of its own. In such a case, number chapter would be the first command
of the source file.
.m1 .hl n text -  HEADER LEVEL 
starts a section at the level specified and takes the following text 
as the header. n can range from 1 to 5. The sections are incremented by
one automatically, and the number is output in the form i.j.k.l.m. If this
is a chapter-oriented document, then i will be the chapter number. Otherwise,
it is the number of the .hl 1 level. The command causes a break, tests
for 9 live lines on the current page and outputs three blank lines. Then
the header number is output, followed by two blanks and the header
name. Header levels 1 and 2 end with a break. Header levels 3,4, and 5 end 
with a space-dash-space combination (_# -_# ).
.m1 .he text - PAGE HEADER 
takes the remaining text as a page title and outputs it on every page
at the top. The following three characters, _@,_# and | have a special
meaning in .he (as well as in .fo) command. _@ stands for the current
chapter number and_# for the current page number. You can right justify
the right-hand side of the text in page header and page footer by
inserting | before it. Thus the page header for this manual has
been specified as
.nf
#
	.he RUNOFF User Manual|Page_@ -_#
.fi
.m1 .fo text - PAGE FOOTER
takes the remaining text as a page footer and outputs it at the bottom
of every page. If you don't want it, don't specify it, or turn it off by
requiring ".fo"  with no text. The same holds for the page header.
You can use _@,_# and | the same way as for the page header.
.m1 .ix text - INDEX the text
takes the remaining text on the line as the keyword and adds it, along with the
current page number, to the internal index buffer. 
The command does not cause a break. The other possibility is to
precede the word by the character #^ (up-arrow). In this case only
the word itself is indexed. Of course you can use white blanks, for
instance "^page_#formatting_#commands", but this is unwieldy. So it
is simpler to use the .ix command.
.m1 .px - PRINT KEYWORD INDEX
causes a page advance after which it prints the entire contents of the index
buffer. Entries are printed in alphabetical order and are set against
left margin. Regular line spacing is used, except that a blank line is
left between entries of different first letters. The number of the first page
on which each entry appeared is put on the same line as the entry. Additional
page numbers for multiple entries follow, separated by commas (or dash
signs, if there are consecutive pages indexed). The index buffer
is left empty upon finishing the command execution.
.HL 2 Parameter Setting
.m1 .fi - FILL
causes a break and specifies that subsequent output lines be filled 
(initial setting). The text is left and right justified.
.m1 .nf - NOFILL
disengages the fill and outputs the input text as it is without
filling. However the indent is taken care of, as well as line
spacing, page heading, and footing. The command causes a break.
.m1 .pl n - PAGE LENGTH
sets the page length to n. The page length will not be less than 11. Ten
lines are needed for the header and footer, and one line will remain
for your text. If you don't specify n, the default value of 66 lines will
be used from now on. 
.m1 .in {+-}n - INDENT
causes a break and sets a new value of the left margin. In the
beginning its value is 0, i.e. text starts in the first column
of the output page. 
.m1 .ti {+-}n - TEMPORARY INDENT
causes a break and change in the value of the current indent. 
The next line to be produced will temporarily have the indent changed.
You can for instance produce - by combination of .in and .ti -
hanging indents, like in numbered paragraphs. This combination of
commands:
.nf
#
	.in +5
	.ti -5
#
.fi
will cause the paragraph numbers hang out like this:
.br
.in +5
#
.ti -5
1.###First paragraph with lots of spurious lines causing severe headaches to any reader.
.ti -5
2.###Second paragraph with even more lines and even less meaning, so that the
reader will finally give up and turn to something more pleasant.
#
.br
.in -5
The next line will then return to the normal indent as shown, and the
command .in -5 will return things to the values used before these commands.
.m1 .rm {+-}n - RIGHT MARGIN
is set by this command. It can be increased or decreased (using +/- )
or set to some number (n without sign). Default value is 60.
.m1 .ls n - LINE SPACING
sets the number of spaces between lines. .ls 2 will thus
produce lines which will be separated by one blank line. 
.hl 2 Macros
 Some of the combinations of commands will be pretty often used.
Also, some situations will have to be solved in the same way which,
however, will have to be left open at the start. Imagine there
is a lot of tables in my text. I know that I must space them from
the rest of the material, center their title etc. Most important,
however, is to treat all of them the same way, if possible with one
single command, like .st (for start table) and .et (for end table).
 
 For this purpose the macro utility is made available. All in all nine
macros can be defined and used the same way as all other commands are.
In addition, one parameter can be passed as an argument to the macro, so the
flexibility is high.
.m1 .ma i;text - MACRO DEFINITION
defines the macro with number i (1 to 9) and body text. The definition
must fit into one source line. text is made of one or several strings
seperated by semicolons. The character dollar ($) is used as the parameter
marker.
 The best way to show how the macro definition works is by an example. 
Let us define the macro 1 as a command which will:
.sl
.le produce the new chapter and
.le at the same time change the page headers and footers
.el
 This means we have to write the shorthand for the following set of commands:
.nf
#
      .he new title|page_@ -_#
      .fo chapter new title - macro facilities
      .ch new title
#    
.fi
The new title will be used as the macro parameter which will be 
presented at every invocation of the macro, so the macro definition 
looks like this:
.nf
#
	.ma 1;.he $ |page_@ -_#;.fo chapter $;ch $
#
.fi
.m1 .mi string - MACRO INVOCATION
invokes macro i (1 to 9) with argument string.
If we decide to change the subject and skip to the chapter called 
"Various dynosauria", we only have to specify 
.nf
#
	.m1 Various dynosauria 
#
.fi
and the thing is done by RUNOFF itself.
The argument can of course also be numeric. The following macro
reduces both the left and the right hand margins:
.nf
#         
         .ma 5;.in $;.rm -$
#
.fi
The call .m5 6 would reduce them by 6, and the call .m5 (without
parameter) would set them to default.

.ch APPENDICES
.ma 5 ;bp;.sp 5;
.hl 2 Appendix A: rno Error Messages
.hl 2 Appendix B: Building and Running RUNOFF
.hl 2 Appendix C: Special Characters
.hl 2 Appendix D: Alphabetic Index of Commands
.hl 2 Appendix E: Index of Commands according to their Function
.bp
