.rem ********************************* .rem * Runoff User's Manual * .rem * April 30, 1982 * .rem * Raymond E. Penley * .rem ********************************* .rem .rem --------------------------- SETUP ---------------------------------- .he RUNOFF User's Guide .lm 1 .rm 78 .nhd .nf .sp 22 .c 4 RUNOFF User's Guide CP/M VERSION 1.0 RAYMOND E. PENLEY APRIL 30, 1982 .np .rem -------------------------------------------------------------------- .j .p 5 This is a public domain program. You are encouraged to modify this program to make it better, add new features (but try not to make the executable code much over 20K), make changes, etc. Please send your enhancements to the Pascal/Z Users Group. Thank you. .sp 12 CP/M (r) is a trademark of Digital Research. .hd .bp 1 .np .rem -------------------------------------------------------------------- .hl 1 INTRODUCTION: .j .p This is a version of RUNOFF a text formatting program. It is patterened somewhat after the RUNOFF for the DEC PDP-11. The commands available are a subset of those available in the original PDP-11 version. The command formats and actions are the same as the PDP-11 version. The underlying source code program for this version is written in Pascal. .p New commands include; .MES, prints message to the console; .WAIT, a pause that waits for operator intervention; .SF and .CF, single sheet and continuous forms control; .REM, for remarks imbedded in the text; and .OUT , to allow additional control over the printed output. .rem .rem .hl 2 HOW TO USE THIS GUIDE: .p There are a few notational conventions that are used throughout this manual. .sp .nf <> Symbol brackets. This space should be replaced by the item described. [] Optional brackets. Symbols enclosed between brackets are optional. ... Repetional ellipsis. The preceding symbol may be repeated. .j .rem -------------------------------------------------------------------- .hl 2 SOURCE FILE FORMAT: .p Using your favorite text editor you create a file containing the text of the document. Under the CP/M operating system the normal file consists of a collection of characters stored under a file name on a diskette. The file or document is a standard ASCII text file with the RUNOFF commands imbedded in the file. All lines starting with a period are taken to be commands; only one command per line is permitted. All other lines are considered as text to be formatted. There are no case control characters as in other versions of RUNOFF. Letters are output in whatever case they appear in the source file. .rem -------------------------------------------------------------------- .hl 2 CAPABILITIES: .p Text is normally justified. Justified text has additional spaces inserted between the words to make the right end of each line in a paragraph come out exactly at the right margin; Ragged Right text does not have these spaces. Justification is on by default, but may be turned off to produce ragged right text. Some users prefer ragged right, e.g. for correspondence which they wish to appear hand-typed. .p Functions are available that can turn on/off line filling and justification. .p Text is automatically split up into consecutively numbered pages. Each page has a five line header margin. The title and page number appear on the second line of the header margin. Printing of either the title or page number or both is optional. .p Section headers of up to five numbers, i.e. i.j.k.l.m, plus section title may be specified. Section numbers will be incremented automatically whenever the section header command is encountered. .p Numbered lists are available and may be nested to five levels. List elements are indented from normal text and are filled and justified if fill is enabled. .rem -------------------------------------------------------------------- .hl 2 INVOKING RUNOFF UNDER THE CP/M OPERATING SYSTEM: .p RUNOFF requires an input file and directs its output to one of the following devices: list (LST:); console (CON:); disk (d:filename). .nf .ls 2 .p The command to execute RUNOFF takes one of the following forms: .TI 7 RUNOFF [d:]sourcefile [d:]outputfile Directs the formatted output to the disk file "outputfile" name. .TI 7 RUNOFF [d:]sourcefile or RUNOFF [d:]sourcefile LST: Directs the formatted output to the List device. .TI 7 RUNOFF [d:]sourcefile CON: Directs the formatted output to the console device for previewing. .ls 1 .j .p The source file and the output file may be on the same or different disk drives. Simply by prefixing the file name with the drive identifier causes the program to read/write the file from the specified drive. .sp .TI 7 RUNOFF sourcefile b:outputfile .sp .p Will process the file "sourcefile" from the currently logged in disk drive and send the output file to a file "outputfile" on drive B:. .rem -------------------------------------------------------------------- .hl 1 TEXT FORMATTING COMMANDS: .p 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, an error diagnostic will be displayed on the console and the line will be ignored. Some commands take one or more decimal numbers following. These must be separated from the command by at least one space. RUNOFF commands take on one of the following forms: .nf .sp .ti 20 .AA .ti 20 .AA n .ti 20 .AA text .ti 0 .sp where AA is a keyword and n is a value {which may be optional} depending on the command. The keyword may be in upper or lower case. A space is required before numeric or textual values. .rem .hl 2 INITIAL VALUES: .j .p Initial numeric values are assigned to various RUNOFF commands as follows: .nf .sp .lm = 0 left margin .rm = 60 right margin .ls = 1 line spacing .p = 5 paragraph .cnp = 0 conditional new page .pl = 60 page length .rem .np .rem -------------------------------------------------------------------- .hl 1 RUNOFF COMMANDS: .p The commands as listed here in alphabetical order. .sp 5 .BP n Begin Page .BR Break .C n Center .CF Continuous Forms .CNP n Conditional New Page .ELS End Current List .FI Filling On .HD Header title on .HE text Header text .HL n text Heading Level and section header text .J Justify On .LE List element .LJ Left Justify .LM n Left Margin .LS n Line Spacing .MES text Text message to console .NBP No Page Numbering .NF No Fill .NJ No Justify .NL n Numbered list .NP New Page .NPR No Period .OUT n output control values .P n m w Paragraph Break .PL n w Page Length .PR Period flag .REM text Remark .RM n Right Margin .SF Single Forms .SK n Skip n * Line Spacing lines .SP n Space n Lines .TI n Temporary Indent n .WAIT Pause .np .hl 2 MARGINS: .nf .sp .ti 10 LEFT MARGIN .LM .j .p The LM command sets the margin to and causes a break. must be less than the right margin but not less than 0. The default setting is 0. If indenting, the amount of any indent plus the left margin must not be less than 0. .nf .sp .ti 10 RIGHT MARGIN .RM .j .p The RM command sets the right margin to and causes a break. must be greter than the left margin. The default setting is 60. .p The number of characters on a line will be equal to or less than the right margin minus the left margin minus any indenting which may be specified. Even if filling has been disabled, lines will not be extended past the right margin. .rem hl 2 FILLING: .nf .sp .ti 10 FILL .FI .j .p The FI command causes a break and specifies filling of following output lines. Justification is specified by the last setting of the .J or .NJ commands (DEFAULT=NO). .nf .sp .ti 10 NO FILL .NF .j .p The NF command causes a break and prevents filling of all following output lines. Also, justification is disabled. .rem -------------------------------------------------------------------- .hl 2 JUSTIFYING: .nf .sp .ti 10 JUSTIFY .J .j .p The J command causes a break and forces justifiction of subsequent output lines (DEFAULT=ON). .nf .sp .ti 10 LEFT JUSTIFY .LJ .j .p The LJ command causes a break and produces what is commonly called "ragged right" text. Lines will be filled with words but justification is turned off. If a word will not fit on the current line it will be placed in the next line. .nf .sp .ti 10 NO JUSTIFY .NJ .j .p The NJ causes a break and terminates justification of following lines of text. .rem .hl 2 CENTERING: .nf .sp .ti 10 CENTER .C .j .p The C command causes a break after which it centers the next lines in the source file. Center will always center at least one line. The centering is between the left and right margins. .rem -------------------------------------------------------------------- .hl 2 PARAGRAPHS: .nf .sp .ti 10 PARAGRAPH .P [ ] .rem .hl 3 COMMAND FORM .sp (a) .p (b) .p (c) .p .j .p The P command causes a break, inserts (SP+1)/2 blank lines and indents the next line of text positions. The initial value for "indent" is 5 spaces. If command form (a) is used then indenting will take on the new value of . If command form (b) is used then the vertical spacing between paragraphs is set to . If command form (c) is used then sets an argument for a 'Conditional New Page' command just before the paragraph is begun. .nf .sp .ti 10 TEMPORARY INDENT .TI +- .j .p The TI command causes a break and sets the next line to begin spaces to the right of the left margin. may be negative to cause the line to begin to the left of the left margin, it effectively created an "outdent" command. TI works with the LM command, for example: .nf .sp .j .lm 12 .ti -10 TEMPORARY INDENT The TI command causes a break and sets the next line to begin spaces to the right of the left margin. may be negative to cause the line to begin to the left of the left margin, it effectively created an "outdent" command. .sp .sp would produce the following output: .j .sp .lm 12 .ti -10 TEMPORARY INDENT: The TI command causes a break and sets the next line to begin spaces to the right of the left margin. may be negative to cause the line to begin to the left of the left margin, it effectively created an "outdent" command. .sp .lm 1 .ti 0 .rem -------------------------------------------------------------------- .hl 2 TABS: .j .p Unfortunately at the present time RUNOFF does not recognize the tab character and there is no way to set/reset tab stops. Do not use the tab character in a RUNOFF file. .rem .hl 2 LINE SPACING: .nf .sp .ti 10 SKIP .SK .j .p The SK command causes a break after which [ N * (line spacing) ] lines are left blank. If the skip would leave room for less than two printed lines on the page (i.e. if there are less than [ N + 2 * (line spacing) ] lines left), the output is advanced to the top of the next page. If the output is currently at the top of a new page no lines are skipped. .nf .sp .ti 10 SPACE .SP .j .p The SP command inserts inton the output file. SPACE is to be used where space is to be left independent of the line spacing; SKIP is to be used where the space should be relative to the line spacing. If the output is currently at the top of a new page no lines are skipped. .nf .sp .ti 10 BREAK .BR .j .p The BR command 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 according to the current line spacing. .rem -------------------------------------------------------------------- .hl 1 PAGINATION COMMANDS: .rem .hl 2 HEADINGS AND FOOTINGS: .nf .sp .ti 10 HEADER .HE .j .p The HE command takes the remaining text on the line as the title. This text will appear at the top of all subsequent pages, aligned with the left margin on the second line of the page. The title is initially blank. .p The Header Margin is 3 by default and the Top Margin is 5 by default. These values are presently locked into the program, however, since the source code is available it shouldn't be much trouble to make these margin settings user selectable. .nf .sp .ti 10 HEAD Command .HD .j .p The HD command enables the printing of title and page number at the top of each new page. .nf .sp .ti 10 No Head Command .NHD .j .p The NHD command turns off the printing of title and page number at the top of each new page. .rem -------------------------------------------------------------------- .hl 2 PAGE NUMBERING: .nf .sp .ti 10 BEGIN PAGE .BP .j .p The BP command turns on page numbering at page . .nf .sp .ti 10 NO PAGE NUMBERING .NBP .j .p The NBP or omit page numbering command turns off page numbering. Pages will continue to be counted so that the normal page number will reappear if page numbering is resumed. .rem -------------------------------------------------------------------- .hl 2 PAGINATION: .nf .sp .ti 10 NEW PAGE .NP .j .p The NP command causes a break and an advance to a new page. It does nothing if the current page is empty. .nf .sp .ti 10 CONDITIONAL NEW PAGE .CNP .j .p The CNP PAGE command causes a break followed by a conditional page advance. If there are or more lines remaining on the current page then no advance is made, otherwise, the page is advanced as in the NP command. This command should be used to ensure that the following are all output on the same page. .nf .sp .ti 10 LINE SPACING .LS .j .p The LS command causes a break after which the line spacing will be set to . must be within the range 1 to 5. Single spacing is 1, double spacing is 2. Default is single spacing. .nf .sp .ti 10 PAGE LENGTH .PL [] .rem .hl 3 COMMAND FORM .sp (a) .pl (b) .pl .j .p The PL command specifies the width of the page in columns and the length of the page in lines. If values other than the default values are used, then this command should appear before any of the margin or heading commands. Whenever RUNOFF begins printing a new page, the line count is initialized to a value of one. As each line is printed the line count is incremented. When the page length is reached, a sheet of paper is ejected from the printer and a new page is begun. is the number of lines on an entire page, including the top margin of 5 lines. The paper length must match the forms in use. The default is 60 lines or 11 inches. The sets the paper width in columns; it acts like the RIGHT MARGIN command. .rem .hl 2 PRINTER CONTROL: .nf .sp .OUT [ ... ] .j .p The OUT command allows direct access to printer controls. is the decimal value of the control code. i.e. if the command to set your printer to 12 cpi is say escape + "A" then you would enter the command line as: .nf .sp .OUT 27 65 .sp .j .p Notice that the values are separated by spaces. The maximum number of arguments that may be output is eight. .nf .sp .WAIT .j .p The WAIT command puts the program in a pause mode awaiting for any input from the operator at the console. .rem .hl 2 REMARKS AND MESSAGE DISPLAY: .nf .sp .REM [text] .j .p The REMARKS command may be used to separate paragraphs, put comments in the text for later use. .nf .sp .MES .j .p The MES or MESSAGE command sends the text string to the console for viewing. This command can be particularly useful in combination with the WAIT command. .rem .hl 2 MISCELLANEOUS: .nf .sp .ti 10 PERIOD .PR .j .p The PERIOD command causes two spaces to be inserted after punctuation marks for proper spacing between sentences. The punctuation marks are: '.', '?', and '!'. .nf .sp .ti 10 SINGLE SHEET .SF .j .p The SINGLE SHEET command causes the program to pause after each page allowing the operator time to change the paper in the printer. .nf .sp .ti 10 CONTINUOUS FORMS .CF .j .p The CONTINUOUS FORMS command sets the program up to use continuous paper. This is the default value. .nf .sp .ti 10 HEADING LEVEL .HL .j .p The HEADING LEVEL command starts a section at the level specified by and takes the text string as the header. must be specified as 1, 2, 3, 4, or 5. The sections are incremented by one automatically and the number is output in the form of i.j.k.l.m. This command acts as a: .nf .BREAK .TEST PAGE 9 .BLANK 3 followed by the section number, two spaces and the section name. .rem .hl 2 LIST ELEMENTS: .nf .sp .ti 10 NUMBERED LIST .NL .j .p The NUMBERED LIST command causes a break and starts a numbered list. is the number of blank lines left between list elements. The first list is indented 9 spaces from the left margin; subsequent nested lists are indented 4 more spaces. There may be up to 5 levels of nested numbered lists. .nf .sp .ti 10 LIST ELEMENT .LE .j .p The LIST ELEMENT command causes a break and starts a new list element. Elements are numbered sequentially and the numbers have a negative indent from the body of the list element. .nf .sp .ti 10 END LIST .ELS .j .p The END LIST command causes a break and terminates the current list by re-adjusting the left margin. .rem .hl 1 EXAMPLES: .sp Following are examples of the effects of different commands. After the examples is the section of RUNOFF source input that produced the examples. .rem .hl 1 FIRST LEVEL HEADER .nf .p This is unfilled and unjustified text. It comes out just as you put it in. It can have paragraph spacing and indenting with the .P command if you like. It doesn't line up with the right margin but it will never be allowed to extend beyond the right margin; the excess will be put on the next line. This command may be used for columnar work, tables, and address lists. For example: .nf South Fork Hospital 12 South Bend Ave. Pine Blufs, IN 12345 .sp 3 .LJ .hl 2 SECOND LEVEL HEADER .p This is left justified text. The line contains as many full words as will fit without running over the right margin. When FILL is enabled the PERIOD and NOPERIOD options come into effect. PERIOD inserts two spaces after the end-of-sentence punctuation; NOPERIOD inserts one blank. .rem .hl 3 THIRD LEVEL HEADER .j .p This is justified text. The line is filled with words and right justified by inserting spaces throughout the line. The blanks are added alternately on the left and right sides of the line; this is to avoid "rivers" of blank space running down the page. Since this program does not hyphenate words there may occasionally be lines with a large number of inserted blanks. .rem .hl 4 FOURTH LEVEL HEADER .p It should be noted that SKIP and SPACE have no effect at the top of a new page. This is a bit inconvenient if, for example, you want to create a title page with a title block spaced part way down the page. You can get around this problem by doing the following: .nf .sp .NHD -TURN OFF PAGE HEADER .NF -TURN OFF FILLING -INSERT ONE BLANK LINE TO GET OFF TOP OF PAGE .SP n -SPACE DOWN n LINES .C -CENTER TITLE LINE(s) this is my title line .HD -RESET FOR REGULAR PROCESSING .BP 1 -BEGIN PAGE NUMBERING WITH PAGE 1 .FI -TURN FILL ON .NP -NEW PAGE .rem .fi .hl 5 FIFTH LEVEL HEADER .p This is as far as you can go for header. .hl 4 BACK TO FOURTH LEVEL HEADER .hl 3 BACK TO THIRD LEVEL HEADER .hl 1 BACK TO FIRST LEVEL HEADER .hl 2 LISTS - NUMBERED .nl 1 .le Here we have the first level of list. .nl 1 .le The next level. .le A second element. .nl 1 .le Third level list. .le And so on, .le And so on for two more levels of indenting. .els .els Back out to the outermost list. .els .np .rem -------------------------------------------------------------------- .hl 1 LITERAL TEXT: .p Following is the literal source text that produced the above. It has been offset by one space so that the commands will be processed as normal text. .nf .rm 80 .sp .rem .hl 1 FIRST LEVEL HEADER .nf .p This is unfilled and unjustified text. It comes out just as you put it in. It can have paragraph spacing and indenting with the .P command if you like. It doesn't line up with the right margin but it will never be allowed to extend beyond the right margin; the excess will be put on the next line. This command may be used for columnar work, tables, and address lists. For example: .nf South Fork Hospital 12 South Bend Ave. Pine Blufs, IN 12345 .sp 3 .LJ .hl 2 SECOND LEVEL HEADER .p This is left justified text. The line contains as many full words as will fit without running over the right margin. When FILL is enabled the PERIOD and NOPERIOD options come into effect. PERIOD inserts two spaces after the end-of-sentence punctuation; NOPERIOD inserts one blank. .rem .hl 3 THIRD LEVEL HEADER .j .p This is justified text. The line is filled with words and right justified by inserting spaces throughout the line. The blanks are added alternately on the left and right sides of the line; this is to avoid "rivers" of blank space running down the page. Since this program does not hyphenate words there may occasionally be lines with a large number of inserted blanks. .rem .hl 4 FOURTH LEVEL HEADER .p It should be noted that SKIP and SPACE have no effect at the top of a new page. This is a bit inconvenient if, for example, you want to create a title page with a title block spaced part way down the page. You can get around this problem by doing the following: .nf .sp .NHD -TURN OFF PAGE HEADER .NF -TURN OFF FILLING -INSERT ONE BLANK LINE TO GET OFF TOP OF PAGE .SP n -SPACE DOWN n LINES .C -CENTER TITLE LINE(s) title line text here .HD -RESET FOR REGULAR PROCESSING .BP 1 -BEGIN PAGE NUMBERING WITH PAGE 1 .FI -TURN FILL ON .NP -NEW PAGE .rem .fi .hl 5 FIFTH LEVEL HEADER .p This is as far as you can go for header. .hl 4 BACK TO FOURTH LEVEL HEADER .hl 3 BACK TO THIRD LEVEL HEADER .hl 1 BACK TO FIRST LEVEL HEADER .hl 2 LISTS - NUMBERED .nl 1 .le Here we have the first level of list. .nl 1 .le The next level. .le A second element. .nl 1 .le Third level list. .le And so on, .le And so on for two more levels of indenting. .els .els Back out to the outermost list. .els .np .rem -------------------------------------------------------------------- .nf .rm 80 .ls 2 .c APPENDIX A .c SUMMARY OF RUNOFF COMMANDS .ls 1 Command Format Function ------- -------------------------------------------------------- .sp .bp Begin page numbering at page . .br Break - Stop filling and start a new line. .c Center next lines. Default=1. .cf Continuous Forms. Default=ON. .cnp Conditional New Page. Starts a new page if there are less then lines remaining. .els Terminate the current list. .fi Set Line Filling On. .hd Sets flag to turn on printing of header title and page #. .he Set header title to text. .hl Set heading level and section header text. .j Justify lines by blank filling. Default=ON. .le Starts a new list element. .lj Left Justify lines. Produces "ragged right" lines. .lm Set left margin to column . .ls Set line spacing to . Default=1; Double spacing=2. .nl Starts a numbered list. .mes Sends message to console. .nbp Terminate page numbering. .nf Terminate Filling Lines. .nj No Justify - justify off. .np New Page. .npr Terminate spacing sentences. .out [ ... ] Directly output control values to the printer device. .p [ ] Paragraph Break. = sets paragraph indenting spaces. = sets vertical spacing between paragraphs. = sets argument for conditional new page. .pl [] Set Page Length to . Set right margin to . .pr Period flag, set sentences spaced by 2 chars. .rem [text] Remark. Any comments may be placed on a remark line. .rm Set right margin to column . .sf Single Forms. Pause for operator intervention between pages. .sk Skips * (line spacing) lines. .sp Space lines exactly. .ti +- Temporary Indent spaces. may be negative for outdent (not less than 0) .wait Force program to wait for operator intervention. .rem -------------------------------------------------------------- .np .