RUNOFF BONNER LAB version - ii - TABLE OF CONTENTS CHAPTER I INTRODUCTION 1 CHAPTER II RT11/TSX OPERATING PROCEDURES 2 II.1 INITIATING RUNOFF 2 II.2 COMMAND STRING 2 CHAPTER III SOURCE FILE FORMAT 6 III.1 CASE INFORMATION 6 III.2 SPECIAL CHARACTERS 7 CHAPTER IV INTRODUCTION TO THE COMMANDS 11 CHAPTER V RUNOFF COMMANDS 16 V.1 BASIC TEXT FORMATTING 18 V.2 FOOTNOTE / NOTE 21 V.3 PAGE FORMATTING 23 V.4 PAGE HEADERS 26 V.5 LISTS 29 V.6 CHAPTER/APPENDIX FORMATTING 31 V.7 SECTION HEADERS 32 V.8 NUMBERING 34 V.9 DISPLAY COMMANDS 36 V.10 MODE SETTING 39 V.11 PARAMETER SETTING 46 V.12 TAB STOPS 49 V.13 FLAGS 54 V.14 ENABLE/DISABLE 60 V.15 DEFINE, DELETE, AND RESET 66 V.16 MISC COMMANDS 75 V.17 SAVE/RESTORE COMMANDS 77 V.18 INDEXING 78 V.19 TABLE OF CONTENTS 81 V.20 EQUATION FORMATTING 83 V.21 CONDITIONAL TEXT 86 APPENDIX A RUNOFF LIMITATIONS 91 APPENDIX B RUNOFF ERROR MESSAGES 92 APPENDIX C BUILDING RUNOFF 100 APPENDIX D SPECIAL CHARACTERS 109 APPENDIX E LIST OF COMMANDS (ALPHABETICAL) 111 APPENDIX F RUNOFF (SPALDING VERSION) 121 APPENDIX G SPECIAL PRINTER SUPPORT 123 INDEX 125 - iii - RUNOFF Revision Date: July 1985 Program Version: BL8.0 Document Printed : 22 Jan 86 23:15:05 NOTICE: This document describes a program that Digital Equipment Cor- poration has no commitment to offer or support at this time. This docu- ment is believed to be an accurate description of RUNOFF. Feel free to distribute this program to other users, but please do not sell it. This version of RUNOFF is a major rewriting of RNO. The revisions es- sentially add almost all features from DSR to RUNOFF while maintaining compatibility. There are 3 known incompatible changes, to the .CENTER, .NUMBER, and .FOOTNOTE commands. The additions include the .REQUIRE command, overstrike capability, and escape sequence handling. A macro facility via the SUBSTITUTE flag has been added and permanent margins are also implemented. The permanent margins can cause incompatible out- put with respect to the headers if they are not set. In addition, all FLAGS are redefinable, and all can be enabled/disabled. The escape se- quence handling has been designed to give the user the ability to define arbitrary sequences, and intermix them with standard RUNOFF text. Since both this version of RUNOFF and previous versions use ASCII non printing characters internally, including such characters in your input file can be disastrous. To prevent this, all such characters with the exception of CR, LF, TAB are ignored. The philosophy of this version of RUNOFF has been to create a program that can handle virtually any printer with minimal support for any specific printer. As a result, general mechanisms have been included for printer control, but only suggested escape sequence definitions have been added as part of the permanent escape sequence table. The maximum size page is 127 lines by 255 characters (21 by 25 inches). This should be adequate for all but the most perverse applications. You are welcome to make modifications and additions to the this version. There are hints in INTERNALS.DOC and also in the section on building RUNOFF. I would appreciate a copy of any mods, so they can be incor- porated into future distributions. If you have any problems with this version, I will be glad to answer your questions. I do not guarantee that all errors can be patched. I will try to maintain this version and release new versions with most bugs fixed and some enhancements added. This program runs on RSX/IAS/VMS/RT/TSX and presumably RSTS. The RT version was prepared by Gary McMillian, a graduate student here at the Rice Physics department, and is now being maintained by the DECUS RT-11 SIG. - iv - John Clement T. W. Bonner Nuclear Lab Rice University P.O. Box 1892 Houston, Tx, 77251 Tel (713) 527-4018 CHAPTER I INTRODUCTION RUNOFF is a text formatting program that facilitates the design and pro- duction of printed documents such as memos, letters, manuals, etc. Input to RUNOFF is a file containing the text of the document, case and formatting information, and other pertinent information such as how lines should be justified, how pages should be numbered and titled, and so forth. The output from RUNOFF is a ready-to-print document. After a input file has been processed, it remains available for further editing. The formatting information consists of commands and flags. Command lines are signalled by a period in the first position and may contain one or more commands and text. Within the text are special characters, called flags, that specify character modifications such as underlining or bolding. RUNOFF reduces the amount of interaction needed for preparation of a do- cument by allowing both textual correction and formatting changes to be executed in one pass through the source file. And since text changes do not effect the basic design, documents can be updated without extensive retyping. - 1 - CHAPTER II RT11/TSX OPERATING PROCEDURES II.1 INITIATING RUNOFF RUNOFF can be initiated by any standard means. The .SAV image file must be present to run the program. Also, sufficient memory space must be available to accomodate RUNOFF code and data. If the program will not load and run, it must be relinked to overlay parts of the program from disk. If the program loads and runs but will not process input files, there may not be sufficient dynamic memory (memory that is used by RUN- OFF to temporarily store indices, footnotes, substitutions, etc.). If this is the case, then the program must be relinked to make more memory available for temporary storage. If this fails, then the program is probably too large to run on your system. RUNOFF can be started by typ- ing RUN DEV:RUNOFF.SAV or @COMMND.COM where DEV: is the device on which the RUNOFF.SAV file is found, and COMMND.COM is a command file that initiates RUNOFF and might or might not contain file specification information. II.2 COMMAND STRING The program will prompt you for a command string. The command string specifies the names of the input and output files and any options that you might select at run time. The standard command string (for further information look at the .CSIGEN macro in the Programmer's Reference Manual) should be entered in the following form: output-file,toc-file=input-file,input-file,,,,input-file/options where output-file is the document to be produced by RUNOFF, toc-file is a table of contents file that can be edited before it is reprocessed by RUNOFF to produce a table of contents, and input-file is a file contain- ing text and RUNOFF commands to control the format of the output-file and the toc-file. Up to six input-files can be concatenated to produce a single document file. Each input file is processed sequentially and no parameters are reset between files. This feature allows control files for different printers to be processed prior to the text. Users should construct a control file for each printer with the appropriate escape sequence definitions and printer specific RUNOFF commands such as .PAPER SIZE. Thus, no file editing will be required to print documents on two printers or terminals that have different capabilities. Also, - 2 - CHAPTER: RT11/TSX OPERATING PROCEDURES - RUNOFF - 3 - SECTION: COMMAND STRING - 22 JAN 86 control files can be built to set parameters for different types of do- cuments (for example: business letters, technical documentation, or a masters thesis). For example: DK:THESIS,DK:THESIS=DK:SPIN,DK:CONTRL,DK:THESIS where SPIN will define escape sequences for a NEC Spinwriter printer and set the paper size, and CONTRL will contain RUNOFF commands to format the document in the customary thesis form. The toc-file can be omitted if no table of contents is desired. The available options can be printed on the user's terminal by entering only a /I in response to the CSI prompt. The user can exit from the program back to the operating system by typing a /X. II.2.1 FILE SPECIFICATIONS A valid file specification has the form: DEV:FILNAM.EXT DEV: must be a legal device code. The default device code is DK:, where DK: can be assigned to any device on the system. The output-file, toc-file, and input-files can be on different devices. FILNAM can be any 1 to 6 character alphanumeric string and EXT can be any 1 to 3 character alphanumeric string. FILNAM and EXT must be separated by a period. The default EXT's are RNO for the input-files, DOC for the output-file, and RNT for the table of contents file. If you use the default EXT's, only the FILNAM need be specified. The table of contents file must be processed by RUNOFF as an input-file to produce a table of contents (or DOC file). Editing RUNOFF Input and Output The DOC file can be edited prior to printing using any stan- dard RT11 text editor. The RNT file can be edited to change the contents or format of the table of contents to be produced by RUNOFF. Due to the manner in which RUNOFF processes text files (line by line), no single input line can be more than 512 characters long. A line is defined as text terminated by a carriage re- turn and a line feed. A line might consist of several sen- tences or part of a single sentence. It is good practice (to facilitate future editing) to enter only single sentences separated by a carriage return and a line feed. Sentences longer than one screen width can contain as many carriage re- turn - line feed combinations as necessary. CHAPTER: RT11/TSX OPERATING PROCEDURES - RUNOFF - 4 - SECTION: COMMAND STRING - 22 JAN 86 II.2.2 OPTIONS The command string can have one or more switch options associated with it. A switch option consists of a / and a single ASCII character. Some switch options can be followed by a colon and a decimal number or an ASCII character. Any decimal number can be preceded by a + or - sign, and must be followed by a period. The valid switch options are: /P:l:h Output only the indicated page range. l = lowest page to print h = highest page to print This option should be used in conjunction with the /A and /C options for chapter oriented text. /C:l:h Output only the indicated chapter range. /A:l:h Output only the indicated appendix range. /G Force all text to be output in uppercase. /G:N Allow all text to be output as it is input. /F Use the standard ascii formfeed character. /F:n Simulate the formfeed character with multiple linefeeds. n = paper length /H Hyphenate output. /H:N Do not hyphenate output. Note: This switch overrides .ENABLE HYPHENATION. /R:n Right shift output n spaces. Useful for output that is to be bound. /S:h:w Set hardware page size. h = height of page w = width of page /U:B Underline with underline character and backspace. /U:L Underline with underline character and line overprint. /U:S Underline with hyphen on next line. /U:N Do not underline text. Note: This command overrides the enable underline command. /W Wait for carriage return between pages. /W:N Do not wait for carriage return. /I Print available switch options on terminal. /E Output even pages. /E:N Do not output even pages. /O Output odd pages. /O:N Do not output odd pages. /X Exit program and return to operating system. CHAPTER: RT11/TSX OPERATING PROCEDURES - RUNOFF - 5 - SECTION: COMMAND STRING - 22 JAN 86 /2 Perform 2 passes. /2:N Perform 1 pass. /M Output warning messages. /M:N Suppress warning messages. Default values are: /G:N/F/H/R:0./S:58.:60. /U:L/W:N/E/O/M/2:N (print all) CHAPTER III SOURCE FILE FORMAT The source file contains the textual material that will appear on the final copy, plus information to specify formatting. All command infor- mation consists of regular ASCII printing characters, so a listing of the source file can 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 as- sumed to be a command, and must match one of those listed in the chapter on commands. The commands provide the formatting information and con- trol various optional modes of operation. III.1 CASE INFORMATION NOTE The following section explains how to change the case of the input text. If your terminal has a shift key you, do not need to read this section. Case is specified by the the circumflex (^) and the back-slash (\) characters. The appearance of a circumflex causes the letter im- mediately 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 preceded by one of these characters is transmitted in the current mode. The mode is initially upper case, and is changed by the occurance of two successive case control characters. Two circumflexes (^^) cause the mode to be set to upper case, and two back-slashes (\\) cause the mode to be set to lower case. When the text is in upper case mode (^^), the text is printed exactly as typed, i.e., no case conversion occurs. If in lower case mode (\\), however, all text is converted to lower case except where explicitly specified as upper case by a single upper shift character (^). The following example illustrates the use of the case control characters: H\\ERE IS A ^SAMPLE ^SENTENCE IN ^^UPPER CASE\\ AND LOWER CASE. becomes: Here is a Sample Sentence in UPPER CASE and lower case. - 6 - CHAPTER: SOURCE FILE FORMAT - RUNOFF - 7 - SECTION: CASE INFORMATION - 22 JAN 86 If the .FLAGS CAPITALIZE comand has been issued, the capitalization flag, less-than (<), is enabled, and any word it precedes will be capitalized. After the word, the case mode returns to its previous value. If the capitalization character is enabled, a whole section of text can be capitalized by inserting ^< in front of the text and ^^ after the text. As with the lower case lock, a single character can be forced to lower case rather than upper case by preceding it with (\). These case change control symbols always override the actual case of the input text and the implied case of a command. For example, the command .HEADER LEVEL would normally produce a capitalized title for level number 1. This can be changed by preceding the title with \\ to force it to lower case. III.2 SPECIAL CHARACTERS & Ampersand UNDERLINE The character ampersand "&" is used to specify underlining. The ampersand will cause the character following it to be underlined, e.g. &f&o&o becomes foo. To begin underlining a whole section of ___ text, precede the section by ^& and follow the section by \&. Any spaces in the section will not be underlined. To underline a sin- gle space or tab, precede it by &. Text with imbedded spaces can be underlined, spaces and all, by issuing the command .UNDERLINE " ". You can specify which characters will or will not be under- lined with the .UNDERLINE and .NO UNDERLINE commands. (In DSR, you underline spaces by preceding them with an accept flag "_".) # Number-Sign Quoted or non expandable SPACE It is sometimes necessary to include spaces that should not be treated as word separators. For this purpose, RUNOFF treats the number-sign character "#" as a quoted space; i.e. it will produce exactly one space in the output. Normal spaces might be expanded to multiple spaces to justify the text, but quoted spaces will not be expanded. Also, normal spaces mark the end of the previous word and the beginning of the next. Text with imbedded quoted spaces are not be broken at the quoted spaces or split into separate lines. _ Underline ACCEPT or Quote character The underscore character "_" is used as an accept flag to allow the appearance of the special characters (ampersand, number-sign, cir- cumflex, or back-slash) in the output. The character immediately following an underscore will be transmitted to the output with no formatting effect. The underscore itself is a special character requiring quoting. The following 12 cases occur: _& _^ _\ __ _$ _| _= _% _< _# _{ _} If normal spaces or tabs are preceded by an ACCEPT character, they are converted to non-expandable spaces. CHAPTER: SOURCE FILE FORMAT - RUNOFF - 8 - SECTION: SPECIAL CHARACTERS - 22 JAN 86 ^ Circumflex UPPERCASE shift or mode lock As described above, the circumflex character "^" is used to convert the letter following to upper-case. It is also used to lock the case mode to upper case, and the underline mode to "underline all text". If ^ is to appear in the printed text, it must be preceded by the quote character "_^". User-defined special flags can be locked on using the circumflex. For example, if your printer sup- ports bolding, "^*" would be used to turn on bolding. \ Backslash LOWERCASE shift or mode unlock As described above, the backslash character "\" is used to convert the letter following to lower-case. It is also used to lock the case mode in lowercase, and to disable underlining. If a backslash is to appear in the printed text, it must be preceded by the quote character "_\". The backslash is also used to turn off special features. For example, "\*" would be used to turn off bolding if your printer supports it. < Less-than CAPITALIZE next word If .FLAGS CAPITALIZE has been defined, the less-than character "<" will capitalize the entire word it precedes. If < is to appear in the printed text, it must be preceded by the quote character "_<". An appearance of a circumflex followed by less than "^<" per- manently locks RUNOFF into capitalize mode. This mode can be can- celled by a double circumflex "^^". This flag is not normally used with terminals that have lowercase. = Equals-sign HYPHENATE character If .FLAGS HYPHENATE has been specified, the equals character "=" is used to control hyphenation. If it precedes a word, the word will not be hyphenated. If it is imbedded inside a word, it specifies where that word can be hyphenated. The word is only hyphenated if necessary to fill out a line. When hyphenation is specified for a word, no automatic hyphenation is used. When the hyphenate flag appears at the end of a line, it specifies that the next line is a continuation of the current one and that a hyphen may appear at this point. If = is to appear in the printed text, it must be pre- ceded by the quote character "_=". % Percent-Sign OVERSTRIKE character If .FLAGS OVERSTRIKE has been defined, the percent character "%" will generate a backspace to allow overstriking of the previous character to form new composite characters. If overstriking is de- fined and you wish to use the percent character in the text, it must be preceded by an underscore "_%". The default is .NO FLAGS OVERSTRIKE. Multiple backspaces can be generated, but you should be careful when using this feature: backspacing past the left margin is not allowed, and some printers do not support backspacing. (DSR doesn't support multiple backspacing) CHAPTER: SOURCE FILE FORMAT - RUNOFF - 9 - SECTION: SPECIAL CHARACTERS - 22 JAN 86 + Plus PERIOD character If .FLAGS PERIOD has been defined, the plus-Sign "+" will generate an extra space when followed by a normal space. For example J+ M will appear in the output as J M. . Period CONTROL character If a period appears at the beginning of a line, it indicates that the rest of the line is a control or command. $ Dollar-Sign SUBSTITUTE character If .FLAGS SUBSTITUTE has been enabled, the dollar sign marks the beginning of a substitution label. RUNOFF will then substitute the text specified by a .DEFINE SUBSTITUTE command for the label. Per- manently defined substitutions are already in affect for the cur- rent date and time. See: .FLAGS SUBSTITUTE. | Vertical bar BREAK character If .FLAGS BREAK is enabled, this character indicates where a word or expression may be broken. A word containing a break will not be hyphenated, but will be broken if necessary. Words may contain both specified hyphenation and break points. You can automatically specify breaks on a character by using the .AUTOBREAK command. If .TAB RIGHT is enabled, this flag also marks where a string is justified. If the break character appears at the end of a line, it specifies that the next line is a continuation of the current one. > Greater than INDEX/SUBINDEX flags If .FLAGS INDEX is enabled, this character can be used to mark terms to be indexed. If .FLAGS SUBINDEX is enabled, the character can be used inside an .INDEX command to denote subindex terms. For further explanation, see the section on indexing. { } Braces EQUATION formatting characters If .FLAGS EQUATION is enabled, these characters are used to delimit either the numerator or denominator of a fraction. The numerator and denominator are further separated by a slash "/". (Not available in DSR) ???? User defined flags The user can define any other special character as a flag by using the .FLAGS SPECIAL or .FLAGS ESCAPE commands. Any flag so defined obeys the printing rules defined above. The meaning of the flag is entirely up to the user. (Not available in DSR) NOTE All of the above flags can be undefined by a .NO FLAGS command. They can be defined and changed to a different CHAPTER: SOURCE FILE FORMAT - RUNOFF - 10 - SECTION: SPECIAL CHARACTERS - 22 JAN 86 character by a .FLAGS command. For example, if you use the equals sign frequently, you can change the hyphena- tion flag to the seldom used tilde. This is done by en- tering the following line: .FLAGS HYPHENATE ~ CHAPTER IV INTRODUCTION TO THE COMMANDS When you first use RUNOFF, the wealth of available commands may seem confusing, but you will find this wealth can be used to speed the crea- tion of documents. The first thing you should learn is how to create simple documents such as letters. For this you will need the following commands: 1. .RIGHT MARGIN sets the right margin. 2. .LEFT MARGIN sets the left margin. 3. .TOP MARGIN sets the top margin. 4. .PAGE SIZE combines all the above, and sets the page length. This command should always be used if you wish to produce docu- ments with numbered pages. 5. .PARAGRAPH starts paragraphs. 6. .CENTER centers a line of text. 7. .RIGHT right justifies a line of text. 8. .INDENT indents the next line. 9. .SPACING sets the spacing to single, double, triple .... 10. .HALF SPACING enables in-between spacing such as 1&1/2, 2&1/2 .... (Only works on some printers.) 11. .SKIP skips a line (or 2, if double spacing, 3 etc.) In other words, it skips lines according to the spacing selected. 12. .BLANK skips multiple lines independent of spacing. 13. .FIGURE or .FIGURE DEFERRED reserves n lines, independent of spacing, for inserting drawings, or other artwork later. 14. .BREAK starts a new line. This is called breaking the text. 15. .PAGE starts a new page. 16. .FILL automatically fills each line with words until no more will fit. 17. .JUSTIFY pads the text with spaces so that each line is justi- fied at the right margin. 18. .AUTOHYPHENATE causes long words at the end of a line to be au- tomatically hyphenated. The task of setting up paragraphs can be simplified by using the .AUTOPARAGRAPH command. Once this command has been given, any line pre- ceded by a blank, tab, or a blank line automatically starts a new paragraph. When this command is used, the input text can be formatted to "look" like the final document. The .SET PARAGRAPH command can be used in conjunction with the .AUTOPARAGRAPH to control the format of each paragraph. - 11 - CHAPTER: INTRODUCTION TO THE COMMANDS - RUNOFF - 12 - A frequently asked question is: How do I do bibliographies or tables? This can be done by setting up a negative indentation and adding the same indentation to the left margin. As a result, every time you begin a paragraph, the line will start on the old left margin, and the text will be indented. EXAMPLE: the input ________ ___ _____ .left margin +5. set paragraph -5 .p;_.SET PARAGRAPH [-indent],[-skip],[test page] .BR;sets the format produced by the _.PARAGRAPH command, the _.AUTOPARAGRAPH, or _.AUTOTABLE feature. The indentation can be either positive or negative. produces the following text ________ ___ _________ ____ .SET PARAGRAPH [-indent],[-skip],[test page] sets the format produced by the .PARAGRAPH command, the .AUTOPARAGRAPH, or .AUTOTABLE feature. The indentation can be either positive or negative. You can control the overall look of the pages with the .HEADER, .LAYOUT, and .TITLE/.SUBTITLE commands. The default page format is to place a title, subtitle, and page number at the top of the page. The location of the title/subtitle and the page number can be varied using the .LAYOUT command, which allows 17 different placements. The title and subtitle can be specified by the .TITLE or .SUBTITLE command. If no ti- tle is specified, none appears. The .NO TITLE command will suppress both the title and subtitle without suppressing the page number. The .NO HEADER command, on the other hand, will suppress title,subtitle, and page number. The .DISABLE NUMBERING command will suppress the page number without affecting the title/subtitle. Normally the page number is preceded by the word "Page". To display only a number with no extra word, use the .DISPLAY NUMBER command. The .DISPLAY NUMBER command can be used to substitute some other text for the word "Page", and can be used to add extra text after the page number. For example, .DISPLAY NUMBER could be used to number the pages of a 4 page document as 1/4,2/4,3/4,4/4. The .DISPLAY command can be used to switch page numbers to other forms. Normally the first page of a document will not have the title/subtitle printed on it. This can be changed with the .FIRST TITLE command. A common problem with formatting text is deciding how to arrange it on each page. For example, you may wish to force a particular section of text to fall all on the same page rather than have it possibly be split between 2 pages. This can be achieved using the .TEXT and .END TEXT commands. An alternate way to guarantee a fixed number of lines all on the same page is to use the .TEST TEXT command or the .TEST PAGE command. You should be aware that the .PARAGRAPH command has an au- tomatic .TEST TEXT built into it. You may wish to reserve part of a page for a figure with a caption. This is easily achieved with the .TEXT DEFERRED and .END TEXT commands. If there is not enough space on the current page for the text between these commands, the text will be stored and reproduced on the next page CHAPTER: INTRODUCTION TO THE COMMANDS - RUNOFF - 13 - that has enough space. You can reserve a whole page by using .TEXT DEFERRED and .PAGE to complete the reserved text. Several captioned figures can be generated and mixed with text in this way without without leaving partial pages blank. After you are able to format a letter or simple few page document, you will want to learn more advanced techniques. If you need to produce lists, such as the list above of simple commands, you can use the com- mands .LIST, .LIST ELEMENT, and .END LIST. These commands make creation and modification of lists simple and perhaps even enjoyable. 1. .LIST is used to begin a list. 2. .LIST ELEMENT starts each entry in the list. To insert more entries in the list, you need only insert a new .LIST ELEMENT command with the added text, and the list will be appropriately numbered. 3. .END LIST terminates the list. If you need to produce lists preceded by Roman numerals or letters rather than numbers the .DISPLAY ELEMENTS command allows you to change the list format. If you are dealing with a large document, you should consider breaking it up into sections. A master file for creating the entire document can be created using a .REQUIRE "filename" command to include each of the sections of the document. You could reshuffle the order of the various sections latter simply by rearranging the order of the .REQUIRE state- ments in the master file. Whenever a document is to be longer than a single page, you should consider breaking it up into sections. You can also divide a large document into chapters and appendices with the .CHAPTER and .APPENDIX commands. These commands automatically format the beginning of each chapter or appendix in an identical fashion and cause the chapters to be numbered in the order in which they occur. If you later need to insert a new chapter, the chapters are automa- tically renumbered. The "look" of the chapters can be modified by the .STYLE CHAPTER command. This command sets up the margins and placement of the chapter number and title. For some documents might want to have the page number placed in different locations depending on whether or not the current page is the first page of a chapter. The .CHAPTER LAYOUT command can be used to control the layout of the first page of each chapter independently of subsequent pages. .DISPLAY CHAPTER and .DISPLAY APPENDIX can be used to select either letters, roman numerals, or normal Arabic numerals for numbering the chapters and appendices. Whenever a document is chapter oriented, the page numbers are printed as chapter-page. For example, the 5th page in chapter 2 would be numbered 2-5. If sequential page numbering without the chapter numbers is desired, then .DISABLE NUMBERING CHAPTER should be used. In addition to (or instead of) dividing a document into chapters, it may be necessary to divide it into sections of text that are headed by a section number followed by a title. A section number is a string of numbers separated by periods. For example, 3.2.5 or 1.2. A string of 3 numbers is called a third header level, 2 numbers a second and 1 the first. You can automatically generate headers with the .HEADER LEVEL command. This command allows you to easily insert additional sections because RUNOFF will automatically renumber the remaining sections correctly. Headers can be reformatted with the .STYLE HEADERS command, CHAPTER: INTRODUCTION TO THE COMMANDS - RUNOFF - 14 - which controls the spacing and placement of the headers. In addition, the .INDENT LEVELS command indents the left and right margins of the headers as desired. If you need to use letters or Roman numerals in- stead of normal decimal numbers, you can use the .DISPLAY LEVELS command to change the type of numeral. You may want to have the sections of a document defined in outline form. That is, instead of numbering sections a.b.c... you wish to use large letters for level 1, numbers for level 2, and small letters for level 3. This can be accomplished with the .STYLE HEADERS and .DISPLAY LEVELS commands. The STYLE command can be used to suppress the a.b.c form of numbering and the DISPLAY command can be used to specify the numbering format. In addition, the section title can be centered, underlined, and capitalized automatically. The next page number or chapter number can be assigned with the .NUMBER commands. Subpage numbering can also be performed. Subpage numbering allows extra pages to be inserted without having to reformat and reprint the whole document. For example, after page 12 you could insert sub- pages 12A, 12B, and 12C by using the .SUBPAGE and .END SUBPAGE commands. The actual subpage number can be specified with the .NUMBER SUBPAGE command. The .NUMBER commands can be used to skip page numbers. It is also possible to format only selected pages and chapters by using the /C, /A, and /P switches. If you need to reproduce your document in in book form with both sides of the paper printed, there are several commands to aid you. The .ENABLE ODD command forces the first page of each chapter onto an odd numbered page. .PAGE ODD or .PAGE EVEN can be used to pick which page you wish to have next. In addition, you can select only odd or even page output with the /O or /E switches. By splitting your document into odd and even pages you can first print out the odd pages, then reinsert the paper and print the even pages on the other side of the paper. The /R switch can be used to move the text over to account for an extra binding margin. Text can be underlined by using the underline flag. Underlining is af- fected by the .FLAGS UNDERLINE, .ENABLE UNDERLINING and .DISABLE UNDER- LINING commands. Normally only printable characters are underlined; the space character is not normally underlined. To cause it (or any other non-underlined character) to be underlined, you can use the .UNDERLINE command to define it as underlinable. Likewise, if you never want to underline certain characters, such as punctuation or numbers, you can define them not underlinable with the .NO UNDERLINE command. A whole cornucopia (or Pandoras box) of additional features can be con- trolled with the .FLAGS commands. These commands allow you to enable and redefine special symbols to perform various functions such as under- lining, capitalization, hyphenation, overstriking, breaking, and substituting. The .ENABLE or .DISABLE commands let you control when these features are used. (See the section on SPECIAL CHARACTERS.) Most of these features are self explanatory. Three of them are worth men- tioning here. 1. OVERSTRIKING is where more than one symbol is printed at the same spot. For example, overstriking an oh "O" with a minus sign "-" can produce the Greek letter theta. CHAPTER: INTRODUCTION TO THE COMMANDS - RUNOFF - 15 - 2. BREAK is a special way of telling RUNOFF where it may break a line as opposed to hyphenating it. It is also used to control tabulation. (See also the AUTOBREAK command.) 3. SUBSTITUTION allows abbreviations to be defined for long or commonly used lines of text, numbers, or symbols. Substitution can be used to create complex symbols that can be printed on special line printers. See .DEFINE SUBSTITUTE, .RESET SUBSTI- TUTE, .FLAGS SUBSTITUTE, and .ENABLE SUBSTITUTION If you need to number various items in the text, such as footnote numbers, figure numbers, table numbers, and equation numbers, you can set up such numbers and increment them with the .DEFINE ITEM and .NUMBER ITEM commands. You can also set up substitution labels for various reference numbers such as a chapter, section, appendix, or item number with the .DEFINE NUMBER commands. Typing a table in column format can be onerous task, even with the tab stops on a typewriter. RUNOFF contains tab stops that are settable by the .TAB STOPS and .TAB PROPORTIONAL commands. In addition, you can right justify columns or even center justify columns using the .TAB STOPS command. The .AUTOBREAK command will allow you align columns of numbers along the decimal point. (see the TAB command for examples.) Items can be connected by ellipses to guide the eye. The .ELLIPSES com- mand will cause ellipses rather than spaces to appear whenever you tab to the next item. RUNOFF can automatically take care of footnotes. The .FOOTNOTE command allows you to type the footnote at the same point it is referenced, but have it appear at the bottom of the page. RUNOFF can also produce an index and a table of contents for your document. Finally, a few special features should be mentioned that may be avail- able if you have a word processing style printer: 1. EQUATION FORMATTING allows you to easily format equations to be typed equations on the printer. 2. VARIABLE SPACING improves the look of the output when you right justify the text by balancing the white space throughout the line. Since this version of RUNOFF is almost the same as Digital Standard Run- off (DSR), the DSR manual can be used as a guide to most of the basic features. However, many advanced features in this version are not available in either DSR or any other version of RUNOFF. VAX/VMS users may prefer this version to DSR because of the extra features available for customizing documents. For those who use VAX/VMS and either RSX, RT, or IAS, this version of RUNOFF is particularly convenient because it runs essentially transparently on all these systems. (DEC does not sup- port RUNOFF or DSR on RSX, RT, or IAS, so users of these systems have no other choice but to use one of the versions of RUNOFF available through DECUS.) CHAPTER V RUNOFF COMMANDS This chapter contains a list of all RUNOFF commands. You may not want to read all of this chapter, as it is intended to be a reference manual. If you have never used RUNOFF before, then you should read the chapter "INTRODUCTION TO THE COMMANDS". All commands begin with a period(.). Any line in the source file begin- ning with a period is assumed to contain one or more commands. If the text after the period is not recognized as a command, an error message is typed. Most commands have arguments following them. An argument is a number or string of text that controls how the command works. Multi- ple arguments can be separated by spaces, tabs, or commas. If the argu- ments are separated by commas, any number of tabs or spaces can appear before or after the comma. Certain conventions are used to describe the arguments of a command. If the argument is enclosed inside square brackets [], it can be omitted. Most arguments are numbers. If the number is preceded by a minus sign (-), it will be entered as a negative value. If it is preceded by +-, it is a relative argument. A relative argument changes the old value by + or - the value specified. Many arguments have limits. For example, page numbers must be within the range 1 to 3999. Each command documents the limits on its arguments. For example, the command .LEFT MARGIN 5, will set the left margin to ex- actly 5, whereas the command .LEFT MARGIN +5 will set the left margin to its old value plus 5, and .LEFT MARGIN -5 will set it to the old value minus 5. Some commands have literal arguments. A literal is a string of text en- closed in either apostrophes (') or quotes ("). If quotes are used to delimit the string and you wish to use a quote inside the string, you must use two quotes in a row. Similarly, if the text is enclosed in apostrophes, a double apostrophe within the text will be interpreted as a single apostrophe. For example legal literals are: '"legal" literal' """legal"" literal" Either of these will appear as: "legal" literal The following are not legal literals: 'illegal literal" 'illegal' literal' ''illegal literal' Tabs enclosed inside a literal are treated as single spaces. A literal is also terminated by the end of a line. (This termination might not be supported in future versions.) More than one command can be entered on a single line. The commands can be optionally separated by a semicolon ";", spaces, or tabs. If a semi- colon is used as a separator, the next command must immediately follow with no intervening spaces or tabs. A command that is followed by text - 16 - CHAPTER: RUNOFF COMMANDS - RUNOFF - 17 - must be the last command on a line, and cannot have other commands after it on the same line. These include: .APPENDIX .CHAPTER .FIRST TITLE .HEADER LEVEL .INDEX .LIST ELEMENT .REQUIRE .SEND .SUBTITLE .TITLE For example, the following is a legal set of commands all on 1 line: .TT 10 .Fill;.EH .Title GONE WITH THE WIND Commands can have text following them, provided the text is separated from the command by a semicolon (;). For example, the following line will produce a centered title. .C;THIS IS A TITLE When the semicolon is used as a separator, it indicates that the rest of the line is to be treated just as if a new line had begun. Many commands can be abbreviated. Standard abbreviations are given below each command. Many other abbreviations will work, but only the standard ones are guaranteed to work. Multi-word commands can appear without spaces. For example, the following forms of the .PAGE SIZE com- mand are all legal: .PAGE SIZE 20,20, 4, 1, 1 .PAGE SIZE 20 , 20 .PAGESIZE 20 20 .PS ,,1,2 .ps , , 1 2 .PAG SIZ 25 Many commands have defaults. In other words, if an argument is not specified, a default value of the argument will be used. It is possible to define your own commands. RUNOFF will search for ei- ther a standard command or a user defined command. To specify one or the other, preface a user command with an underscore "_" and a standard command with a dollar sign "$". For example, you might have a user com- mand called FIGURE, but there is also a standard command of the same name. To use your command, type ._FIGURE and to use the standard command, type .$FIGURE CHAPTER: RUNOFF COMMANDS - RUNOFF - 18 - V.1 BASIC TEXT FORMATTING .BLANK [-n] .B [-n] skips n absolute lines. .BLANK is like .SKIP, except that the number of lines skipped is independent of line spacing. If the page is empty, .BLANK does nothing. n can be negative to move to n lines from the end of the page. The maximum value of n is 127 for normal spacing and 255 for half spacing. .BLANK should not be used to skip lines to leave room for artwork or figures because no lines will be skipped if the current position is at the top of a page. Values of n that are negative or greater than 6 are not allowed in footnotes or text sections. .BLANK 6 will leave 1 inch of space on the page. DEFAULT: .BLANK 1 .BREAK .BR causes a break. That is, 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. | .BREAK LINE | .BRL | causes a break at the end of the next line. (Useful when defining | commands.) .CENTER [LINE][+-n] .CENTRE [+-n] .C [LINE] [+-n] causes a break, and centers the following line of text in the source file. If n is not specified, the centering will be halfway between the right and left margins. If n is specified as an ab- solute argument (no sign), the centering will be over column n. If n is a relative argument, the centering will be over the default center plus the relative value of n. If a .RIGHT command has been already specified for the current line, the .CENTER command will be treated as an error. Tab stops are converted to single spaces for centered lines. NOTE The definition of n differs from the previous version of RUNOFF and DSR. CHAPTER: RUNOFF COMMANDS - RUNOFF - 19 - SECTION: BASIC TEXT FORMATTING - 22 JAN 86 .CENTER TEXT [+-n] .C TEXT [+-n] .END CENTER .ECN centers lines of text that follow until an .END CENTER command is encountered. .CENTER TEXT differs from .CENTER LINE in that will center more than 1 line of text. Centering automatically prevents filling and justification. The argument n has the same meaning as for .CENTER LINE. (NOT available in DSR) .FIGURE [n] .FG n leaves n lines blank to make room for a figure or diagram. If fewer than n lines remain on the current page, the page is advanced and n blank lines are left at the top of the next page. .FIGURE guarantees that n blank lines will be generated, while .BLANK will does not if the position happens to be at the top or bottom of the page. If n is greater than the number of lines/page, an entirely blank page is produced. If a figure caption follows the figure command, it may not appear on the same page as the reserved space unless .TEST TEXT has been used to guarantee enough space. To guarantee the caption and figure are on the same page, use .TEXT. .FIGURE is not allowed during footnotes. If the current page doesn't have enough space for the figure, the rest of the page is left blank and n lines are left blank at the top of the next page. The maximum value of n is 127 for normal spacing and 255 for half spacing. DEFAULT: .FIGURE 1 .FIGURE DEFERRED [n] .FGD [n] reserves n lines on the current page, or, if there is not enough room, n lines at the top of the next page. This command differs from .FIGURE in that if there is no room for the figure on the cur- rent page, the current page will be filled with text right to the bottom line. Unlike .FIGURE, this command cannot be followed by the figure caption unless the .TEXT DEFERRED command is used. .FIGURE DEFERRED can not be used inside a footnote, note, or text section. The maximum value of n is 127 for normal spacing and 255 for half spacing. .FIGURE DEFERRED is equivalent to: .TEXT DEFERRED .BLANK n .END TEXT NOTE .BLANK, .SKIP, and .FIGURE are similar commands. If you want to leave 1 inch of space, .BLANK 6 would be appropriate. If you need 3 lines of space, .SKIP 3 is the correct command. If you need to leave space at the top of a page, or need a guaranteed amount of space, use .FIGURE or .FIGURE DEFERRED. When choosing between .SKIP and .BLANK, remember that .SKIP is appropriate if you are concerned with the number of text lines to skip, where CHAPTER: RUNOFF COMMANDS - RUNOFF - 20 - SECTION: BASIC TEXT FORMATTING - 22 JAN 86 text lines may be more than 1 physical line, whereas .BLANK is appropriate when the space to be left is an ab- solute value such as, for example, .5 inches (which is normally 3 physical lines). .INDENT [-n] .I [-n] .LEFT [-n] .L [-n] causes a break, and sets the next line to begin n spaces to the right of the left margin. If the value of n is negative, the next line will begin to the left of the left margin. However, a line cannot begin to the left of column 0. DEFAULT: .INDENT paragraph-indentation .PARAGRAPH [-n], [v], [t], [b] .P [-n], [v], [t], [b] causes a break, and starts a paragraph. If n is present, it speci- fies the number of spaces the paragraph is to be indented. (n can also have a negative value). v is the vertical spacing, or number of lines between paragraphs. v can range from 0 to 5. t is the TEST TEXT value. If there is not room for t lines on the page, a new page is started. b is the bottom test value. It specifies the minimum number of lines allowed on the next page. For example, if b is 2, then any paragraph that is split between two pages will have at least 2 lines on the second page. t and b are ignored dur- ing a text section or footnote. .PARAGRAPH is equivalent to: .SKIP v .INDENT n .TEST TEXT t,b (parameter b is not available in DSR) .SET PARAGRAPH [-n], [v], [t], [b] .SPR [-n], [v], [t], [b] sets the paragraph parameters without actually starting a paragraph. The parameters specified in this command also have an effect on the following commands: .PARAGRAPH .LIST ELEMENT .NOTE .PRINT INDEX .DO INDEX DEFAULT: .SET PARAGRAPH 5,1,2,2 .RIGHT [-n] .R [-n] breaks the line, and places the text that follows flush with the right margin if n is zero or unspecified. If n is specified, the text is placed n spaces to the left (n positive) or n to the right (n negative) of the right margin. If .RIGHT is issued after .CENTER or .CENTER TEXT, but before .END CENTER, the command will be rejected with a "conflicting command" message. Tab stops are converted to single spaces for right justified lines. CHAPTER: RUNOFF COMMANDS - RUNOFF - 21 - SECTION: BASIC TEXT FORMATTING - 22 JAN 86 .RIGHT TEXT [-n] .R TEXT [-n] .END RIGHT .ER begins a section of text all of which is to be right justified. Each input line after this command causes a break, until an .END RIGHT is encountered. .SKIP [-n] .S [-n] skips n spaced lines. The number of blank lines produced is n times the spacing. If the position is currently at the top of a page, .SKIP does nothing. If n is larger than the number of lines left on the page, a new page is started but no lines are skipped on it. The maximum value of n is 127 for normal spacing and 255 for half spacing. If n is negative, RUNOFF will skip n lines from the bottom of the page. Negative skips will work if the position is currently at the top of a page. Skip should not be used to leave room for artwork or figures; use .FIGURE or .TEXT instead. Nega- tive skips, or skips greater than 6, are not allowed during foot- notes or text sections. If n is not specified, it is assumed to be 1. If the spacing is 1, .SKIP 6 will leave 1 inch of space. If the spacing is 2 or 3, then 2 or 3 inches will be left. DEFAULT: .SKIP 1 V.2 FOOTNOTE / NOTE .FOOTNOTE .FN saves space for a footnote. When the bottom of the page is reached, the text following the .FOOTNOTE command will be printed. If insufficient room remains on the current page, the footnote con- tinues at the bottom of the following page. The text of the foot- note begins on the line following the .FOOTNOTE command, and ends with .END FOOTNOTE. Indentation, case lock, justify, margins, spacing, bar, and fill are preserved around footnotes. In addi- tion, all status is preserved. See .SAVE STATUS. However, com- mands that affect page formatting are illegal in a footnote. A footnote within a footnote is also illegal. If the footnote over- flows from the current page onto the next page, it is possible that the line referring to the footnote will also be printed on the next page. To prevent this, either preface the .FOOTNOTE command with a command that causes a break, or place enough text between the reference and the command to guarantee a full line of text. Nor- mally .FOOTNOTE does not draw a line between the body of the text and the footnotes. If you want a line to be drawn automatically, use .PERMANENT FOOTNOTE. CHAPTER: RUNOFF COMMANDS - RUNOFF - 22 - SECTION: FOOTNOTE / NOTE - 22 JAN 86 .END FOOTNOTE .EFN causes a break, and ends a footnote. The previous version of RUN- OFF used an exclamation point "!" to do this. The exclamation point is not supported in this version. Each .FOOTNOTE or .PERMANENT FOOTNOTE command must be followed by an .END FOOTNOTE command. Other versions of RUNOFF also required a parameter after the .FOOTNOTE command. .PERMANENT FOOTNOTE .PFN saves information for a permanent footnote header. This command may only be issued before other footnote commands. If it is issued and a footnote command has already been given for the current page, an error will be generated. Text following this command is taken as a permanent footnote header that is printed between the body of text on a page and the footnotes at the bottom. Permanent margins, spacing, and fill/justify mode are also set up for footnotes. The left margin, right margin, and spacing can be set during a per- manent footnote, and their values will be restored before every subsequent .FOOTNOTE command. For example, to separate the foot- note from the text by a blank line and a divider, and to indent both margins by 2 with no justification, you could use the follow- ing sequence of instructions: (NOT available in DSR) .PERMANENT FOOTNOTE .LEFT MARGIN +2 .RIGHT MARGIN -2 .NO JUSTIFY .SKIP 2;------- footnote ------- .END FOOTNOTE A permanent footnote will not be printed at the bottom of the page if no regular footnotes are declared. If the permanent footnote is longer than 6 lines, it is rejected with an error message. .NOTE [;][title] .NT [;][title] formats notes. A note is text set off from the rest of the docu- ment by reduced margins and a centered title. The text of the note follows the .NOTE command, and is terminated by an .END NOTE command. .NOTE skips 2 lines, reduces both margins, centers the title text (if no text is given, it centers the word "NOTE"), skips 1 more line, and issues a .TEST TEXT t,b, where t and b are deter- mined by the last .PARAGRAPH or .SET PARAGRAPH command. The text of the note is then printed. The same indentation is applied to both the left and right margins. The amount of indentation that is applied will be 20,15,10, or 5, whichever produces no more than a 25% reduction in the text line. If the indentation produces a text line less than the minimum, no indentation is used, and an error message is produced. Unlike DSR, notes may not be imbedded inside other notes. CHAPTER: RUNOFF COMMANDS - RUNOFF - 23 - SECTION: FOOTNOTE / NOTE - 22 JAN 86 .END NOTE [n] .EN [n] terminates the .NOTE command, skips n lines, and resets the margins and spacing modes to their settings before the last .NOTE command. DEFAULT: .END NOTE 2 V.3 PAGE FORMATTING .PAGE .PG causes a BREAK and an advance to a new page. If the current page is empty, a page advance is not performed. Like an automatic page advance, this command prints the title (if given) and page numbers on every page. The next page number can be selected with the .NUMBER command. This command is illegal during a footnote or note. | If you wish to end the page without causing a break in the text, | use .IMMEDIATE TEST TEXT (.ITT). To produce a break at the end of | the current line, use .ITT 127. .PAGE EVEN .PGE causes a page advance to the next even numbered page, skipping an odd numbered page if necessary. This command is illegal during a subpage, footnote, note, or text section. (not available in DSR) .PAGE ODD .PGO causes a page advance to the next odd numbered page, skipping an even numbered page if necessary. This command is illegal during a subpage, footnote, note, or text section. (not available in DSR) .SUBPAGE .SPG .END SUBPAGE .ES produces a new page, but the page number is unchanged and letters are appended to the page number until an .END PAGE command is encountered. This command permits the insertion of additional pages within an existing document without changing the existing page numbering. Subpages can be renumbered with the .NUMBER SUB- PAGE command. While subpaging is in effect, .TEXT commands are illegal. Deferred text is never printed on subpages. For example, if you are on page 5 and .SUBPAGE is used, a page num- bered 5A will be produced. Subsequent pages will be numbered 5B, CHAPTER: RUNOFF COMMANDS - RUNOFF - 24 - SECTION: PAGE FORMATTING - 22 JAN 86 5C and so on. After an .END SUBPAGE, the next page number will be 6. .PAGING .PA .NO PAGING .NPA turns document paging on or off and causes a break in the text. When no paging is in effect, neither footnotes nor text sections are allowed, but a new page can be produced with the .PAGE command. .CHAPTER, .APPENDIX, or .PAGE SIZE commands will enable paging. These commands are illegal inside a note, footnote, or text section. DEFAULT: PAGING .TEXT .TX .END TEXT .ETX specifies a text section that is to be kept all on one page. The text section is ended by a .PAGE, .END TEXT, or another .TEXT command. If the text section is too long to fit on the current page, the rest of the current page will be blank and the section will begin at the beginning of the next page. With this command you can guarantee that a given section of text will not be split between 2 pages unless it is too long to fit on 1 page. If a .PAGE command terminates a section, the rest of the page after the sec- tion will be blank. This command is illegal inside a footnote, note, or subpage. Likewise, footnotes and .TEST PAGE, .TEST TEXT, or .FIGURE DEFERRED are illegal inside this command. This command causes a break. (not available in DSR) .TEXT DEFERRED .TXDEF starts a text section that will be printed later if it doesn't fit on the current page. The normal .TEXT command leaves the bottom of the current page blank if the text section doesn't fit. The .TEXT DEFERRED command will save the text for printing on later pages if necessary. If text is deferred, the current page will be filled with the text that follows the next .END TEXT or .PAGE command. The deferred text section is terminated by a .TEXT, .TEXT DEFERRED, .END TEXT, or .PAGE command. Several deferred sections can be de- fined at one time; they will appear on later pages as necessary. The .TEXT DEFERRED command is useful for defining figures with captions. If the page length is changed in the middle of the docu- ment, deferred pages might not appear correctly, since the decision to defer the text is based on the original page size. This command causes a break. CHAPTER: RUNOFF COMMANDS - RUNOFF - 25 - SECTION: PAGE FORMATTING - 22 JAN 86 NOTE .TEXT DEFERRED does not modify the rules applicable to the .SKIP, .FIGURE and .BLANK commands. If a .SKIP com- mand follows the .TEXT command and the text appears at the top of a page, the .SKIP command is ignored. This will cause trouble when a .TEXT DEFERRED is followed by .PAGE. If .SKIP follows the .TEXT DEFERRED, it will be ignored and the text will be shortened with the result that the intended text will not fill the page, and regu- lar lines might appear at the bottom of the page. If you need to skip lines after .TEXT, you should use the .FIGURE command to reserve exactly the space you need. Examples To reserve 10 blank lines followed by a caption: .TEXT DEFERRED .FIGURE 10 This is figure 3.5 .END TEXT To reserve a whole page with 50 blank lines followed by a caption: .TEXT DEFERRED .FIGURE 50 This is figure 3.6 .PAGE To reserve room for 2 figures in a row: .TEXT DEFERRED .FIGURE 20 Figure 3.7 TEXT DEFERRED .FIGURE 20 Figure 3.8 .END TEXT .FLUSH flushes out all deferred text. If a .PAGE command is issued with deferred text pending, you are not guaranteed of getting a blank page. A blank page could, of course, be guaranteed by issuing several page commands in a row, but a better way of forcing a blank page is .FLUSH .PAGE The test commands check to see if there is enough room on the cur- rent page for more text. (not available in DSR) .TEST PAGE [t] [,b] .TP [t] [,b] causes a BREAK followed by a conditional page advance. If there are fewer than t lines left on the page, an advance to the next page is performed. When you specify b, test page operates slightly differently: the text following the test page up to the next com- mand that causes a break is treated as a block. Thus, b is useful in preventing orphan lines. t specifies the minimum number of CHAPTER: RUNOFF COMMANDS - RUNOFF - 26 - SECTION: PAGE FORMATTING - 22 JAN 86 lines at the top of the block and b the minimum number of lines at the bottom. The text will be arranged to maintain the minimum number of lines/page. In other words, the first t lines will all be on the same page, and the last b lines will also all be on a single page. The first t lines might not necessarily be on the same page with last b lines. (The b parameter is not available in DSR) .IMMEDIATE TEST PAGE [t] [,b] .ITP [t] [,b] performs a .TEST PAGE, but doesn't cause a break. If fewer than t lines remain on the current page, a new page is started and the current line becomes the first line on the new page. This command is useful if you wish to test for sufficient space on the current page without breaking the line. (not available in DSR) .TEST TEXT [t] [,b] .TT [t] [,b] causes a break and tests to see if there is enough room on the cur- rent page for t lines of text. If not, a new page is started. This command differs from .TEST PAGE in that the actual space re- quired will depend on the current spacing. (not available in DSR) .IMMEDIATE TEST TEXT [t] [,b] .ITT [t] [,b] performs a .TEST TEXT without causing a break. (not available in DSR) V.4 PAGE HEADERS The page header consists of a title and subtitle printed at the top of each page, as well as a page number. This title is printed on the first line below the top margin, and the subtitle on the next line. The page number will normally appear right justified on the same line with the title. The page number is normally preceded by the word "Page". The title and subtitle are normally left justified. The actual location of title, subtitle, and page number are controlled by the .LAYOUT command. In addition to the following commands, the .NUMBER PAGE, .DISPLAY NUMBER .NO NUMBER, and .NO NUMBER CHAPTER commands control the page header. .TITLE [;][text] .T [;][text] .NO TITLE break the text and set the title for the top of the page. .TITLE takes the remaining text as the title and outputs it on every page at line 0. The title is normally left justified with respect to the permanent left margin. See the .PAGE SIZE command. The CHAPTER: RUNOFF COMMANDS - RUNOFF - 27 - SECTION: PAGE HEADERS - 22 JAN 86 permanent margins allow different margins for the headers than for the text. Titles are also produced by these commands: .FIRST TI- TLE, .CHAPTER, or .APPENDIX. Titles can contain any special characters, but autoindexing will not work and tabs are converted to spaces. Normally only the flags enabled at the last .TITLE or .SUBTITLE command will be used in producing the title/subtitle. If you wish to control the flags, use the .SAVE HEADER command. If a flag is specified or removed with a .FLAGS command, all subsequent titles and subtitles will be affected. .NO TITLE inhibits printing of either the title or the subtitle at the top of the page. Title printing is reinstated by the .TITLE command. (The optional [;] is not used in DSR) .FIRST TITLE [;][text] .FT [;][text] is similar to .TITLE, but is used to specify the title to be printed on the first page of the document. This command must precede all text in the source file. Use of the FIRST TITLE com- mand is the only way to print a title line on the first page of the document. If the page number is formatted to appear on the same line as the title, it will not appear on the first page unless a .FIRST TITLE command is issued. If the title is blank, only the page number will be printed. If the page number is at the bottom of the page, it will be printed on the first page whether or not a .FIRST TITLE command is used. The .FIRST TITLE command is equivalent to: .HEADERS .TITLE [ text ] (DSR doesn't support any parameters after .FIRST TITLE. If you wish to use this command in the same way as DSR, include a .TITLE command on the line after .FIRST TITLE.) .SUBTITLE [;][text] .ST [;][text] specifies the text to be used as the subtitle that appears directly under the title. The subtitle is aligned on the same margin as the title. The subtitle is not printed if the .NO TITLE command is in force. If you do not wish to have a subtitle, use the .SUBTITLE command without any text. (The optional [;] is not used in DSR) .LAYOUT [code] [,spacing] .LO [code] [,spacing] breaks the current line and changes the layout of the title and page numbers on the page. This command does not have any affect on the current page. The next page will have the new layout. If you want to change only the first page of each chapter, use the .CHAPTER LAYOUT command. The spacing is the number of blank lines between the last line on the page and the page number. If the code is 0, then the spacing is the number of blank lines minus 1 between the bottom of the text and the bottom of the page. Pages with CHAPTER: RUNOFF COMMANDS - RUNOFF - 28 - SECTION: PAGE HEADERS - 22 JAN 86 different layouts but the same spacing will have the same number of lines on a page regardless of whether the page number is at the top or bottom of the page. If the spacing is omitted, it is assumed to be 2 except for code 0. For code 0, it is assumed to be -1 if not specified. If layout 0 is used, the first page of a document will not have a page number unless .FIRST TITLE or .HEADERS commands are used at the beginning. However, all other layouts will number every page. This is consistent with DSR usage. The layout codes are: CODE PAGE LAYOUT ____ ____ ______ 0 Title flush left, page number flush right 1 Title center ,number bottom center 2 Title right odd page/left even ,number bottom center 3 Title left, number bottom center 4 Title left, number bottom right 5 Title center, number bottom right 6 Title center, number bottom right odd/left even 7 Title top, number bottom, both right odd/left even 8 Title left, number right odd/left even 9 Title right odd/left even, number bottom right 10 Title center, number bottom left 11 Title right odd/left even, number bottom left 12 Title left, number bottom left 13 Title right, number bottom left 14 Title right, number bottom center 15 Title right, number bottom right odd/left even 16 Title right, number bottom right DEFAULT: .LAYOUT 0 (Codes 5-16 not available in DSR) .CHAPTER LAYOUT [code] [,spacing] .CHLO [code] [,spacing] changes the layout for the first page of a chapter or appendix without having any effect on other pages. The parameters are specified in the same manner as for the .LAYOUT command. If this command is not used, or used with no parameters, the layout will be the same for all pages of a document. (Not available in DSR) .HEADERS [on] .HD [on] .NO HEADERS [on] .NHD control whether the page header (title, subtitle, and page number) is printed. If a layout other than 0 is used, the page number is still printed at the bottom of the page and only the title and sub- title can be suppressed. If the header lines are disabled, the text begins at the top margin where the header would normally start. The first page of output from RUNOFF is formatted as if the .NO HEADERS command had been issued, while subsequent pages are formatted as if the .HEADERS command had been issued. This can be changed by issuing the .FIRST TITLE command before any text on the first page. CHAPTER: RUNOFF COMMANDS - RUNOFF - 29 - SECTION: PAGE HEADERS - 22 JAN 86 .HEADERS PAGE .HEADERS NO PAGE controls whether RUNOFF prints the word PAGE in front of the page number. This command is equivalent to .DISPLAY NUMBER "PAGE ". DEFAULT: .HEADERS PAGE (Not available in DSR) .HEADERS UPPER .HEADERS MIXED .HEADERS LOWER enables the header and specifies the format of the pre-header. UPPER, MIXED or LOWER cause the word "PAGE" to be printed before the page number in all upper case, capitalized, or all lower case respectively. NOTE The .DISPLAY NUMBER command should be used rather than .HEADERS UPPER .HEADERS LOWER, .HEADERS MIXED, .HEADERS NO PAGE, and .HEADERS PAGE. It is a more versatile com- mand and it can perform all the same functions of these other HEADERS commands. .HEADERS SPACING [n] .HDSP [n] sets the spacing between the title and the first line of text. The value n is the number of lines to skip. If n is not specified, the current spacing per line of text is used as the default. The minimum value for n is 1. If 0 is specified, the value of 1 is assumed. DEFAULT: .HEADER SPACING 3 (Not available in DSR) V.5 LISTS The following commands format lists of items. .LIST [n] ["char"] .LS [n] ["char"] specifies the beginning of a list of items. The left margin is moved 9 spaces to the right for the first .LIST command, and 4 ad- ditional spaces for each subsequent nested LIST. n specifies the number of blank lines to appear before each item. The .LIST ELE- MENT command is used to specify each item in the list, and the .END LIST command is used to end the list. CHAPTER: RUNOFF COMMANDS - RUNOFF - 30 - SECTION: LISTS - 22 JAN 86 If the .SPACING setting is greater than 1, the actual number of blank lines is n times the spacing. If n is omitted, the current paragraph spacing is used. If the optional character "char" is specified, then the character is output rather than a number. Thus, a "bullet" can be produced by specifying "o" as the optional character. If you wish to indent by a different amount than the default, the margins can be changed by using .LEFT MARGIN or .RIGHT MARGIN after .LIST. See also .NUMBER LIST and .DISPLAY ELEMENTS. DEFAULT: .LIST paragraph-spacing .LIST ELEMENT [;]text .LE [;]text specifies the start of each item in the list. If the text of the item appears on the same line as the command, the text must be separated from the command with any number of intervening spaces or tabs, or (optionally) one semicolon. Each list element entry pro- duces a number followed by a decimal point "." and two spaces fol- lowed by the text. If you prefer letters, roman numerals or some character other than the decimal point, see the .DISPLAY ELEMENTS command. The text lines up with the left margin, and the item numbers are placed 4 spaces to the left of the left margin. If there are not 4 spaces between the current margin and the permanent margin, then the number will be lined up with the permanent margin. A .TEST TEXT t,b is performed for each list element using the value set in the last .PARAGRAPH or .SET PARAGRAPH command. Both widow and orphan lines are prevented by the paragraph test values. The .LIST ELEMENT command can be issued without a preceding .LIST command, in which case the element might be considered to be the 0'th or base list. (the [;] is required in DSR) .END LIST n .ELS n terminates a list and restores the margins to their previous set- tings before the last .LIST command. The optional value n causes a .SKIP n after the last item in the list. DEFAULT: END LIST paragraph-spacing NESTING Lists can be nested up to 5 deep. That is, up to 5 .LIST commands can be used without any intervening .END LIST commands. This number can be modified by the system manager when RUNOFF is built. EXAMPLE Suppose you wish to make a list of the colors of the rainbow. You could do this by issuing the following commands. .list 0 .le RED .le ORANGE .le YELLOW .le GREEN CHAPTER: RUNOFF COMMANDS - RUNOFF - 31 - SECTION: LISTS - 22 JAN 86 .le BLUE .le VIOLET .end list The result would be the following: 1. RED 2. ORANGE 3. YELLOW 4. GREEN 5. BLUE 6. VIOLET It is possible to precede the list with letters as A,B,C ... and so on, or by Roman numerals. To do this, see the .DISPLAY LIST command. V.6 CHAPTER/APPENDIX FORMATTING .CHAPTER [;][title] .CH [;][title] indicates the beginning of a chapter with the specified title. Successive .CHAPTER commands number the following chapters sequentially. The title can contain escape sequences. Tabs within the title are treated as ordinary spaces. This command declares the layout to be chapter oriented, which has effects on the page numbers and the section headers. The effect of this command is as if the following command string were entered: .NO HEADER .PAGE SIZE .PAGE .FIGURE 12 .CENTER; CHAPTER n and n is incremented by 1 automatically. After a "CHAPTER n", the following commands are performed: .BLANK 2 .CENTER; title .BLANK 3 .TITLE title .FILL .HEADER .SUBTITLE The resulting chapter heading will have a centered title and chapter number. The chapters of this document are an example of the chapter format. All special printer features* are turned off, and underlining is turned off at the beginning of the chapter and after the chapter title. In addition the case, margins, spacing, and justify/fill modes are reset, any subtitles are cleared, and the chapter name is set to the title. The title will appear in CAPS unless it contains a shift down (\\). If the .NO AUTOTITLE or .NO TITLE command is used, the page title will not automatically be the same as the chapter title. To control the margins and spacing, use the .PAGE SIZE command to set the permanent margins and spacing before the .CHAPTER command is executed. -------- footnote -------- * Special features are only turned off if the appropriate escape sequences are defined as LCK. CHAPTER: RUNOFF COMMANDS - RUNOFF - 32 - SECTION: CHAPTER/APPENDIX FORMATTING - 22 JAN 86 It is possible to reformat the chapters with the .STYLE CHAPTER command. Chapter numbers can be selected to be letters or Roman numerals with the .DISPLAY CHAPTER command. In addition, the .DISPLAY CHAPTER command can be used to change the word "CHAPTER" to another word, or just blank space. .DISPLAY CHAPTER can under- line chapter titles, or use bolding on printers that support this feature. The STYLE and DISPLAY commands, when used together, can completely alter the chapter header. .STYLE CHAPTER [n1],[-n2],[-n3],[-n4],[-n5] .STCH [n1],[-n2],[-n3],[-n4],[-n5] changes the style of the chapter and appendix headers. 1. n1 = Number of lines to skip before the word CHAPTER. 2. n2 = Number of lines to skip after the word CHAPTER. If n2=-1, the title and the word CHAPTER will appear on the same line. 3. n3 = Number of lines between the title and text. If n3=-1, the title and any following text will be placed on the same line. 4. n4 = Number of spaces to indent the word CHAPTER. 5. n5 = Number of spaces to indent the title. If n4 or n5 are -1, the line will be centered. If n4 or n5 are -2, the line will be right justified. DEFAULT: .STYLE CHAPTER 12,1,3,-1,-1. (Not available in DSR) .APPENDIX [;][title] .AX [;][title] indicates the start of an appendix with the specified title. Suc- cessive .APPENDIX commands assign identifying letters in alphabeti- cal order. This command performs the same functions as .CHAPTER except that an appendix results. This command acts as if the fol- lowing command string were entered: .NO HEADER .PAGE SIZE .PAGE .FIGURE 12 .CENTER APPENDIX a .BLANK 2 .CENTER; title .BLANK 3 .TITLE title .FILL .HEADER .SUBTITLE The letter following the word APPENDIX is incremented before it is printed. Both .STYLE CHAPTER and .DISPLAY APPENDIX alter the look of the appendix header. V.7 SECTION HEADERS A section header consists of a section number of the form n1.n2.n3... followed by a section title. If either the .CHAPTER or .APPENDIX command has been used, then the current chapter or appendix number is attached to the front of the section number, giving it the form n0.n1.n2.n3... The level of the section header is equal to the number of numbers in the section header (not counting n0). The excep- tion is header level 1, which has the form n.0. The .STYLE HEADERS CHAPTER: RUNOFF COMMANDS - RUNOFF - 33 - SECTION: SECTION HEADERS - 22 JAN 86 command can be used to override the default form and print section numbers as a single number or letter, or with no number at all. The following commands control the header levels. See also .DISPLAY LEVELS, .NUMBER LEVEL, .ENABLE TRAILING ZERO and .ENABLE LEVELS. Examples Here is an example of the first header level: 1.0 The first header level! Here is an example of a header at level 4: 1.2.3.4 Example of a header The following is a header at level 6: 3.1.1.1.1.1 Example of a header The following is a header at level 3 in chapter number 7: 7.3.2.1 .HEADER LEVEL [+-n] [;][title] .HL [+-n] [;][title] starts a section with the specified section number and section title. n can range from 1 to 6. Successive .HEADER LEVEL commands at the same level cause the section numbers to increase sequentially. If the document is chapter oriented, then n will be the chapter number. Otherwise, it is the number of the .HL 1 level. The .HEADER LEVEL command issues the commands: .BREAK .TEST PAGE 7 .BLANK 2 then prints the section number, two spaces, and the section name. If the level number is preceded by + or -, the current level number is the previous one + or - the value specified. If the title is omitted, only the number is printed, and the next line of text follows, separated by 2 spaces. In this case, no dis- tinction is made between different level numbers. If the title is too long to fit on 1 line, it is filled, justified, and continued on the next line with indentation to line up with the first part of the title. Autohyphenation is not performed on header titles. DEFAULT LEVEL 1 capitalizes the section title and skips a line. LEVEL 2 prints the section title (no caps) and skips a line. LEVELS 3,4,5 The title and the text following it are separated by a dash. These defaults can be changed by the .STYLE HEADERS command. CHAPTER: RUNOFF COMMANDS - RUNOFF - 34 - SECTION: SECTION HEADERS - 22 JAN 86 .STYLE HEADERS [n1],[n2],...[n9],[n10] .STHL [n1],...[n10] changes the format used for various levels of section headers. .STYLE HEADERS also causes a line break. Default values are shown below in (). n1 = Lowest level at which text starts on same line as title. (3) n2 = Lowest level with title capitalized. (1) n3 = Highest level with first letter of title in CAPS. (6) n4 = Lowest level with no level number. (7) n5 = Lowest level with centered title and number. If the title and text are on the same line, no centering occurs. (7) n6 = Number of blank lines before the header. (2) n7 = Number of blank lines after the title. (1) n8 = Implicit test page value (7) n9 = Number of spaces between section number and title. (2) n10= Largest level printed as n.m.... (6) (n10 not available in DSR) DEFAULT: STYLE HEADERS 3,1,6,7,7,2,1,7,2,6 .INDENT LEVELS n1,n2 causes the header levels to be indented by n1 from the left margin and n2 from the right margin. A positive value of n1 causes inden- tation to the right of the left margin. A positive value of n2 causes indentation to the left of the right margin. (Not available in DSR) .INDENT LEVEL TITLES [n1],[n2]...[n6] causes the section titles to be indented from the normal level in- dention by an additional fixed amount. This can be used, for exam- ple, to line up all of the titles for level 1 independently of the titles for level 2. If the spacing specified in the .STYLE HEADERS command is greater then the spacing specified by the .INDENT LEVEL TITLES, the style spacing is used. When n is omitted the indenta- tion is not altered. DEFAULT: .INDENT LEVEL TITLES 0,0,0,0,0,0 V.8 NUMBERING These commands set numbers for various items. The number can be speci- fied either as a decimal number or a string of letters. The letter A corresponds to 1, B to 2, Z to 26, AA to 27, AB to 28, and so on. If the number is preceded by a plus sign "+", the new value is the old value plus the specified increment. If the number is omitted, it is as- sumed to be 1. No number should exceed 3999 or EWU. DSR allows larger numbers, but incorrectly handles Roman numerals larger than 3999. .NUMBER APPENDIX [+-n] specifies a number or letter to be used as the identifying letter for a subsequent APPENDIX command. See NUMBER CHAPTER. CHAPTER: RUNOFF COMMANDS - RUNOFF - 35 - SECTION: NUMBERING - 22 JAN 86 .NUMBER CHAPTER [+-n] .NMCH [+-n] specifies a number or letter to be used in a subsequent CHAPTER command. This command is useful when a chapter of a document occu- pies a source file of its own. In this case, .NUMBER CHAPTER should be the first command of the source file. .NUMBER CHAPTER can also be used to skip a chapter that will be inserted later. To skip chapters, specify +n. For example, if the current chapter is 10 and you specify .NUMBER CHAPTER +2, the next chapter will be 12. .NUMBER CHAPTER enables chapter numbering, so that each .CHAPTER or .APPENDIX command will reset the page number to 1 and cause the chapter or appendix number to be printed with the page number as part of the page header. (Default). .NO NUMBER CHAPTER disables chapter numbering, so that page numbers are not reset with each chapter or appendix, and the chapter/appendix number is not printed as part of the header. If this command is used, it must be issued before the first .CHAPTER or .APPENDIX command. If you in- tend to control chapter numbering, but wish running page numbers, then you must reissue this command after each after each .NUMBER CHAPTER command. Chapter numbering can be permanently disabled with the .DISABLE NUMBERING CHAPTER command. .NUMBER LEVEL [+-n1],[+-n2],[+-n3],[+-n4],[+-n5],[+-n6] .NMLV [+-n1],[+-n2],[+-n3],[+-n4],[+-n5],[+-n6] specifies the beginning number of a sequence of headers. It should be issued immediately before the first .HEADER LEVEL that you wish to affect. If the next .HEADER LEVEL command specifies a level different from the one implied in the .NUMBER LEVEL command, you will get unexpected results. If n1 is omitted then the next level will be 1.0. For example the following command sequence is specified: .NUMBER HEADER 5,4,3,2 .HEADER LEVEL The result of this would be: 5.4.3.2 If the current level is 1.2.3.4 and .NUMBER LEVELS +1,+1,-1,-1 is specified, the next section header will be 2.3.2.3. .NUMBER ITEM /name/ [+-n1] .NMIT /name/ [+-n1] specifies a new value for the item "name". The item must have been previously defined by the .DEFINE ITEM command. CHAPTER: RUNOFF COMMANDS - RUNOFF - 36 - SECTION: NUMBERING - 22 JAN 86 .NUMBER LIST [+-n] .NMLS [+-n] sets the next number in a list to n. For example, if the current list element is numbered 10 and you specify .NUMBER LIST +2, the the next element will be 12. .NUMBER [PAGE] [+-n] .NMPG [+-N] .NO NUMBER .NNM controls page numbering. The .NUMBER PAGE command indicates the beginning of a new page numbering sequence by specifying the number for the next page. For example, if you wish to skip several pages for inserting diagrams, artwork, or any other items that require a full pages, you can do so by issuing the commands: .NUMBER PAGE +n .PAGE The next page number will be the current page number plus n. If you issue .NUMBER PAGE 10, then the next page will be 10. If the current page is 10 and you specify .NUMBER PAGE +2, the next page will be 12. If the current page is 10 and you specify .NUMBER PAGE -1, the next page will be 9. .NUMBER PAGE +1 is essentially redundant. The page number is normally right justified with respect to the permanent right margin. See the .PAGE SIZE command. .NO NUMBER PAGE stops page numbering. However, pages continue to be counted, so that the normal page number will appear if page num- bering is resumed with the .NUMBER command. To disable page num- bering and not have pages numbered, use the .DISABLE NUMBERING command. .NUMBER SUBPAGE [+-n] .NMSPG [+-n] indicates the beginning of a new sequence of subpage numbers by us- ing the specified subpage number or letter on the next page. V.9 DISPLAY COMMANDS The display commands control how numbers such as the page number, chapter number, and so on, are displayed. Numbers can be displayed as normal (decimal) numbers, letters, or Roman numerals. Extra text can be added to the numbers as pre- or post-fixes. Pre- and post-fixes can be used to automatically control the format of various headers. For exam- ple, you can automatically underline headers, or print them in boldface on printers that support bolding. The display commands, like the DSR commands, produce a break. CHAPTER: RUNOFF COMMANDS - RUNOFF - 37 - SECTION: DISPLAY COMMANDS - 22 JAN 86 Table of Formats The format code produces numbers in the specified format: Format Description ______ ___________ D Decimal numbers (1,2,3,....) LU Letters uppercase (A,B,C,....,Z,AA,AB,AC....) LL Letters lowercase (a,b,c,....,z,aa,ab,ac....) LM Letters mixed (first is uppercase) (A,B,C,....,Z,Aa,Ab,...) RU Roman numerals uppercase (I,II,III,IV,....) RL Roman lowercase (i,ii,iii,iv,....) RM Roman mixed (I,Ii,Iii,Iv,....) Pre/Post-fix The pre- or post-fix specifies text to be printed before or after the number. The value is specified as a literal of up to 10 characters. Any flag characters included in the pre- or post-fix text are inter- preted at the time the page is printed. The autoindex flag is ignored in the pre-fix and tabs are converted to spaces. All spaces are treated as non-expandable. The pre-fix size can be extended by a substitution. When this is done, the number of levels of substitution is reduced, since the pre/post-fix is essentially another level of substitution. The pre- or post-fixes can be enclosed in either apostrophes (') or quotes ("). See the rules applicable to literal parameters. DSR doesn't support the "pre-fix" or "post-fix" parameters. .DISPLAY APPENDIX ["pre-fix",] [format] [,"post-fix"] .DAX ["pre-fix",] [format] [,"post-fix"] controls the format of the appendix number. The pre/post-fixes ap- ply only to the first page of the appendix, but the format sets the style of the appendix number, page number, index, and header levels. The page number and index are only changed if chapter num- bering is used. DEFAULT: .DISPLAY APPENDIX "APPENDIX " , LU , "" .DISPLAY CHAPTER ["pre-fix",] [format] [,"post-fix"] .DCH ["pre-fix",] [format] [,"post-fix"] controls the printed format of the chapter numbers when the .CHAPTER command is used. The command determines what is printed before and after the chapter number on the title page of each chapter. DEFAULT: .DISPLAY CHAPTER "CHAPTER " , D , "" CHAPTER: RUNOFF COMMANDS - RUNOFF - 38 - SECTION: DISPLAY COMMANDS - 22 JAN 86 For example, if you want sections to be numbered with Roman numerals rather than chapters, include the following in your .RNO file: .DISPLAY 'Section (' , RU , ')' When you issue the .CHAPTER command for the 6'th time, you will get the following chapter header: Section (VI) .DISPLAY ELEMENTS ["l"] [,format] [,"r"] .DLE ["l",] [format] [,"r"] sets the format of the current LIST element. "l" and "r" are the left and right characters to put around the list number. See .LIST, .LIST ELEMENT, .END LIST for explanations of the list elements. Once you have specified the display characteristics for a given list, the same characteristics will remain specified when additional .LIST or .END LIST commands are encountered. The op- tional characters can be delimited by either quotes ["] or a pair of apostrophes [']. DEFAULT: .DISPLAY ELEMENTS "" , D , "." If you wish to set up lists at the beginning of the document to normal outline form, issue the following commands: .LIST 0 .LIST 0 .DISPLAY ELEMENTS LU .LIST 0 .DISPLAY ELEMENTS LL .END LIST 0 .END LIST 0 .END LIST 0 This will display lists in the form (decimal number, capital letter, lowercase letter). .DISPLAY LEVELS [fm1,][fm2,][fm3,][fm4,][fm5,][fm6,] .DISPLAY LEVELS [level,]["pre-fix",] [form,] ["post-fix"] .DHL [fm1,][fm2,][fm3,][fm4,][fm5,][fm6,] specifies the format for display of the header level numbers. fm1 to fm6 are format codes for LEVELS 1 to 6. Each format code can be preceded by a pre-fix and followed by a post-fix. The pre-fix and post-fix are 10 char literals that will appear before and after the numbers. If the number is not printed, the post-fix is omitted. When the pre- and post-fix are defined, the .HEADER LEVEL command will automatically turn off underlining and all printer special features before the pre-fix and after the label. The levels can be specified by number or sequentially. For example, the following command will set number underlining with uppercase letters for level 2 and title underlining with roman numerals for level 3: .DISPLAY LEVELS 2,"^&",LU,"\&",RU,"^&" (DSR doesn't support Level numbers, pre-fix or post-fix) DEFAULT: .DISPLAY LEVELS D,D,D,D,D,D .DISPLAY NUMBER ["pre-fix",] [format] [,"post-fix"] .DNM ["pre-fix",] [format] [,"post-fix"] controls the format of the page numbers printed at the top of the page and in the index and table of contents. The pre- and post-fixes specify text to be printed before and after the page number. The pre-fix and post-fix are only printed on the indivi- dual pages, and do not appear in the index or table of contents page numbers. The format applies to the page number, which can be CHAPTER: RUNOFF COMMANDS - RUNOFF - 39 - SECTION: DISPLAY COMMANDS - 22 JAN 86 either a regular decimal number, Roman numeral, or a letter. See the table of formats. If the format is not specified, then it remains unchanged. If you wish to specify the post-fix only, you must either specify the pre-fix, the format, or include commas to mark their absence. DEFAULT: .DISPLAY NUMBER "Page " , D , "" If you want pages to be numbered in lower case roman numerals, you would use the following command: .DISPLAY NUMBER RL If you wish to print a 4 page memorandum, and on each page you want the page number and the total number of pages as n/4 underlined, you would issue the following command: .DISPLAY NUMBER "^&" "/4\&" The first page is numbered 1/1, the second 1/2, and so on. ___ ___ The RUNOFF manual was produced with the following format: .DISPLAY NUMBER "- " " -". .DISPLAY SUBPAGE [format] .DSP [format] controls the format of the subpage number. DEFAULT: .DISPLAY SUBPAGE "" LU "" .DISPLAY SUBTITLE ["pre-fix"] [,"post-fix"] sets pre- and post-fixes that are to appear with the subtitle at the top of the page. The .DISPLAY SUBTITLE command must appear be- fore the .SUBTITLE command or .HEADER LEVEL command that it modifies. The .HEADER LEVEL command produces automatic subtitles if .AUTOSUBTITLE is on. DEFAULT: .DISPLAY SUBTITLE "" "" .DISPLAY TITLE ["pre-fix"] [,"post-fix"] sets pre- and post-fixes that are to appear with the title at the top of the page. The .DISPLAY TITLE command must appear before the .TITLE command or .CHAPTER command that it modifies. The .CHAPTER command produces automatic titles if .AUTOTITLE is on. DEFAULT: .DISPLAY TITLE "" "" V.10 MODE SETTING .AUTOBREAK ["characters-to-test"] .AB ["characters-to-test"] .NO AUTOBREAK ["characters-to-disable"] .NAB enables or disables automatic optional breaks after selected characters. The selected characters are specified in a literal string. For example, to produce breaks after hyphens, issue the command .AB '-'. Then, if the word self-deceit overflows the end CHAPTER: RUNOFF COMMANDS - RUNOFF - 40 - SECTION: MODE SETTING - 22 JAN 86 of a line, the word will break after the hyphen. This command is also useful in tabulation; see the .TAB RIGHT command for further information. If you turn off autobreak for spaces, they no longer act as separators between words. A character preceded by an accept flag "_" will not autobreak. (Not available in DSR) DEFAULT: .NO AUTOBREAK .AUTOHYPHENATE [size],[begin],[end],[mode][,"chars"] .AH [size],[begin],[end],[mode][,"chars"] .NO AUTOHYPHENATE [,"chars"] .NAH [,"chars"] controls automatic hyphenation. When automatic hyphenation is turned on, words will be hyphenated automatically wherever necessary. If hyphenation is turned off with .DISABLE HYPHENATION, all hyphenation, including autohyphenation, is disabled until an .ENABLE HYPHENATION is issued. Autohyphenation follows the normal rules of style. A hyphenated word will always have at least 2 letters on the end of first line, and at least 3 on the beginning of the next. These rules can be changed by the command parameters. If a command parameter is omitted, it maintains its previous value. When automatic hyphenation is turned off, user selectable hyphena- tion can still be used. Autohyphenation can be turned off tem- porarily for 1 word by preceding the word with the hyphenate flag. .NO AUTOHYPHENATE turns off all autohyphenation, and specifies characters that are not allowed inside hyphenated words. For exam- ple, specifying "." will prevent hyphenation of words at the end of sentences. To allow autohyphenation, but disable hyphenation when these characters are present, the .NO AUTOHYPHENATE command must be followed by the .AUTOHYPHENATE command. For additional help see .ENABLE HYPHENATION. 1. size = The minimum number of characters/word. 2. begin = The minimum number of characters at the beginning of a line. 3. end = The minimum number of characters at end of a line. 4. mode = The hyphenation mode. 0 produces maximum hyphena- tion with possibly some inaccuracy. 1 hyphenates accord- ing to the suffix/prefix tables only, for maximum accuracy. 5. "chars"= Special characters allowed in hyphenated words. DEFAULT: .AH 5,2,3,0,'\/.,()"@' For more information see .ENABLE HYPHENATION. (Not available in DSR) .AUTOPARAGRAPH .AP .NO AUTOPARAGRAPH .NAP controls whether any blank line or a line starting with a space or tab is to be considered the start of a new paragraph. .AUTOPARAGRAPH allows normally typed text to be justified without special commands. It does not cause a paragraph if blank lines are followed by a command. Autoparagraphing works only if FILL is CHAPTER: RUNOFF COMMANDS - RUNOFF - 41 - SECTION: MODE SETTING - 22 JAN 86 enabled. When autoparagraphing and fill are enabled, all tabs at the start of a line are removed. SEE - .PARAGRAPH, .SET PARAGRAPH DEFAULT: .NO AUTOPARAGRAPH .AUTOTABLE .AT .NO AUTOTABLE .NAT controls whether or not lines starting with a space or tab are con- sidered to be the start of a new paragraph. This command allows normally typed text to be justified without special commands. AU- TOTABLE works only if FILL is enabled. When AUTOTABLE and FILL are enabled, all tabs at the start of a line are removed. See .AUTOPARAGRAPH. DEFAULT: .NO AUTOTABLE .AUTOTITLE .ATI .NO AUTOTITLE .NAT controls the generation of automatic titles. When AUTOTITLE is enabled, then each time a .CHAPTER or .APPENDIX command is given, the chapter or appendix title will be used as the title at the top of the page. DEFAULT: .AUTOTITLE (Not available in DSR) .AUTOSUBTITLE [+-n] .AST [+-n] .NO AUTOSUBTITLE .NAST controls the automatic changing of subtitles. When AUTOSUBTITLE is enabled, each header level command lower than n sets the subtitle to the current header level title. DEFAULT: .NO AUTOSUBTITLE The default for n is 1 .BEGIN BAR .BB .END BAR .EB controls whether the change bar is printed in the document. After a .BEGIN BAR, change bars are printed until an .END BAR. See .ENABLE BAR. CHAPTER: RUNOFF COMMANDS - RUNOFF - 42 - SECTION: MODE SETTING - 22 JAN 86 .FILL .F .NO FILL .NF controls whether or not subsequent output lines are filled. The .FILL command causes a break in the text, and sets the justifica- tion mode to be that specified by the last appearance of .JUSTIFY or .NO JUSTIFY. When FILL is enabled, successive words from the source text are added to the output line until the adding of one more word would exceed the right margin. If hyphenation is enabled, RUNOFF will attempt to break words that would cause line overflow into syllables. The end of an input line is treated as a space unless the .NO SPACE command has been issued. Initially FILL is enabled, so it does not need to issued except after a .NO FILL. .NO FILL is useful if you want to type a table or text and you want the output to look exactly like the input. (This could also be done with the .LITERAL command.) DEFAULT: .FILL RULES 1. When .FILL is enabled, multiple or redundent spaces are removed. This includes the following: (A) Spaces following spaces. (B) Spaces following non expandable spaces "#". (C) Spaces following "tabs". (D) Spaces at the beginning of a line. 2. When FILL is enabled, the end of a line is treated exactly like a space. 3. If both FILL and PERIOD are enabled, any punctuation fol- lowed by a space is converted to "punctuation", "space", "non expandable space". 4. If FILL is disabled, the end of a line is treated as a break ("|"). 5. Regardless of whether FILL is enabled or disabled, if the input line is longer than the available page size and it contains no "normal" spaces, it will be truncated to fit the available space. The only exception to this is when the line contains a "break" character ("|"); then the line is divided at the break character to make it fit. .JUSTIFY .J .NO JUSTIFY .NJ controls whether or not a line is filled out with additional spaces so that the last word ends exactly on the right margin. With justification turned off, output lines will have a ragged right margin. DEFAULT: .JUSTIFY CHAPTER: RUNOFF COMMANDS - RUNOFF - 43 - SECTION: MODE SETTING - 22 JAN 86 RULES 1. If justification is enabled, all "normal" spaces are ex- panded or padded to right justify the final output. 2. If a break occurs between lines, then the previous line is NOT justified. ___ 3. If an input line is shorter than the output line size and it contains no "normal" spaces, the line cannot be justified. This is indicated by an error message: "Can't justify line" 4. If .VARIABLE SPACING is enabled, justification will be done by adding micro spaces, rather than full spaces. If the character width is not 1, then justification may not occur unless variable spacing is enabled. 5. If justification is disabled, the output will not be pad- ded with extra spaces, but if filling is enabled, redun- dant spaces will be removed. 6. .FILL normally turns justification off unless preceded by .NO JUSTIFY. 7. .NO FILL always turns off justification. In order to justify but not fill (not recommended), a .JUSTIFY command must follow every .NO FILL command. .KEEP [LINES] .K [LINES] .NO KEEP [LINES] .NK [LINES] controls whether or not blank lines are kept in .NO FILL mode. Normally blank lines in the input are ignored. DEFAULT: .NO KEEP LINES (DSR uses .KEEP/.NO KEEP) .KEEP TABS .K TABS .NO KEEP TABS .NK TABS controls whether or not tabs at the beginning of a line are kept in .FILL mode. Autoparagraph mode also causes all tabs at the begin- ning of an input line to be discarded, so .KEEP TABS may not work with .AUTOPARAGRAPH. (Not available in DSR) DEFAULT: .KEEP TABS .LITERAL .LT .END LITERAL .ELI allows text to appear literally as typed. .LITERAL turns off fill and all flags to permit printing of text exactly as it appears in the source file. In addition, all commands are disabled until an .END LITERAL. When LITERAL is enabled, commands appear in the output as if they were normal text. Tabs are still recognized CHAPTER: RUNOFF COMMANDS - RUNOFF - 44 - SECTION: MODE SETTING - 22 JAN 86 inside a literal. Blank lines are output instead of being ignored. This command is almost equivalent to the following sequence of commands: .NO FILL .KEEP .NO FLAGS ALL .NO FLAGS CONTROL The .LITERAL command can be turned off by the .END LITERAL command. Tabs are still expanded inside a literal, and if a special feature has been turned on it will remain on for the duration of the literal. For example, if the literal is preceded by "^&" the en- tire literal text will be underlined. If you want to use flags in- side a literal, use the commands .NO FILL .KEEP to simulate the effect of a literal. You can turn off individual flags with a .DISABLE FLAGS command. .LOWER CASE .LC sets the case mode to lowercase. This command has the same effect as typing two backslashes (\\). .LOWER CASE is not normally used unless your terminal lacks lower case. .UPPER CASE .UC sets the case mode to uppercase. This command has the same effect as typing two circumflexes (^^). (Uppercase is the default case mode). There is no need to use .LOWER CASE unless the mode was previously altered to lower case. .PERIOD ["chars"] .PR ["chars"] .NO PERIOD ["chars"] .NPR ["chars"] controls whether or not additional spaces are printed after every terminal punctuation that is followed by at least one space or tab character. .PERIOD causes two spaces to be printed after terminal punctuation. .NO PERIOD disables conversion of punctuation/space to punctuation/two spaces and specifies characters that will not cause 2 spaces when .PERIOD is engaged. If you do not want 2 spaces to be inserted after a punctuation mark, you can quote the character or use a non expandable space after it. For example, if you want to use an abbreviation such as "Char.", you can avoid the extra spaces by writing it "Char_." or "Char.#". "chars" is a list of characters to be added to the terminal punc- tuation list; the terminal punctuation list will be changed only if "chars" are specified. (This parameter is not available in DSR.) Alternatively, the PERIOD flag can be used to add extra spaces without enabling .PERIOD. DEFAULT: .PERIOD ".:;?!" CHAPTER: RUNOFF COMMANDS - RUNOFF - 45 - SECTION: MODE SETTING - 22 JAN 86 .SEPARATED EQUATION .SEQ .END SEPARATED EQUATION .ESEQ enables or disables separated equation mode. If separated equation mode is enabled, an equation will automatically generate extra lines to separate it properly from other equations or text. Separated equation mode does not generate a break. It also cannot be used in a FOOTNOTE. This restriction may be changed in a future release. If you format an equation with the SEPARATED EQUATION mode off and the equation occupies more than the alloted spacing, it may print over other text. SEE - .ENABLE EQUATION, .FLAGS EQUATION DEFAULT: .END SEPARATED EQUATION (Not available in DSR) .UNDERLINE "chars to underline" .UN "chars to underline" .NO UNDERLINE "chars to not underline" .NUN "chars to not underline" specifies which characters are underlinable. Normally all characters other than spaces are underlinable. To enable underlin- ing of spaces, for example, you would use the following command: .UNDERLINE " " If you did not wish to underline common punctuation marks, you would use the command: .NO UNDERLINE ".,?!;:" If you don't want to underline either the apostrophe or quotes: .NO UNDERLINE "'""" ;SEE .ENABLE UNDERLINING and .FLAGS UNDER- LINE for more information. (Not available in DSR) DEFAULT: .NO UNDERLINE " " .UNDERLINE SPACES .UNDERLINE NO SPACES controls whether or not spaces are underlined. .UNDERLINE SPACES is the same as .UNDERLINE " ". (Not available in DSR) .VARIABLE SPACING .VARSP .NO VARIABLE SPACING .NVARSP controls the variable spacing mode. If variable spacing mode is enabled, microspaces are used to pad out room between words in order to create a justified line. To use this feature with your printer, it must either be a DIABLO compatible or you must define an appropriate escape sequence for variable spacing with the .DEFINE VARIABLE SPACE command. If variable size characters are used and they are to be justified, then variable spacing must be enabled. Variable spacing should not be confused with proportional CHAPTER: RUNOFF COMMANDS - RUNOFF - 46 - SECTION: MODE SETTING - 22 JAN 86 spacing. With variable spacing each letter is still assumed to oc- cupy the same amount of physical space as opposed to a propor- tionally spaced font. NOTE When using .VARIABLE SPACING and .UNDERLINE" ", the switch /U:L will not work correctly. Gaps will be left in the underlining at each variable spacing point. In this case /U:B is recommended. (Not available in DSR) DEFAULT: .NO VARIABLE SPACING V.11 PARAMETER SETTING .LEFT MARGIN [+-n] .LM [+-n] sets the left margin to n, where n must be at least 16 less than the right margin but not less than 0. The initial left margin set- ting is 0. If n is not specified, the permanent margin is restored. If the margin is specified with a + or - sign, n is ad- ded to or subtracted from the current margin. For example: .LEFT MARGIN +5 moves the margin 5 spaces to the right. .LEFT MARGIN -5 moves the margin back 5 spaces to the left. .LEFT MARGIN sets the margin to the value last specifed in a .PAGE SIZE command. Tab stops are relative to the margin at 0. In other words, if you set .LEFT MARGIN 10 .TAB STOPS 10,15,20,25, then the tab stop at 10 will be ineffective because it is already at the left margin. .RIGHT MARGIN [+-n] .RM [+-n] sets the right margin to n, where n must be 16 greater than the left margin. The initial right margin setting is 60. If n is not supplied, the current page width (set with the PAGE SIZE command) is used. If the margin is specified with a + or - sign, n is added to or subtracted from the current margin. .TOP MARGIN [+-n] .TM [+-n] sets the top margin (the number of blank lines at the top of the page) to n. The top margin must be less than the total number of lines on the page. The default value is 0. If n is not specified, the top margin is reset to the default or permanent value. See the .PAGE SIZE command for more information. If the margin is CHAPTER: RUNOFF COMMANDS - RUNOFF - 47 - SECTION: PARAMETER SETTING - 22 JAN 86 specified with a + or - sign, n is added to or subtracted from the current margin. (Not available in DSR) .PAPER SIZE [+-h],[+-w],[+-l],[+-t],[s] .PAGE SIZE [+-h],[+-w],[+-l],[+-t],[s] .PS [+-h],[+-w],[+-l],[+-t],[s] sets the size of the page to h lines high by w characters wide. Also, the LEFT MARGIN is set to l, the TOP MARGIN to t and the spacing to s. These settings are permanent since they are now the | new default for the duration of the document. If a .PAGE SIZE com- | mand is given in the middle of a page, the page length (h) and top | margin (l) will not change for the current page, but will change | for the next page only. The left/right margins and spacing (l,w,s) | will change for the current page. Every .CHAPTER or .APPENDIX command will reinstate the permanent settings. Other margin commands without any margins specified will also reset the requested margin to the permanent value. All values can be set to the permanent values by issuing the .PAGE SIZE com- mand without any parameters. The permanent values are used to determine the margins of the heading on each page. Older versions of RUNOFF used only the temporary right margin to set the header margins. If the margins are set so that there are fewer than 16 lines on a page or fewer than 16 spaces per line, the .PAGE SIZE command will be rejected with an error message. This restriction also applies to the margin commands. The maximum h is 127. DEFAULT: .PAGE SIZE 58,60,0,0,1. (DSR doesn't support permanent margins or parameters l,t,s) NOTE If you wish this command or any other margin command to set the margins for the entire document, including the first page, you must put the command before any text and before .BLANK, .SKIP, .FIGURE, .CHAPTER, or any other command that generates text. .SPACING [lines] .SP [lines] sets the number of spaces between lines. Spacing can range from 1 to 5 lines. If n is omitted, the permanent spacing (normally 1) is restored. The permanent spacing is set by the .PAGE SIZE command. This command influences .PARAGRAPH, .SET PARAGRAPH, .TEST TEXT, and .SKIP It has no effect on .TEST PAGE, .FIGURE, or .BLANK. .SPACING 1 is like single spacing on a typewriter, and .SPACING 2 is like double spacing. .CHAPTER or .APPENDIX resets the spacing to the permanent value. .PAGE SIZE also restores the permanent value if the spacing parameter is not specified. CHAPTER: RUNOFF COMMANDS - RUNOFF - 48 - SECTION: PARAMETER SETTING - 22 JAN 86 DEFAULT: .SPACING 1 .HALF SPACING [half lines] .NO HALF SPACING is similar to the spacing command except that it turns on half spacing. "half lines" is the number of half lines per line of text. text. Once half spacing is enabled, every command that specifies spacing will work in increments of half lines. If "half lines" is omitted, the current spacing will remain unchanged. The .HALF SPACING command does not change any spacing unless n is ____ ___ specified or unless one of the commands listed above is used. Com- mands that are affected by half spacing are: .BLANK .FIGURE .FIGURE DEFERRED .PAGE SIZE .TOP MARGIN .SPACING .HEADER SPACING .LAYOUT .STYLE LEVELS .STYLE CHAPTER .HALF SPACING 2 - Produces single spacing .HALF SPACING 3 - Produces 1&1/2 spacing .HALF SPACING 4 - Produces double spacing After .NO HALF SPACING, all commands that specify a spacing will work in increments of 1 space only. Previously specified spacing will, however, remain the same. This means that if you have set the spacing to 3 half lines and you wish it to be single spacing, you must subsequently issue .SPACING 1. NOTE .HALF SPACING will only work properly if the printer sup- ports subscripting. You may have to use the .DEFINE SUB- SCRIPT command. (Not available in DSR) DEFAULT: .NO HALF SPACING .STANDARD n .SD n returns all parameters to their initial settings and sets the page width to n. This command has been retained for compatability with previous versions of RUNOFF and is NOT recommended. The .PAGE SIZE ___ command with no parameters will reset margins to the permanent values, while this command resets them to "installation standard". If .STANDARD 70 is specified, margins are reset as follows: .PAGE SIZE 58,60,0,3 .SPACING 1 .FILL .SET PARAGRAPH 5,1,2 The actual parameters may differ according to the "installation standard". CHAPTER: RUNOFF COMMANDS - RUNOFF - 49 - SECTION: PARAMETER SETTING - 22 JAN 86 .LOCK locks a number of page formatting parameters. While locked, these parameters cannot be changed. All commands that change the page format are locked. The following commands will give error messages if issued after a .LOCK command: .ENABLE NUMBERING .DISABLE NUMBERING .ENABLE NUMBERING CHAPTER .DISABLE NUMBERING CHAPTER .HEADERS UPPER .HEADERS LOWER .HEADERS MIXED .HEADERS PAGE .HEADERS NO PAGE .HEADERS SPACING .NO HEADERS .HEADERS .INDENT LEVELS .PAGE SIZE .TOP MARGIN .STYLE (all commands) .STANDARD .NO NUMBER .NO NUMBER CHAPTER .NO TITLE .LAYOUT .DISPLAY (all commands) In addition, .NUMBER CHAPTER will not reinstate chapter numbering, and .NUMBER PAGE will not reinstate page numbering. If you are careful to put all page formatting commands into a separate file, this command will probably not be necessary. If, however, you have been foolish enough to sprinkle them throughout your text, or you need to merge several documents into a single coherent tome, this command can be a valuable short cut. This command is intended to facilitate merging several files into 1 document. First set up all the parameters mentioned above and then lock them. If you still have page formatting commands in the rest of the document, they will not be obeyed. Thus, you can produce a uniform document with the same formatting throughout. (Not available in DSR) V.12 TAB STOPS Lists of items can be conveniently expressed in tabular form using the tab key and the .TAB STOPS command. Every time you press the "tab" key you have entered a tab into the text. Just as on a typewriter, a tab will make the text begin at the next tab stop. The tab stops are set using the .TAB STOPS command. Items can be right justified or center justified if a right stop is specified. When tabbing, it is suggested that you use the .NO JUSTIFY command or the .NO FILL command. If justi- fication is on, you will either get error messages or unpredictable results. Tab stops to the left of the left margin are not effective. You should also .DISABLE HYPHENATION when using the tabs. See also: ENABLE TABS, KEEP TABS, FLAGS TAB .TAB STOPS ["ell"][+n1],["ell"][+n2], . . . .TS ["ell"][+n1],["ell"][+n2], . . . clears all previous tabs, and sets new ones. Each n specifies the column number for a tab stop. That is, n2 must be bigger than n1, and so on. If a tab stop is +n, then it will be n more than the previous one. If the first stop is +n, then it will be n more than the left margin. If n is prefaced by either R, C, or L, then the CHAPTER: RUNOFF COMMANDS - RUNOFF - 50 - SECTION: TAB STOPS - 22 JAN 86 text is right, center, or left justified. If the number is pre- ceded by a literal, then the text inside the literal is used as an ellipse to fill in the space generated by the tab. The maximum literal size is 15 characters. DEFAULT: .TAB STOPS 8,16,24,32,40,48,56,64,. . . (+- tab stops are defined differently in DSR) (The R,L parameters, and ellipses are not available in DSR) Example: .TAB STOPS +5,+10,+10,+10,+10 sets up a series of stops every 10 columns with the first one 5 from the left margin. .TAB STOPS 10,20,30,40,50 also sets up a series of stops every 10 columns, but the first stop is at column 10. The first tab is 10 from the left margin only if the left margin is at zero. .TAB STOPS ". " L20,C25,R40 sets up the first column to be filled with ellipses with the text left justified on column 20, center justified on column 25, and right justified on column 40. .TAB PROPORTIONAL n,["ell"][+-n1],["ell"][+-n2],,, .TABP n,["ell"][+-n1],["ell"][+-n2],,, sets the tab stops to create n columns across the page between the left and right margins. The first column begins at the left margin and ends at the first tab stop. The second column begins at the first tab stop and ends at the second one. The last column ends at the right margin. n must be 2 or larger. Tab stops are set so that all unspecified columns have equal width. The column 1 posi- tion is specified by n1, column 2 by n2, and so on. When you omit a column, it is unspecified. If you specify a column as either + or -n, then it is n larger or smaller than the unspecified ones. Using + or -, you can increase or decrease each column width from an evenly spaced one. A column width cannot exceed 127. The ac- tual number of tab stops set up is n-1. For example, if you want 3 columns, only 2 tab stops are set up. You can specify ellipses, and right or left justification as in the .TAB STOPS command. (Not available in DSR) For example, if you wish to set up 7 columns with 10 spaces in the second column, and 5 spaces in the 6'th column, then specify .TAB PROPORTIONAL 7,,10,,,,5 If you wish to set up 7 columns with the first and last only 5 spaces wide to allow for indented columns, then specify .TAB PROPORTIONAL 7,5,,,,,,5 This last example is a typical setup for a table. If you set up your table and then, after looking at the result, you decide to in- crease column 2 by 2 spaces and decrease column 4 by 1 space, then specify .TAB PROPORTIONAL 7,5,+2,,-1,,,5 When the .TAB PROPORTIONAL command is used, all previously speci- fied tab stops are cleared. .TAB PROPORTIONAL is easier to use than .TAB STOPS for evenly proportioning columns. CHAPTER: RUNOFF COMMANDS - RUNOFF - 51 - SECTION: TAB STOPS - 22 JAN 86 .TAB LEFT .TL sets unspecified tabs to left justification. If you do not specify either .TAB LEFT or RIGHT, then .TAB LEFT is assumed. (Not available in DSR) For example, .NO FILL .TAB STOPS +10,+10,+10,+10 .TAB LEFT 12345678901234567890123456789012345678901234567890 NAME Jan Feb Mar April Jones 152.75 0.00 3.78 1000.50 Smith 4.95 300.22 5.75 54.95 will produce the following text: 12345678901234567890123456789012345678901234567890 NAME Jan Feb Mar April Jones 152.75 0.00 3.78 1000.50 Smith 4.95 300.22 5.75 54.95 .TAB RIGHT .TR causes the text following an unspecified tab to be right justified. The text is right justified at the next tab terminator. The text is considered to be terminated by either a space, tab, end of line, break character, or autobreak character. If the break character is used to define the right side of the text, a .FLAGS BREAK command must be issued. This allows tables to be typed with the text right justified, or lined up with an arbitrary point (defined by the break). (Not available in DSR) EXAMPLES ________ Entering the text .NO FILL .TAB STOPS +20,+10,+10,+10 .TAB RIGHT 12345678901234567890123456789012345678901234567890 NAME Jan Feb Mar April Jones 152.75 0.00 3.78 1000.50 Smith 4.95 300.22 5.75 54.95 produces the following output: 12345678901234567890123456789012345678901234567890 NAME Jan Feb Mar April Jones 152.75 0.00 3.78 1000.50 Smith 4.95 300.22 5.75 54.95 CHAPTER: RUNOFF COMMANDS - RUNOFF - 52 - SECTION: TAB STOPS - 22 JAN 86 Listing a column of figures right justified: .NO FILL .TAB STOPS R+20,R+10,R+10,R+10 12345678901234567890123456789012345678901234567890 NAME Jan Feb Mar April Jones 152.75 0.00 3.78 1000.50 Smith 4.95 300.22 5.75 54.95 produces the output 12345678901234567890123456789012345678901234567890 NAME Jan Feb Mar April Jones 152.75 0.00 3.78 1000.50 Smith 4.95 300.22 5.75 54.95 Columns of figures lined up along the decimal points using the break flag: .NO FILL .FLAGS BREAK .TAB STOPS R+10,R+10,R+10,R+10 12345678901234567890123456789012345678901234567890 1|.23 3|.1415 75|.2 789|.0 55|.2 100|.98765 produces the output 12345678901234567890123456789012345678901234567890 1.23 3.1415 75.2 789.0 55.2 100.98765 Here is another way of lining up decimal points using autobreak: .NO FILL .FLAGS BREAK .TAB STOPS R+10,R+10,R+10,R+10 .AUTOBREAK "." 12345678901234567890123456789012345678901234567890 1.23 3.1415 75.2 789.0 55.2 100.98765 produces the output 12345678901234567890123456789012345678901234567890 1.23 3.1415 75.2 789.0 55.2 100.98765 Centered justification: .tabp 5,C7,C,C,C,C7 .tr .nf 123456789012345678901234567890123456789012345678901234567890 Mary Prunella Eve Sue Theresa Sadie Helen Agripinella produces 123456789012345678901234567890123456789012345678901234567890 Mary Prunella Eve Sue Theresa Sadie Helen Agripinella CHAPTER: RUNOFF COMMANDS - RUNOFF - 53 - SECTION: TAB STOPS - 22 JAN 86 Laundry lists If you want To set up a series of tab stops for a list of items, and if no item needs to go in any particular column, you can pro- duce the desired effect by setting .FILL .NO JUSTIFY. Each item should be preceded by a tab. If you wish the left hand column to line up with the left margin use .NO KEEP TABS. Otherwise, the first column will line up on the first tab stop. Note Tab stops are disabled and converted to single spaces when: 1. After .RIGHT 2. After .CENTER 3. During equations 4. Inside titles/subtitles .ELLIPSES .ELL .NO ELLIPSES .NELL causes tabbed text to be filled with ellipses rather than spaces. This command only changes tab stops that do not have ellipses asso- ciated with them. In other words, if you tab and this feature is enabled, the text will be padded with ellipses ( . . . .) rather than spaces between tab stops. DEFAULT: .NO ELLIPSES (Not available in DSR) For example, if you type .NO FILL .TAB STOPS " "R+15,R+13,R+13,R+13 12345678901234567890123456789012345678901234567890 NAME Jan Feb Mar .ELLIPSES Jones 152.75 0.00 3.78 .NO ELLIPSES Smith 4.95 300.22 5.75 .ELLIPSES Brown 0.00 1056.19 25.49 the following text will be produced: 12345678901234567890123456789012345678901234567890 NAME Jan Feb Mar Jones 152.75 . . . 0.00 . . . . 3.78 Smith 4.95 300.22 5.75 Brown 0.00 . . 1056.19 . . . 25.49 CHAPTER: RUNOFF COMMANDS - RUNOFF - 54 - SECTION: TAB STOPS - 22 JAN 86 V.13 FLAGS A flag is a character that performs some special action. For example, the ampersand (&) flag causes the next character to be underlined. The predefined flags and their default characters are ACCEPT (_), BREAK (|), CAPITALIZE (<), CONTROL (.), EQUATION ({, }), LOWERCASE (\), HYPENATE (=), INDEX/SUBINDEX (>), OVERSTRIKE (%), PERIOD (+), SPACE(#), SUBSTITUTE ($), UNDERLINE (&), and UPPERCASE (^). In addition, flags can be defined by the user for escape sequences that cause special ac- tions on the printer. The character associated with any flag can be changed to a different character. Normally, flags should be defined once at the beginning of a document, and not redefined later in the document. The .FLAGS commands are illegal inside a note or footnote. Two classes of RUNOFF commands affect flags: the .FLAGS flag-name and .NO FLAGS flag-name commands turn on and off the recognition of a flag character, and the .ENABLE/.DISABLE flag-action commands enable or dis- able the action of a flag. Recognition of flag characters means that the flag character will not be used for text, and it will not appear in the output. A recognized flag may or may not perform its flag task, depending or whether or not it has been enabled. Enabling the action of a flag means that it will perform its task if it is recognized. You can disable and reenable the operation of some flags without affecting their recognition. You can change a flag from the default character to another character. You might want to do this if, for example, you are frequently using a default flag character as regular text. First turn off recognition of the current flag character with a .NO FLAGS flag-name command. Then specify a new flag character with the appropriate .FLAGS flag-name command. All flags can be turned on or off with the .ENABLE FLAGS and .DISABLE FLAGS commands. Example: the following command will redefine the double quotes as the underline flag. .FLAGS UNDERLINE " After issuing this command, any character preceded by quotes (") will be underlined. The ampersand (&), which is the default underline character, will now be merely a simple printable character. When the .NO FLAGS command disables the selected flag character, it becomes a normal printable character. If you issue a .FLAGS command with a character that is already in use as a flag, RUNOFF will reject the com- mand and produce an error message. To turn off underlining but still recognize the flag, use the .DISABLE UNDERLINING command. CHAPTER: RUNOFF COMMANDS - RUNOFF - 55 - SECTION: FLAGS - 22 JAN 86 .FLAGS ACCEPT [new flag] .FL ACCEPT [new flag] .NO FLAGS ACCEPT .NFL ACCEPT turns on or off recognition of the accept flag. The accept flag causes the flag character that follows it to be printed as a normal character rather than be interpreted as a flag. The default character for the accept flag is the underscore (_). Initially recognition of the accept flag is turned on and the flag is disabled. A tab following the underscore flag is treated as a normal tab character. DSR uses this flag in a slightly incompatible way: if it is followed by a non printable character the character is included in the output and is counted as a single character. This convention was rejected for Bonner Lab Runoff as it makes dealing with control codes very difficult. To output control codes use the .DEFINE ESCAPE command. .FLAGS [ALL] .FL [ALL] .NO FLAGS [ALL] .NFL [ALL] turns on or off recognition of all flags that have been previously defined. This is analogous to a master switch that turns on or off all other switches. .FLAGS ALL only performs a useful function if it is preceded by a .NO FLAGS ALL. .NO FLAGS ALL disables recogni- tion of all flags except the CONTROL flag and the TAB flag. .FLAGS BREAK [new flag] .FL BREAK [new flag] .NO FLAGS BREAK .NFL BREAK turns on or off recognition of the break flag. The break flag marks where RUNOFF may break word or expression at the end of a line. The default character for the break flag is the vertical bar (|). Initially recognition of the break flag flag is off. A word will only be broken at the flag if the rest of the word would otherwise exceed the right margin. If more thatn one break flag is present in a word that requires a break, RUNOFF leaves as much of the word as possible on the line. If an .ENABLE CONTINUE command has been issued, and the break flag occurs at the end of an input line, text will continue immediately with the next line with no space being inserted. .FLAGS CAPITALIZE [new flag] .FL CAPITALIZE [new flag] .NO FLAGS CAPITALIZE .NFL CAPITALIZE turns on or off recognition of the capitalize flag. The capitalize flag causes the entire word directly following it to be capitalized. The default character for the capitalize flag is the less-than (<). Initially recognition of the capitalize flag is CHAPTER: RUNOFF COMMANDS - RUNOFF - 56 - SECTION: FLAGS - 22 JAN 86 off. (^<) can be used to perform a shift lock to upper case. All characters will then be printed in upper case until a shift release (^^) is encountered. .FLAGS CONTROL [new flag] .FL CONTROL [new flag] .NO FLAGS CONTROL .NFL CONTROL turns on or off recognition of the control flag. The control flag is the character that appears at the beginning of a line (at the left margin) to indicate that the line is a command instead of text. When the character is to be accepted as a text character, you do not need to precede it by an accept flag (_) as long as the position is not at the left margin. If you need the accept flag to appear at the left margin, precede it by an accept flag. The default character for the control flag is the period(.). Warning: once a .NO FLAGS CONTROL has been issued, you can no longer give any more commands, including .FLAGS CONTROL. So this is a non-reversable command. .FLAGS ESCAPE [escape flag] .FL ESCAPE [escape flag] .NO FLAGS ESCAPE .NFL ESCAPE turns on or off recognition of the escape sequence flags. Escape sequence flags are sets of special control characters (escape se- quences) that cause a printer to perform a variety of control func- tions such as printing characters in bold or changing the font to be used for printing. Initially recognition of the escape sequence flags is turned off and they are disabled. Two escape sequence flags are initially defined: the circumflex (^) and the back slash (\). You can also specify an additional escape character of your choice. See the .DEFINE ESCAPE command for a complete description of how to use escape sequences. (Not available in DSR) .FLAGS EQUATION .FL EQUATION .NO FLAGS EQUATION .NFL EQUATION turns on or off recognition of the equation formatting flags. The default characters used for the formatting flags are the left and right brace ({}), and recognition of the flags is turned off. See the section on Equation Formatting for a complete description of the use of these flags. (Not available in DSR) CHAPTER: RUNOFF COMMANDS - RUNOFF - 57 - SECTION: FLAGS - 22 JAN 86 .FLAGS LOWERCASE [new flag] .FL LOWERCASE [new flag] .NO FLAGS LOWERCASE .NFL LOWERCASE turns on or off recognition of the lowercase flag. The lowercase flag temporarily sets the case mode to lower case. It is also used to turn off features such as underlining. The default character used for the lowercase flag is the backslash (\). Initially recog- nition of the lowercase flag is turned on and the flag is enabled. .FLAGS HYPHENATE [new flag] .FL HYPHENATE [new flag] .NO FLAGS HYPHENATE .NFL HYPHENATE turns on or off recognition of the hyphenation flag. If the hypenation flag appears inside a word, it specifies the point at which the word may be hyphenated. If it precedes the word, it in- dicates that the word cannot be hyphenated. More than one hyphena- tion point can be specified in a word. When explicit hyphenation is specified, no automatic hyphenation will occur for the word. If the .ENABLE CONTINUE command is issued, then the current input line is continued when the hyphen flag appears at the end of the line. The default character for the hyphenation flag is the equal (=) sign. Initially recognition of the hyphenation flag is turned off. .FLAGS INDEX [new flag] .FL INDEX [new flag] .NO FLAGS INDEX .NFL INDEX turns on or off recognition of the index flag. When the index flag precedes a word, that word is automatically included in the index and not printed as part of the normal text. The default character for the index flag is the right arrow (>). The word to be indexed should be terminated by either a space, tab, non expandable space (#), hyphenate flag (=), index flag (>), or end of line. If more than 1 word needs to be part of the index term, the words should be separated by a quoted space (_ ). Initially recognition of the index flag is turned off. See the section on INDEXING for a com- plete discussion of how to create an index for your document. .FLAGS OVERSTRIKE [new flag] .FL OVERSTRIKE [new flag] .NO FLAGS OVERSTRIKE .NFL OVERSTRIKE turns on or off recognition of the overstrike flag. This flag generates a backspace so that the previous character can be over- stiken with the next character, allowing formation of composite characters for approximate scientific symbols or for adding diacritical marks for foreign languages. For example, a O over- striken with a - produces a theta (O-). The default overstrike character is the percent sign (%). Initially recognition of the overstrike character is turned off. CHAPTER: RUNOFF COMMANDS - RUNOFF - 58 - SECTION: FLAGS - 22 JAN 86 .FLAGS PERIOD [new flag] .FL PERIOD [new flag] .NO FLAGS PERIOD .NFL PERIOD turns on or off recognition of the period flag. If in fill mode, the period flag inserts extra expandable space after a period, colon, question mark, or exclamation point followed by an end-of-line space. For example, when this flag is on: A+ B will appear as: A B By default 2 spaces are inserted, but this can be changed with the .PERIOD command. The default period flag is the period (.). Initially recognition of the period flag is on and the flag enabled. .FLAGS SPACE [new flag] .FL SPACE [new flag] .NO FLAGS SPACE .NFL SPACE turns on or off recognition of the space flag. The space flag pro- duces one unexpandable space (not affected by justification) in the output file for every occurance in the input file. If the space flag is inserted between two words, they are treated as one word by RUNOFF (although they will appear as separate words in the output file). The default character for the space flag is the number sign (#). Initially recognition of the space flag is turned on and it is enabled. .FLAGS SPECIAL [flag1][flag2][flag3] . . . .FL SPECIAL [flag1][flag2][flag3] . . . .NO FLAGS SPECIAL [flag1][flag2][flag3] . . . .NFL SPECIAL [flag1][flag2][flag3] . . . turns on or off recognition of special characters that will trigger the generation of escape sequences in the output file. The first character of the escape sequence defined by the .DEFINE ESCAPE com- mand must be the circumflex (^). For example, if you want the left square bracket ([) to be an escape sequence flag that causes an escape character followed by a D to be output, you would enter the following commands: .FLAGS SPECIAL [ .DEFINE ESCAPE /^[/ 33,"D" Once you have done this, the left square bracket is no longer printable unless preceded by the accept flag (_). Note that more than one flag character can be specied with a single .FLAGS SPECIAL command. This command also turns on or off processing of all other special flags previously defined. (Not available in DSR) CHAPTER: RUNOFF COMMANDS - RUNOFF - 59 - SECTION: FLAGS - 22 JAN 86 .FLAGS SUBINDEX [new flag] .FL SUBINDEX [new flag] .NO FLAGS SUBINDEX .NFL SUBINDEX turns on or off recognition of the subindex flag. Subindex entries marked with this flag are collected and alphabetized below the primary entry to which they refer. The subindex flag is only recognized inside an .INDEX command. Since the subindex flag is not recognized as normal text, it can be the same character as the index flag. The default character for the subindex flag is the right arrow (>). See the section on INDEXING for information on the use of the subindex flag. .FLAGS SUBSTITUTE [new flag] .FL SUBSTITUTE [new flag] .NO FLAGS SUBSTITUTE .NFL SUBSTITUTE turns on or off the substitution flag. When this flag is turned on, it causes either a date or a time to be substituted in the out- put file. This is the only flag that must be paired with itself. The default character for the substitution flag is the dollar sign ($), so ($$) must be used to trigger a substitution. Eight per- manent substitutions are defined by RUNOFF. Suppose the current date and time is January 17,1983 15:23:51 then the permanent substitutions are Symbol Resulting output $$DATE 17 Jan 83 $$TIME 15:23:51 $$YEAR 1983 $$MONTH January $$DAY 17 $$HOURS 15 $$MINUTES 23 $$SECONDS 51 The pair of dollar signs ($$) that denote the permanent substitutions are both redefined if the substitute flag is redefined. For example, if you redefine the substitute flag to be ", then to print the date you must type: ""DATE. The permanent substitutions can be typed in either lowercase or uppercase letters. The following are equally valid: $$DATE $$date $$DaTe. .FLAGS TAB [new flag] .FL TAB [new flag] .NO FLAGS TAB .NFL TAB turns on or off recognition of the tab flag. The default character for the tab flag is a tab. When some other character is defined as the tab flag, then a tab in the input text will produce a space. This command is useful in making RNO compatible with other word formatters. Most editors do not display tab characters, so this command could also be used to make tabs visable by reassigning them CHAPTER: RUNOFF COMMANDS - RUNOFF - 60 - SECTION: FLAGS - 22 JAN 86 to an unused printable character. And using a visible character for a tab can make it easier to form output into columns. Initially recognition of the tab flag is turned on and it is enabled. (This is not available in DSR) .FLAGS UNDERLINE [new flag] .FL UNDERLINE [new flag] .NO FLAGS UNDERLINE .NFL UNDERLINE turns on or off recognition of the underline flag. The underline flag causes the next character to be underlined. The default character for the underline flag is the ampersand (&). If the un- derline flag is paired with the uppercase flag(^&), it locks under- lining on until an occurance of the underline flag paired with the lowercase flag(\&). Initially recognition of the underline flag is on, and it is enabled. .FLAGS UPPERCASE [new flag] .FL UPPERCASE [new flag] .NO FLAGS UPPERCASE .NFL UPPERCASE turns on or off recognition of the uppercase flag. A single oc- curance of the uppercase flag serves the same purpose as a typwriter SHIFT key by capitalizing the single letter that follows it. It has no effect if the character following is not a letter. The default character for the uppercase flag is the circumflex (^). When the uppercase flag is paired with a capitalize flag (^<), the action is the same as performing a SHIFT-LOCK on a typwriter: the text that follows will appear in uppercase until the SHIFT-LOCK is removed with a (\<). When the uppercase flag is paired with the underline flag (^&), underlining is locked on until the occurance of (\&). Two uppercase flags in a row (^^) turns off the lower case lock. If the circumflex is used extensively in the text, you may want to specify an alternate character for the uppercase flag. Initially recognition of the uppercase flag is turned on and the flag is enabled. V.14 ENABLE/DISABLE These commands enable or disable various actions. Some of the enable commands can be confused with the FLAGS commands, but they are very different. A FLAGS command turns on recognition of special characters or combinations of characters, but does not affect whether the flag causes the desired action. If recognition of a flag is turned on, then the enable/disable commands can be used to cause the action of the flag to actually occur or not. For example, if you turn on recognition of the overstrike flag with .FLAGS OVERSTRIKE, then the flag is also enabled. The flag character, normally a percent sign " % ", will then cause overstriking and will not appear in the text. If .DISABLE OVERSTRIKING command is then issued, the percent sign will still not appear in the text, unless quoted, but no overstriking will CHAPTER: RUNOFF COMMANDS - RUNOFF - 61 - SECTION: ENABLE/DISABLE - 22 JAN 86 occur. See the FLAGS section for further information on the use of flags. .ENABLE BAR [n1] [,n2] [,"c"] .EBB [n1] [,n2] [,"c"] .DISABLE BAR .DBB controls the printing of change bars. A change bar is a vertical bar printed in the left margin of a document. It is generally used to denote sections of the document that have been changed since the last printing. Change bars will not actually be printed unless a .BEGIN BAR command is issued. The .ENABLE BARS command is normally issued at the beginning of a document. When change bars are enabled, change bars are printed n1 spaces to the right of the left margin and normal text is printed n1+n2 spaces to the right of the left margin. For example, if n1 is 4 and n2 is 3, text will be in- dented by 7 and change bars will appear to the left of the text with two spaces in between. The default values for n1 and n2 are 0 and 3. The character printed in the change bar position can be changed by specifying the literal "c". If a null literal "" is used, the character reverts to the default. (n1,n2, and "c" are not supported in DSR) DEFAULT: .DISABLE BAR | .ENABLE COMMAND REPLACEMENT | .DISABLE COMMAND REPLACEMENT | controls the ability to replace permanently defined commands with | user defined commands. If a user command is the same as a per- | manent command, the permanent command will be performed unless pre- | faced by an underscore "_". For example, if you define the | following command: | .DEFINE COMMAND /p/.s 1 .tt 5 .i 5 | the command would not normally be performed unless you either | .ENABLE COMMAND REPLACEMENT | ...or | ._P | When command replacement is enabled, you can still select permanent | commands by beginning them with a dollar sign "$". In the example | above, .$P invokes the permanent command and ._P invokes the user | defined command. When command replacement is enabled, RUNOFF may | be slower if you have defined many commands or substitutions. | (Not supported in DSR) | Default: .DISABLE COMMAND REPLACEMENT .ENABLE CONTINUE .ECO .DISABLE CONTINUE .DES controls the action at the end of a line when a break or hyphena- tion flag occurs. When CONTINUE is enabled, the line will not automatically break at the end of the input line when in NO FILL CHAPTER: RUNOFF COMMANDS - RUNOFF - 62 - SECTION: ENABLE/DISABLE - 22 JAN 86 mode. In FILL mode, no space will occur between the word at the end of the line and the word at the beginning of the next input line. When CONTINUE is enabled, the break and hyphenate characters still have their usual meaning, and hyphenation or breaks may occur at the end of the input line if there is not sufficient space for the next word in the output line. If the break or hyphenation flag is followed by a space, then it is not at the end of the line. (Not supported in DSR) DEFAULT: .DISABLE CONTINUE .ENABLE ESCAPE .EES .DISABLE ESCAPE .DES controls the output of escape sequences. When ESCAPE is diabled, the escape sequence flags will be recognized but not executed. DEFAULT: .ENABLE ESCAPE (Not supported in DSR) .ENABLE EQUATION n .EEQ n .DISABLE EQUATION .DEQ controls the action of the equation formatting flag. The parameter n is the number of half lines to allocate above and below each character. If you are formatting equations with many subscripts or superscripts, n=1 may look better because more blank space is added to the fractions. When the equation is disabled but has had recog- nition turned on by the .FLAGS EQUATION command, left and right braces { } are translated to be normal parentheses ( ). (Not supported in DSR) DEFAULT: .ENABLE EQUATION .ENABLE FLAGS [flag] .DISABLE FLAGS [flag] controls whether or not flags are enabled. The possible flags are: ACCEPT ALL BREAK CAPITALIZE ESCAPE EQUATION HYPHENATE INDEX LOWERCASE OVERSTRIKE SPACE SPECIAL SUBINDEX SUBSTITUTE TAB UNDERLINE UPPERCASE By default all flags are initially enabled. If no flag is speci- fied or ALL is specified, all flags except the TAB flag are enabled or disabled. Flags disabled by .NO FLAGS ALL can be enabled by a .FLAGS ENABLE flag command. Flags that have not been defined by a .FLAGS command cannot be enabled. The enable status of flags can be saved with the .SAVE command. Disabling a flag does not rede- fine or remove the flag character. For example, if you wish to use the ampersand (&) for some other purpose than as the underline flag, you could undefine it with a .NO FLAGS UNDERLINE. You could also .DISABLE FLAGS UNDERLINE to use the ampersand as a printable character. (Not supported in DSR) CHAPTER: RUNOFF COMMANDS - RUNOFF - 63 - SECTION: ENABLE/DISABLE - 22 JAN 86 .ENABLE HYPHENATION .EHY .DISABLE HYPHENATION .DHY Controls hyphenation. When hyphenation is enabled, RUNOFF will hy- phenate words at the end of an output line. Hyphenation defined by the user with the hyphenate flag can also be used. Automatic hy- phenation is enabled with the .AUTOHYPHENATE command. RUNOFF will not hyphenate: 1. The last line on the page 2. A line following 2 hyphenated lines 3. Equations The following will inhibit autohyphenation: 1. Escape sequences inside a word 2. Overstrikes 3. Non expandable spaces "#" 4. Tabs in front of a word 5. Invalid punctuation Valid punctuation marks are: / \ . , ( ) " @ For example, words containing hyphens are not hyphenated; these words can be broken by using a break character or by issuing the command .AUTOBREAK "-" The valid punctuation marks can be changed by the .AUTOHYPHENATION command. The hyphenation algorithm is not ideal; there are certain problems that you must overcome manually. The hyphenation routine receives no warning when a paragraph is ending. Consequently, it may hy- phenate the last word in a paragraph. This can be avoided by using the .FLAGS HYPHENATE command and marking the last word in a para- graph for no hyphenation. Also, periods could be declared as in- valid punctuation. If a footnote overflows to the next page, the hyphenation routine may hyphenate the last word on a page. This can be avoided by use of the hyphenation flag, or by forcing the page breaks with the .PAGE command. Try to avoid footnotes that overflow to the next page. DEFAULT: .ENABLE HYPHENATION .ENABLE INDEXING .EIX .DISABLE INDEXING .DIX controls the collection and printing of index entries. DEFAULT: .ENABLE INDEXING .ENABLE LEVELS [+-n1],[+-n2] enables output of header levels up to n1, and TOC output up to n2. In other words, the .DOC file will have header levels 1 to n1 and the .RNT file will have levels up to n2. If n2 is greater than n1, the .RNT file will only contain levels up to n1. If n is not CHAPTER: RUNOFF COMMANDS - RUNOFF - 64 - SECTION: ENABLE/DISABLE - 22 JAN 86 specified, the default value is assumed. There is no .DISABLE LEVELS command (Not supported in DSR) DEFAULT: .ENABLE LEVELS 6,6 .ENABLE NUMBERING .ENMPG .DISABLE NUMBERING .DNMPG controls whether page numbers are printed. Numbering does not start if it has been turned off by a .NO NUMBER command. When page numbering is disabled, page numbers will not be printed, but pages will still be counted. The .NUMBER command will not turn on the printing of page numbers when page numbering is disabled. DEFAULT: .ENABLE NUMBERING .ENABLE NUMBERING CHAPTER .ENMCH .DISABLE NUMBERING CHAPTER .DNMCH controls the form of page numbering. When enabled, pages are num- bered in the chapter form N-M, where N is the chapter number and M is the page number. Once chapter numbering has been disabled, it will not be reenabled by any command except .ENABLE NUMBERING CHAPTER. (Not supported in DSR) DEFAULT: .ENABLE NUMBERING CHAPTER .ENABLE ODD .EODD .DISABLE ODD .DODD controls whether or not the first page of each chapter is forced to be an odd number. If enabled, and a page must be skipped, an in- termediate numbered page with with no text will be produced to force the chapter onto the proper page. (Not supported in DSR) DEFAULT: .DISABLE ODD .ENABLE OVERSTRIKING .EOV .DISABLE OVERSTRIKING .DOV enables or disables the overstriking flag. If recognition of the overstrike flag has been turned on by the .FLAGS OVERSTRIKE com- mand, but overstriking is disabled, RUNOFF will not do any over- striking, and the overstrike flag character will not appear in the output. Previous versions of RUNOFF attempted to omit overstruck characters, but this is, unfortunately, not possible in all circum- stances, so this feature had to be omitted. DEFAULT: .ENABLE OVERSTRIKING CHAPTER: RUNOFF COMMANDS - RUNOFF - 65 - SECTION: ENABLE/DISABLE - 22 JAN 86 | .ENABLE PAGING | .EPAG | .DISABLE PAGING | .DPAG | enables or disables pagination. When PAGING is disabled, the .PAGE | SIZE command will not turn paging on, and the .PAGE command will | not produce a page. See .PAGING. | DEFAULT: .ENABLE PAGING | (Not available in DSR) .ENABLE SUBSTITUTION .ESST .DISABLE SUBSTITUTION .DSST enables or disables the substitute flag. When recognition of the substitute flag is turned on, but the flag is disabled, the substi- tution will be recognized, but no substitution will be made. DEFAULT: .ENABLE SUBSTITUTION (Not available in DSR) .ENABLE TABS .ETB .DISABLE TABS .DTB controls how the tab key is interpreted for producing tabulated or columnar output. Tabs are normally enabled, so you do not need to enable them unless they have been previously disabled. When tabs are disabled, they are treated as ordinary spaces. (Not supported in DSR) DEFAULT: .ENABLE TABS .ENABLE TOC .ETC .DISABLE TOC .DTC controls whether or not output is sent to the table of contents file. When disabled, neither CHAPTER, .HEADER LEVEL, .APPENDIX, nor .SEND TOC commands will output anything to the .RNT file. This command can be used to control which items are placed in the TOC. DEFAULT: .ENABLE TOC | .ENABLE TRAILING ZERO | .DISABLE TRAILING ZERO | controls whether or not header levels are printed with trailing | zeroes. For a non-chapter-oriented document, the command | .HL 1 | will print a header level number in the form | 1.0 | If trailing zeroes are disabled, the number appear as | 1 CHAPTER: RUNOFF COMMANDS - RUNOFF - 66 - SECTION: ENABLE/DISABLE - 22 JAN 86 | (Not available in DSR) | DEFAULT: .ENABLE TRAILING ZERO .ENABLE UNCONDITIONAL .EUNC .DISABLE UNCONDITIONAL .DUNC controls the printing of unconditional text. When enabled, all text that is not preceded by an .IF command will appear in the output. When disabled, all input that follows is ignored except for .ENABLE UNCONDITIONAL and .IF commands. These commands cannot be used inside a note, footnote or text section, and must be the first command on a line. When an .IF command is encountered, RUN- OFF will continue processing text as if UNCONDITIONAL were enabled until the matching .ENDIF command is reached. These commands can be used to generate multiple table of contents for sections, figures, tables, and so forth. By disabling normal text, you can have RUNOFF pick out only desired sections and ignore the rest. (NOT available in DSR) DEFAULT: .ENABLE UNCONDITIONAL .ENABLE UNDERLINING .EUL .DISABLE UNDERLINING .DUL enables or disables the underline flag. NOTE The DSR Pocket Reference uses .EUN instead of .EUL, but the DST manual uses .EUL, so this has been adopted as the standard abbreviation. .EUN and .DUN will also work, but these might not be supported in the future. .DEFAULT: .ENABLE UNDERLINING V.15 DEFINE, DELETE, AND RESET The DEFINE, DELETE, and RESET commands are not available in DSR. These commands can be used to define features, such as bolding, that are available in DSR. .DEFINE COMMAND /label/command string allows the user to define new commands. The label consists of up to 20 letters. Imbedded spaces inside the label are treated as op- tional syntax elements. The actual command can have single, multiple or no spaces. The command string must be a legal set of CHAPTER: RUNOFF COMMANDS - RUNOFF - 67 - SECTION: DEFINE, DELETE, AND RESET - 22 JAN 86 commands to be substituted for the label. If a command is defined the same label as a normal command, the normal command will be used and the defined one ignored. .ENDIF will be ignored if used in a defined command. .DEFINE COMMAND must be the last command on the line. All text following this command is treated as the command definition. When the defined command is encountered by RUNOFF, the command string is substituted. Defined commands can be nested to 3 levels. To prevent conflict with future commands all user commands should begin with the letter Q. .DEFINE COMMAND is invaluable for defining commands that exist in other versions of RUNOFF, but are not available in this version. Parameters to be substituted into the command should be marked by %. Text parameters following titles, subtitles, and so on cannot be substituted; they must be included in the previous command. In other words, parameters can be nested. EXAMPLE .QHEADER A could be defined to skip a line, indent both margins by 5 spaces, and output a centered line of text: .DEFINE COMMAND /QHEADER A/.s.lm+5.rm-5.c; Acceptable variants of the command are .QHEADERA, .QHEADER A, and .QHEADER A The first command after the label, s, need not be preceded by a decimal point, as a decimal is already implied. For example, the previous command could be defined as: .DEFINE COMMAND /QHEADER A/s.lm+5.rm-5.c; An example of parameter substitution is: .DEFINE COMMAND /Q/.s %.i % The command .Q 5,8 would then skip 5 lines and indent 8. .DEFINE ESCAPE "escape label" [,modifiers] definition defines escape sequences for control of a variety of printers. Each escape sequence is indicated in the text by either a backslash (\), carot (^), or a symbol of your choice, followed by another symbol. For example, ^* might enable bolding by issuing the appropriate escape sequence to turn on bolding, and \* might dis- able bolding by issuing a turn off sequence. The escape sequence is entered as follows: First, select which 2 character label you want to represent the sequence. The first character must be either ^,\, or your own flag character, while the second one can be any other character. They are entered as a literal. For example, the label ^* could be en- tered as "^*" or '^*' or "^","*". You can define your own flag character with the .FLAGS ESCAPE command. (If you change the up- percase flag from ^ or the lowercase flag from \, then the new up- percase and lowercase flags should be the first character of an escape sequence, and you must specify the new upper/lowercase flags with a .FLAGS command before defining the escape sequences.) CHAPTER: RUNOFF COMMANDS - RUNOFF - 68 - SECTION: DEFINE, DELETE, AND RESET - 22 JAN 86 Next, enter the modifiers. These define how the escape sequence is handled. Modifiers LCK - specifies that escape sequence is a lock/unlock pair. For example, if ^* and \* are defined as a lock/unlock pair, then the first appearance of ^* will "lock" this feature on and a subsequent appearance of ^* will be ignored as long as \* is not used in between them. In other words, the lock is ^* and unlock is \*. When an escape sequence is defined as a lock/unlock pair, it will not act on headers, but will only change text, much in the same way the underline flag works. Only 16 escape sequences can be declared LCK. If a line con- tains only the "lock" sequence, then the unlock sequence will be output automatically at the end off the line and the next line will be preceded automatically by the lock sequence. This process continues until an "unlock" sequence flag is encountered. If you define a sequence that changes the character style, it should always be defined as a lock/unlock pair. Some examples of operations that change character style are hardware underlining, shadow printing, bolding, font changes, and ribbon color changes. The LCK attribute can be used to output sequences automa- tically at the beginning and end of each line. This can be useful if you have a printer that doesn't respond to CR,LF, but uses some other control character. The control character can be output at the end (or beginning) of each line as half of a lock/unlock pair. VSP,spacing - indicates that the escape sequence will change the vertical position by the specified spacing. The spacing parameter is specified in half lines, with 1 being 1/2 line advance, -1 is 1/2 line backwards. HSP,spacing - indicates that the escape sequence will change the horizontal position by the specified spacing. position. Sequences that modify the position are considered to be print- able characters, while sequences without HSP are considered to be attribute changes. If an escape sequence does not have the HSP attribute and a space follows an escape sequence, the space will be deleted from the output (while in fill mode). PSP - indicates that the horizontal spacing specified by HSP is ap- plied to all printable characters following the escape sequence. This attribute modifies the HSP attribute by specifying that a sequence will change the character width and by letting RUNOFF know what the new width is. The width can only be 0,1,2,... or multiples of the normal width. If HSP is specified as a number other than 1, certain aspects of fill are disabled. Spaces will not be expanded if it is necessary to justify the text. Only "normal" spaces with HSP=1 are ex- panded unless .VARIABLE SPACING is enabled. This feature al- lows imbeding extra wide text inside normal text, or centering extra wide text. A whole line of extra wide text cannot be justified, but a mixed line of normal and wide text can. If an escape sequence changes the permanent spacing to a value other than 1, then it should also have the attribute LCK. If it does not, a variety of things will be messed up, including CHAPTER: RUNOFF COMMANDS - RUNOFF - 69 - SECTION: DEFINE, DELETE, AND RESET - 22 JAN 86 underlining and margins. CHR - indicates that the lock/unlock pair is used to change only 1 printable character. This attribute should be used only if the lock/unlock pair is designed to function similarly to the underline flag. You must also declare the escape character in a .FLAGS SPECIAL command. Following the modifiers is the escape sequence itself. Printable characters can be entered as literals ('This is a literl'), while non printable must be entered as a decimal value. Numbers and literals can be separated by blanks,tabs, and or commas. Two com- mas in a row constitute a null, and are illegal. If you define an escape sequence twice in your text, only the first definition will be obeyed unless you reset escape before the second one. The second definition will cause an error message. If you use a large number of different escape sequences frequently, you should define the most commonly used ones first. This will in- crease the speed with which RUNOFF can find them. Escape sequences can be very tricky. To use them intelligently the following rules will be helpful. 1. Always use LCK and define a lock/unlock pair for a se- quence that changes the text attributes. Such sequences are ones that (A) Change font (B) Change all character spacing (C) Underline characters (D) Change ribbon color (E) Bold or shadow print characters 2. Always define HSP for sequences that output printable characters. 3. Always define HSP and PSP for sequences that permanently change the horizontal spacing. 4. Always define VSP for sequences that change the vertical position. 5. Use /U:L instead of /U:B for the underlining option, especially if sub or superscripted expressions are to be underlined. /U:L is also necessary if alternate fonts substitute other characters for the underscore. 6. If a font switch results in a pitch change that is not an even multiple of the normal font, you must handle this change manually. If such a change is defined as a lock/unlock pair, RUNOFF will be able to print headers in the old pitch while using the new one for text. New mar- gins should be set for the new pitch, while the old per- manent margins are maintained to control the headers. Underlining will not work properly in the new pitch unless /U:B is used. 7. If a single font is used throughout, then no attributes need be defined for the font change. 8. Never use letters after ^ or when defining escape sequence labels. Combinations like ^A will defeat the uppercase flag for the letter "A", and /A defeats the lowercase flag for "A".