RRRR U U N N OOO FFFFF FFFFF R R U U NN N O O F F RRRR U U N N N O O FFF FFF R R U U N NN O O F F R R UUU N N OOO F F PDP-11 RUNOFF Revised by: C. D. Lowenstein (Marine Physical Lab.) Revision Date: 20 November 1978 University of California, San Diego Marine Physical Laboratory of the Scripps Institution of Oceanography San Diego, California 92152 PDP-11 RUNOFF Page 1 22 Nov 78 RUNOFF is a PDP-11 program running under RT-11 to facilitate the preparation of typed or printed manuscripts, such as memos, letters, manuals, etc. The user prepares his material on any regular PDP-11 terminal, and writes it onto a file using EDIT11. The user includes not only textual material, but also case and formatting information. RUNOFF then takes the file and reproduces it onto the line printer, teletype or other file to produce a final copy or final file image. It performs the formatting and case shifting as directed, and will also perform line justification, page numbering and titling, etc., as desired. The principal benefit of such a program is that files prepared for use with it may be edited and corrected easily. Small or large amounts of material may be added or deleted, and unchanged material need not be retyped. After a set of changes, the program may be operated to produce a new copy which is properly paged and formatted. Documentation may thus be updated as necessary without requiring extensive retyping. ON LINE OPERATION RUNOFF is a program much like most RT-11 system programs. It is accessed by the command to the monitor: RU RUNOFF The program will respond with its title and version number, followed by an asterisk ( * ), and then wait for a command string. *DEV:OUTPUT.EXT < DEV:INPUT.EXT/SW There may be up to six input files, and several switches. The destination device may be TT:, the teletype, which is limited in that all letters are upper case, and underlining is not available. (These restrictions do not apply to some more elaborate teletype-like terminals such as the LA-36 DECwriter.) Alternately, a disk file name or other device and file name may be given, and the final image will be written onto it. The default extension for input files is ".RNO", the default extension for output files is ".DOC". Switches are: /F:n. Form feed simulation. The program will advance to a new page when appropriate by typing the necessary number of line-feed characters, as determined by the specified hardware page length n. If n is not specified, the _ _ default value of 66. is used. An initial pause allows the operator to position the paper for the first page. /H Hyphenate as necessary to justify lines. /L:m.:n. Limits - Print from page m to page n inclusive. _ _ If only one value is given, that page is printed. PDP-11 RUNOFF Page 2 22 Nov 78 /P Pause after the completion of each page. This allows the operator to position the paper manually, e.g. for typing the output onto pages of duplicating masters. /P supersedes the effect of /F. /U Underscore by overprinting the line (default). /U:B Underscore by backspacing (LA-36 DECwriter). /U:C Underscore without backspace (Flexowriter). /U:S Underscore on next line with - (minus sign) (for printers that can't overprint lines) /U:N Suppress underscores. /? Print HELP message. In order to use the 64 character line printer, it is necessary to use the RT-11 MONITOR command ".SET LP NOLC". When the program has completed processing, it will type * and await another command string. PDP-11 RUNOFF Page 3 22 Nov 78 SOURCE FILE FORMAT As stated above, the source file contains the textual material which will appear on the final copy, plus information to specify formatting. Most importantly, upper and lower case information may also be supplied so that copy can be prepared on the teletype or other such device which can normally input only upper case letters. All command information consists of regular ASCII printing characters so that a listing of the source file may be examined if the final copy is not exactly as desired. All 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 listed below. 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 successive 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, which is done by disabling filling and justification. The program may be set to fill but not justify, in which case the output will be normal except that lines will not be justified to the right margin. The program may also be set to justify but not fill, although this would probably produce peculiar results and is not recommended. When the fill mode is on, spaces and carriage returns occurring in the source text are treated only as word separators. Multiple separators are ignored, i.e. double or triple spaces are treated as single spaces. 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 at the beginning of the next line. This occurs at the end of paragraphs. The program will advance to new pages as necessary, placing the title (if given) and the page number at the top of each page. The user may explicitly call for a page advance where desired, and may inhibit the occurrence of a page advance within specified material. PDP-11 RUNOFF Page 4 22 Nov 78 CASE INFORMATION Specification of case for files prepared on the teletype is done with two characters, up-arrow (^, shift-N), and back-slash (\, shift-L). The appearance of an up-arrow causes the letter immediately following to be transmitted in upper case. The appearance of a back-slash causes the letter immediately following to be converted to lower case. Any letter not preceeded by one of these characters is transmitted in the current mode. The mode is initially lower case, and is changed by the occurrence of two successive case control characters. Two up-arrows (^^) cause the mode to be set to upper case, and two back-slashes (\\) cause the mode to be set to lower case. The use of the above corresponds to the use of the shift and shift-lock keys on a typewriter. Usually, typing appears in lower case. To type one letter in upper case, the shift key is used. The shift-lock is set to type a series of upper case letters, after which it is released. The following shows the uses of the case control characters: ^HERE IS A ^SAMPLE ^SENTENCE IN ^^UPPER CASE\\ AND LOWER CASE. becomes: Here is a Sample Sentence in UPPER CASE and lower case. Note: Case conversion takes place only on ASCII codes 101 to 132 octal, that is, the upper case letters. Any actual lower case letters (codes 141 to 172 octal) appearing in the source will be transmitted unchanged. If the source is prepared on a device such as a DECwriter, Flexowriter, or model 37 Teletype which produces letters of the proper case, the mode should be set to upper case at the beginning of the file and left unchanged for the remainder. PDP-11 RUNOFF Page 5 22 Nov 78 SPECIAL CHARACTERS The character ampersand (&, shift-6) is used to specify underscoring. The ampersand will cause the character following it to be underscored, e.g. &f&o&o becomes foo. ___ Underlining of a string of characters can also be specified, similar to the use of the shift lock operations described above. An appearance of ampersand preceded by up-arrow (^&) will cause underlining of all following characters except space. An appearance of ampersand preceded by backslash (\&) will disable this mode. The present version of RUNOFF uses the ASCII character 137 for an underline, which prints as a left arrow on some printers. This is due to the erratic nature of ASCII on certain characters such as underline over the years. It is occasionally necessary to include spaces in the text which should not be treated as word separators. For this purpose, RUNOFF treats numbersign (#) as a quoted space; i.e. it will __________ print as exactly one space in the output, will never be expanded nor changed to a carriage return. To allow the appearance of the special characters (ampersand, number-sign, up-arrow, or back-slash) in the output, the character underline (_, shift-O) is used as a quote character. The character immediately following an underline will be transmitted to the output with no formatting effect. The underline itself is thus another case requiring quoting. The following five cases occur: _&, _^, _\, __, and _#. PDP-11 RUNOFF Page 6 22 Nov 78 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, an error diagnostic will be typed and the line will be ignored. Some commands may be followed by one or more decimal numbers. These are separated from the command by a space. Several commands may be given on a single line, separated by a semicolon ( ; ). A line which is started with an exclamation point ( ! ) is considered to be a comment. Certain commands can be abbreviated. These abbreviations are given in Appendix A, and in the following command descriptions. Formatting .BREAK .BR 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. .SKIP n .S n 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. .BLANK n .B n Exactly like SKIP, except that n (rather than n*(line spacing)) lines are specified. BLANK is used where space is to be left independent of the line spacing; SKIP, where the space should be relative to the size of line space. .FIGURE n .FG n Like BLANK except that if less than n lines remain on the current page, the page will be advanced, and n blank lines will be left at the top of the new page. Principally used where it is desired to leave room for a figure to be drawn in manually. PDP-11 RUNOFF Page 7 22 Nov 78 .INDENT n .I n Causes a break and sets the next line to begin n spaces to the right of the left margin. n may be negative to cause the line to begin to the left of the left margin (useful for numbered paragraphs). .PARAGRAPH n .P n The number is optional and, if present, sets the number of spaces which paragraphs are to be indented. The initial setting is 5. (n can also have a negative value) The command causes a break and leaves [(m+1)/2] additional blank lines, where m is the regular line spacing. The next line will be indented as indicated above. .PAGE .PG Causes a break and an advance to a new page. Does nothing if the current page is empty. Titling and numbering as for automatic page advance. .TEST PAGE n .TP n Causes a break followed by a conditional page advance. If there are n*(line spacing) or more lines remaining on the current page, no advance is made and no lines are skipped. Otherwise, the page is advanced as for PAGE. This command should be used to ensure that the following n lines are all output on the same page. .NUMBER n .NM n Turns on page numbering (normal) and, if n is supplied, sets _ the current page number to n. _ .NONUMBER .NNM Turns off page numbering. Pages will continue to be counted, so the normal page number will appear if numbering is re-enabled. Note: Both NUMBER and NONUMBER do not take effect until the following page header is printed. At that time, the page number will be n + 1. _ PDP-11 RUNOFF Page 8 22 Nov 78 .DATE .D Prints the current system date right-justified directly under the page number in each page header. If the page number does not appear, the date is not printed. The date is in the format DD Mmm YY. .NODATE .ND Suppresses printing of the current date. NODATE is the initial setting. DATE and NODATE take effect at the top of the following page, in a manner similar to NUMBER and NONUMBER. Mode Setting .LOWER CASE .LC Sets the case lock to lower case. Equivalent to \\. All letters are output as lower case unless a case shift is indicated. (Initial setting) .UPPER CASE .UC Sets the case lock to upper case. Equivalent to ^^. Any upper case letters in the source file are output as upper case. Note: Since case control applies only to upper case characters in the source file (ASCII codes 101 to 132), UPPER CASE mode causes the text to be reproduced as it is in the source file. This is especially useful if the source is created on a terminal that can input both upper and lower case characters. .JUSTIFY .J Causes a break and sets subsequent output lines to be justified. (Initial setting) PDP-11 RUNOFF Page 9 22 Nov 78 .NOJUSTIFY .NJ Causes a break and prevents justification of subsequent output lines. .FILL .F Causes a break and specifies that subsequent output lines be filled. Sets the justification mode to be that specified by the last appearance of JUSTIFY or NOJUSTIFY. (Initial setting) .NOFILL .NF Causes a break and prevents filling of subsequent output lines. Also turns off justification. Note: 1. The nofill-nojustify mode need be used only where there are several lines of material to be copied exactly. A single line example will not require using these commands if there are breaks before and after. 2. Normally FILL and NOFILL are used to turn both filling and justification on and off. It is usually desirable to do both. A subsequent appearance of a justification command will override the fill command however. 3. Because of the action of FILL, a single occurrence of NOJUSTIFY will cause the remainder of the file to be unjustified, with filling as specified. In order to justify but not fill (not recommended), a JUSTIFY command must follow every NOFILL command. PDP-11 RUNOFF Page 10 22 Nov 78 Parameter Settings .LEFT MARGIN n .LM n Causes a break after which the left margin is set to n. n must be less than the right margin, but not less than 0. The initial setting is 0. The amount of any indent plus the left margin must not be less than 0. .RIGHT MARGIN n .RM n Causes a break after which the right margin is set to n. n must be greater than the left margin, and not greater than 132. The initial setting is 60. 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. .SPACING n .SP n Causes a break after which the line spacing will be set to n. n must be within the range 1 to 5. Single spacing is 1, double spacing is 2, etc. .PAPER SIZE n,m .PS n,m Sets the number of lines per page to n. n must be greater than 10. The initial setting is 60. n includes the top margin of 5 lines. The page number and title appear on the second line, preceded by one blank line. The subtitle is on the third line, and is followed by two blank lines. The second argument, m, is optional. If present, it sets the paper width in columns (initially 60). It must be greater than the left margin, and not greater than 132, and it is set into the right margin as if a RIGHT MARGIN m command had also been typed. This command is usually used only at the beginning of a file, but may be used throughout if needed. .TAB STOPS n ... n .TS n ... n Clears all previous tab stops and sets new tab stops as specified. The several n (max 32) must be greater than zero and in increasing order. They are the positions of tab stops independent of the setting of the left margin, although any which are less than the left margin will not be seen. There are no tab stops initially. Tabs are produced by use of the key or by . PDP-11 RUNOFF Page 11 22 Nov 78 They should be used only in lines which will be unjustified and unfilled, i.e. where filling is disabled or a break immediately follows. Clearly, the spaces specified by a tab character should not be expanded to justify the line--this would defeat the effect of tab formatting. The appearance of a tab in the source text will be translated to one or more spaces, the amount necessary to advance to the next tab stop. If a tab appears at a point where no further tab stops have been set on a line, the tab will be treated as though it had been a space. Miscellaneous .TITLE tttt ... tttt .T tttt ... tttt This command takes the remaining text on the line as the title. (up to 52 characters) This text will appear at the top of all subsequent pages, at position 0, on the second line with the page number. The title is initially blank. .SUBTITLE tttt ... tttt .ST tttt ... tttt This command takes the remaining text on the line as the subtitle. (up to 52 characters) This text will appear on the line immediately following the title and page number. The subtitle is initially blank. The subtitle is not indented, but may contain leading spaces to achieve the same effect, if desired. .CENTER n .C n This command causes a break after which it centers the next line following in the source file. The centering is over the column n/2, independent of the setting of the left and right margins. If n is missing, n is assumed to be the paper width, initially 60. (See PAPER SIZE command.) .FOOTNOTE n .FN n Allocates n*(line spacing) lines at the bottom of the current page for a footnote(1). If insufficient room remains on the current page, space will be allocated at the bottom of the following page. The text for the footnote begins on the line following the command, and it may contain any appropriate commands (e.g. CENTER, SKIP) necessary to = = = = = = = = = = = (1) This is a footnote. This text and the dividing line above were specified by text and commands following a FOOTNOTE 5 command. PDP-11 RUNOFF Page 12 22 Nov 78 format the footnote. The footnote is terminated by a line beginning with an exclamation point ( ! ), the remainder of which is ignored. The lines delimited by this line and the FOOTNOTE command are put into a buffer to be processed when the output moves to within the stated distance of the bottom of the page. If a page has multiple footnotes, the allocated space is the sum of the allocations for all footnotes assigned to the page. The user must include his choice of footnote-designating symbols within the text. The current values of left and right margin and line spacing are saved and restored after processing of footnotes. Therefore, a footnote may contain commands which change these parameters, and the effect will be limited to the footnote text. The actual space taken by the footnote may be more or less than that specified by n. The n merely allocates space and should be the user's best guess. If it is considerably off, the footnote lines may overflow the page, or extra space may be left at the bottom. The user may wish to adjust n after examining a first draft printout. .INDEX tttt ... tttt .X tttt ... tttt This command takes the remaining text on the line as a key word or words and adds it, along with the current page number, to the internal index buffer. The command does not cause a break. It should appear immediately before the item to be indexed. A key word or words may be indexed more than once. .PRINT INDEX .PX Causes a break after which it prints the entire contents of the index buffer. Entries are printed in alphabetical order, and are set against the 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, beginning at the middle of the line (midway between the left and right margins). Additional page numbers for multiple entries follow, separated by commas. The index buffer is left empty. PDP-11 RUNOFF Page 13 22 Nov 78 APPENDIX A - Command Summary B BLANK n BR BREAK C CENTER n D DATE FG FIGURE n F FILL FN FOOTNOTE n I INDENT n X INDEX ttt ... ttt J JUSTIFY LM LEFT MARGIN n LC LOWER CASE ND NODATE NF NOFILL NJ NOJUSTIFY NNM NONUMBER NM NUMBER PG PAGE PS PAPER SIZE n,m P PARAGRAPH n PX PRINT INDEX RM RIGHT MARGIN n S SKIP n SP SPACING n ST SUBTITLE ttt ... ttt TS TAB STOPS n ... n TP TEST PAGE n T TITLE ttt ... ttt UC UPPER CASE PDP-11 RUNOFF Page 14 22 Nov 78 APPENDIX B - Help Message GENERAL COMMAND FORMAT IS: DEV:OUTFIL=DEV:INFIL1,DEV:INFIL2.../S1/S2... INPUT DEFAULT EXTENSION IS .RNO OUTPUT DEFAULT EXTENSION IS .DOC LEGAL SWITCHES ARE: /F:N. - SIMULATE FORMFEEDS WITH LINEFEEDS TO MAKE PAGE 'N.' LINES LONG (DEFAULT 66.) /H - HYPHENATE WORDS AS NECESSARY TO JUSTIFY LINES (N.B. HYPHENATION MAY NOT BE CORRECT) /L:N. - LIMIT - PRINT PAGE N. ONLY /L:M.:N. - LIMITS - PRINT FROM PAGE M. TO N. /P - PAUSE BETWEEN PAGES (TYPE ANY CHAR TO CONTINUE) /U - UNDERSCORE BY OVERPRINTING LINE (DEFAULT) /U:B - BACKSPACING UNDERSCORE /U:C - NON-SPACING UNDERSCORE /U:S - NEXT LINE UNDERSCORE WITH - /U:N - SUPPRESS UNDERSCORES /? - PRINT THIS TEXT PDP-11 RUNOFF Page 15 22 Nov 78 APPENDIX C - Sample RUNOFF input file !SAMPLE OF RUNOFF SOURCE FILE. .LEFT MARGIN 5 .RIGHT MARGIN 70 1.0 ^^INTRODUCTION\\ .PARAGRAPH ^^RUNOFF\\ IS A ^^PDP-11\\ PROGRAM RUNNING UNDER ^^RT-11\\ THAT ENABLES YOU TO PREPARE DOCUMENTS EASILY IN CONJUNCTION WITH A TEXT EDITOR. ^BY INSERTING ^^RUNOFF\\ COMMANDS AND SPECIAL CHARACTERS WITH YOUR TEXT YOU CAN FORMAT YOUR MATERIAL WITH A MINIMUM OF EFFORT. .PARAGRAPH ^YOU CAN USE THE ^^RT-11 EDITOR\\ TO INPUT YOUR DOCUMENTS. ^DURING INPUT YOU NEED NOT WORRY ABOUT SPACING BETWEEN WORDS, JUSTIFYING LINES, CASE SHIFTING, PAGE NUMBERING, AND OTHER FORMATTING CONSIDERATIONS. ^^RUNOFF\\ DOES ALL THESE THINGS FOR YOU. ^BECAUSE YOU ADD CERTAIN COMMANDS WITH YOUR TEXT, ^^RUNOFF\\ CAN TAKE YOUR FILE AND REPRODUCE IT ACCORDING TO YOUR SPECIFICATIONS. .PARAGRAPH ^IF YOU MUST MAKE CHANGES TO YOUR FILE, YOU DO SO WITH THE ^^EDITOR\\. ^AFTER YOU MAKE YOUR CORRECTIONS, YOU RUN YOUR FILE THROUGH ^^RUNOFF\\, AND YOUR DOCUMENT IS AGAIN IN THE PROPER FORMAT. ^ONCE YOUR DOCUMENT IS READY, YOU CAN REPRODUCE IT EITHER .SKIP;.NOFILL;.TAB STOPS 20 1. ^INTO ANOTHER FILE, 2. ^ON YOUR TERMINAL, OR 3. ^ON A LINE PRINTER. .SKIP;.FILL;.PARAGRAPH ^BY USING ^^RUNOFF\\ YOU CAN UPDATE YOUR DOCUMENTATION AND MAKE IT LOOK PRESENTABLE WITHOUT EXTENSIVE RETYPING. PDP-11 RUNOFF Page 16 22 Nov 78 This page was produced by the sample input file. 1.0 INTRODUCTION RUNOFF is a PDP-11 program running under RT-11 that enables you to prepare documents easily in conjunction with a text editor. By inserting RUNOFF commands and special characters with your text you can format your material with a minimum of effort. You can use the RT-11 EDITOR to input your documents. During input you need not worry about spacing between words, justifying lines, case shifting, page numbering, and other formatting considerations. RUNOFF does all these things for you. Because you add certain commands with your text, RUNOFF can take your file and reproduce it according to your specifications. If you must make changes to your file, you do so with the EDITOR. After you make your corrections, you run your file through RUNOFF, and your document is again in the proper format. Once your document is ready, you can reproduce it either 1. Into another file, 2. On your terminal, or 3. On a line printer. By using RUNOFF you can update your documentation and make it look presentable without extensive retyping. PDP-11 RUNOFF Page 17 22 Nov 78 APPENDIX D - Assembling & Linking RUNOFF RUNOFF is assembled and linked in a fairly straight-forward fashion. The current source file is named RUNOFF.MAC, while the source file for HYPHEN is named HYPHEN.MAC. Assembly-time switches are: HYP which controls the interface between RUNOFF and HYPHEN, and DBLBUF which sets up double buffering of the output file. Default values of these switches are: HYP=1 and DBLBUF=1 allowing both hyphenation and double buffering. Thus, to assemble and link RUNOFF with the default options, one would use the following commands: (RT-11 V02C) (RT-11 V03B) .R MACRO EXECUTE/NORUN RUNOFF,HYPHEN *RUNOFF