1. Introduction This document describes additional functionality added to ROFF to support the TOUR (c) Program. No changes to the existing functionality of ROFF have been made. The changes made support decimalization. Decimalization is the automatic numbering of heading and subheading labels in a document. Some formatting control for headings has also been included. 2. Extension to the Roff program 2.1 Specifying heading labels You may label sections of a document by using a heading label directive. Heading labels are entered by using the new .hl command. The command which labeled this section was When the document is run-off'ed ROFF will automatically number heading labels in sequence. This feature allows you to move section of document around without worrying about renumbering sections. TOUR (c) is ideal for this purpose. 2.2 Specifying sub-headings If you are working on a more complicated document, you may wish to place numbered headings within headings. Using this feature, sub-headings are also automatically numbered. The same .hl command is used to specify sub-headings. Sub-headings, however, are bracketed by "set level" commands. The set level commands are to begin a series of sub-headings and to end a series of sub-headings. Headings may be nested 8 deep with the new version of ROFF. For example Any number of lines of text may follow a .hl command. Text does not normally follow a .sl + command, but it may follow a .sl - command. (It would function as a section summary.) 2.3 Page formating for heading labels Five additional commands help control the look of your document when you use heading labels. In the (lazy) spirit of ROFF's ".M" commands, five ".D" commands have been added. They are Note that .d4 and .d5 can be used to create "hanging titles". WARNING The indent feature makes internal use of ROFF's .in command. If you use the .in command within your document, you should take care to use it in relative mode (with "+"'s and "-"'s) rather than absolute mode. 2.4 Periods in the first column By placing two periods in a row, ROFF now allows you to place a period in the first column. The first period is stripped by ROFF, all successive periods will be output. For example, would appear after processing 3. Roff Command Reference May 7, 1981 ROFF This version of ROFF, based on the formatter in Kernighan and Plauger's book SOFTWARE TOOLS, is written in BDS C, and employs the directed i/o functions that go along with that package. Well, half of the directed I/O anyway - it doesn't use redirected input because I wanted to be able to format more than one file at a run. Please ignore any "odd" comments to myself in ROFF1.C and ROFF2.C; I tried to find them all but there may be a few extra silly remarks around. For more details on the directed I/O (NDIO in our version) see NDIO.C Sample calls: A>roff filename1 filename2 filename3 +} this would send the formatted version of these three files to the console and to the printer A>roff filename1 +}]>filename1 this would format filename1 and send it to the printer, console, robot-typewriter, and back to filename1. For more details on using the directed I/O, see NDIO.C Using ROFF, you can make nice printouts of a file, with as little or as much help from the program as you want, depending on the commands. There are default values for all parameters, so if you don't put any commands in at all, your file will come out with filled, right-justified lines. The default line-length is 80 characters; the default page-length is 66 lines per page. "Filled lines" means that as many input words as possible are packed onto a line before it is printed; "non-filled" lines go through the formatter w/o rearrangement. "Right-justified" simply means that spaces are added between words to make all the right margins line up nicely. To set a parameter, use the appropriate commands below. All commands have the form of a period followed by two letters. A command line should have nothing on it but the command and its arguments (if any); any text would be lost. A command argument can be either ABSOLUTE or RELATIVE : minus one Also, all commands have a minimum and maximum value that will weed out any odd command settings (like setting the line spacing to zero, for example. It won't let you do that, but it could be changed if you REALLY have a burning desire to do so). Some commands cause a "break", which is noted in the table below. Before such a command goes into effect, the current line of text is put out, whether it is completely filled or not. (this is what happens at the end of a paragraph, for example.) A line beginning with spaces or a tab will cause a break, and will be indented by that many spaces (or tabs) regardless of the indent value at that time (this is a "temporary indent", which can also be set explicitly). An all blank line also causes a break. If you find that seem to have some lines that are indented strangely, and it's not obvious WHY, look at which commands are causing a break, and which aren't. For instance: this is a line of text <- blank line more text for the machine to play with At first glance it seems obvious that the line "this is a line of text" will be indented zero spaces, but it won't - it will be indented 8. The indent command does NOT cause a break (although the .ti does) so it will not cause the line to be put out before setting the indent value to 8. Then, when the blank line is encountered, it will cause a break - and "this is a line of text" will be indented incorrectly. *********************** Table of Commands ***************************** Command Break? Default Function ------- ------ ------- --------- ---------------------------------------------------------------------- Here's what the page parameters look like: _ _________________________________________________ | | top margin - (includes header) | | |-----------------------------------------------| | | top margin 2 | | |-----------------------------------------------| P | : : | A | :<-indent : | G | : : | E | :lots and lots of silly text and: | L | :other garbage. Get the picture?: | E | :This is a temp. indentation: | N | : : | G | : right margin -> : | T | : : | H | : : | | |-----------------------------------------------| | | margin 3 | | |-----------------------------------------------| | | margin 4 - (includes footer) | - ------------------------------------------------- To change the default for any parameter, simply alter ROFFGLOB recompile ROFF1.c and ROFF2.c, and re-clink them with NDIO.CRL (you can use DIO.CRL, but it doesn't have all the features of NDIO ) ************************************************************ A Few Extra Comments on Some of the Commands: ************************************************************ If you want to center lots of lines, but don't want to count them, do something like this: lots and lots of words to be centered -------------------------------------- To underline a few words on a line: Some of the words in this sentence are underlined WOULD PRODUCE: Some of the words in this sentence are underlined. ---- ---- ----------- (obviously you don't have to turn the fill on and off if it's already on ) ------------------------------------ A new paragrah may be caused by using the temporary indent command, like or by simply beginning the paragraph with a tab, as you would if you were just typing. ------------------------------------ Headers and Footers. A page number can be incorporated into any header or footer by putting a "#" in the title where you want the number to go: Each time this is printed at the top of a page, the current page number will be substituted for the "#". ------------------------------------ If you want to send the output to a file, and don't want the page breaks in there ( that's what I did for this ) set margins 1-4 to zero. 4. I/O redirection 6 MAY 81 :: NDIOC.PAK distributed with ROFF.COM 25 Jan 85 :: Edited to form DIO.DOC by Ed Taychert To activate redirection: Four special arguments may be given on the command line to the generated COM file... >foo causes "putchar" to place characters into the file named "foo" instead of to the console. +foo like >foo except that the characters are ALSO sent to the console. ,+,< or | and the corresponding filename.) You can send the output to more than one thing at once, like so: A>ROFFTOUR infile +)}]>outfile 5. Use and Limitations The extensions made to ROFF are paterned after DSR, a registered trademark of Digital Equipment Corporation. DSR is one of Digital's runoff programs. ROFFTOUR supports only a subset of DSR's decimalization commands. In the future, ROFFTOUR will be enhanced to recognise more of the DSR commands. To guarantee upward compatability with furture versions of ROFFTOUR, do not use numbers as the first charaters of a heading label. For example: will cause future problems, while will always work.