PROFF By: Steven Tress Feb. 1984 INTRODUCTION This is a tutorial for using PROFF, a word processing program that formats documents such as letters, essays, and even books for printing. The structure of the tutorial is oriented for those who have had little or no experience using text formatters. The sections of this tutorial start at the beginner level and end with the most advanced features of PROFF. INPUT PROFF is a text formatter that supports functions such as filling and justifying. It works on a text file that you create with a text editor. The output file can either be specified or can be redirected to a file or device. If no input file and no redirection command is given, the output goes to the console. Text can be entered in any format. Lines can be broken at wherever is convenient, as PROFF ignores whitespace. Spaces at the beginning of a line causes a break. A break means that the line will not be filled or justified. COMMANDS PROFF formats text according to request lines embedded in the text of a document. Request lines begin with a distinguishing 'control character' which defaults to a period. The 'control character' can be changed with a PROFF request. OUTPUT Output lines are automatically filled and justified. The default values are good enough for most applications and PROFF can be used with no request lines but if the margins aren't appropriate or the spacing isn't suitable, they can be changed as needed using the requests available under PROFF. GETTING STARTED This section helps you start formatting right away. It presents the very basic commands needed to adjust parameters such as the margins. In many cases, the default values are suitable; however, if you desire a different format, these commands will help get you started. Left and right margins can be controlled by the requests 'in' and 'rm' preceded by a period, which is the default 'control character'. In the text, the commands would look like this: .in 7 .rm 72 This tells PROFF that left margin is indented 7 spaces. The left margin is at column 8 and the right margin at column 72. Line spacing is specified by the 'ls' request. The request .ls 2 tells PROFF to format the document double spaced. .pl 58 specifies a page length of 58 lines. All numeric arguments can have relative values as well. If a passage form a quote needs to be single spaced, the request .ls -1 will decrease the line spacing from double spaced to single spaced. Similarly, if the passage is to be indented then you could specify .in +5 just before the passage and then .ln -5 to return to the normal left margin. If temporary indentation is needed, then the 'ti' request can be used to specify the indentation of a single line of output. .ti +3 would specify that the next output line be indented three spaces more than the current left margin. .ti -3 would specify an indentation three spaces left of the current left margin. It may be desired to centre a line or two for presentability. The request 'ce' takes care of this. .ce 4 will centre the next four lines within the left and right margins. The 'sp' request is used to tell PROFF to space a number of lines before continuing. .sp 5 will cause five blank lines before the next output line. PROFF justifies and fills text by default. There may be cases where you would want to turn off these features, such as in a table or figure. Justification may be turned off by the '.nj' request and fill by the '.nf' request. To turn on justify and fill again, use the '.ju' and '.fi' commands respectively. These eleven commands should be enough for most purposes. They are the basic commands for contolling the general format of a page of output. The next section deals with enhancing the printed page. It is advised that you practise with the basic commands before preceding to the next section. SUMMARY OF THE BASIC REQUESTS .in n set left margin to column n+1 default=0 .rm n set right margin to column n default=65 .ls n set line spacing to n default=1 .pl n set page length to n lines default=66 .ti n temporarily indent next output line n spaces default=0 .ce n centre the next n input lines default=1 .sp n space n lines, except at top of page default=1 .nf stop filling .nj stop justifying .fi start filling .ju start justifying ENHANCING THE OUTPUT This section deals with making the output appear more attractive. Certain features such as bolding and underlining are sometimes desired to add a finishing touch to a document. In order to bold a line, the .bd request is used. .bd 2 tells PROFF to bold the next two lines. If there is only one word that needs to be bolded, it can be put on a separate line. Remember, PROFF ignores whitespace except if it is at the beginning of a line, therefore lines can be broken and will still be formatted. A feature similar to bolding is underlining. There are two kinds of underlining: continuous underlining and word underlining. .cu 5 specifies that the next 5 lines will be continuously underlined. Similarly, .ul 5 specifies that the words in the next 5 lines will be underlined. Page formatting often enhances the output greatly. Of the better enhancers are headings and footings. .he /l/c/r specifies that the text "l" will be left justified, the text "c" will be centred, and the text "r" will be right justified at the top of the page. Footing is done similarly: .fo /l/c/r The separator need not be a slash (/). PROFF will treat the first character it meets after the request as a separator. In some cases, it may be desired to have different headings and footings depending on whether the page is evenly or oddly numbered. .eh t specifies that the text "t" will be the header on all even pages. The following commands control even and odd headers and footers. .eh even header .oh odd header .ef even footer .of odd footer There are many ways to format the length of your page. The page length request '.pl' was already mentioned. Spacing between headers and footers may also be controlled. .m1 2 specifies that there will be 2 lines between the top of the page and the header. .m2 3 requests three lines between the header and the text. .m3 3 takes care of the spacing between the text and the footer. In this case, there will be a 3 line space, and .m4 2 means there will be a 2 line space between the footer and the bottom of the page. In this example, if .pl 66 specifies a 66 line text, then the number of text lines will be: number of text lines = pl - (m1 + m2 + m3 + m4) = 66 - ( 2 + 3 + 3 + 2) = 56 There is also a request that will allow spacing from the top or bottom of a page. .st 5 will space 5 lines from the top of the page, and .st -5 will space 5 lines from the bottom of the page. The next section is for those who have had some experience with PROFF. It is recommended that you familiarize yourself with the commands covered in the preceding two sections before advancing to the next set of requests. SUMMARY OF INTERMEDIATE REQUESTS .bd n boldface next n lines default=1 .cu n continuously underline next n lines default=1 .ul underline words in the n lines defaut=1 .he /l/c/r head titles are left, centre, right .fo /l/c/r foot titles are left, centre, right .eh t head titles on even pages .oh t head titles on odd pages .ef t foot titles on even pages .of t foot titles on odd pages .m1 n space between top of page and head title default=3 .m2 space between head title and text default=2 .m2 space between text and foot title default=2 .m3 space between foot title and bottom of page default=3 .st n space to line n from top of page, a negative default=0 number spaces to line n from bottom of page default=0 FOR THE ADVANCED USER Now that you have some experience with PROFF, some of the more advanced features will be covered. One of the better features of PROFF is the ability to store commonly used requests in a file. Then all one has to do is include that file and let PROFF do the rest. The request to include a file is presented: .so common.prf This request at the top of your text will instruct PROFF to take more requests from commom.prf. This is especially useful if you are using PROFF for a continuing application. The application might be indicated with a comment, such as .# ycsformat The '#' request indicates that the line will not be written to the output file and will be treated as a comment. For other applications, it may be easier to define your own requests made up of PROFF requests. The following set of requests defines a paragraph request. .de PG .sp .ti +3 .en The requests 'de' and 'en' delimit the definition of 'PG', which can now be used to space one line and indent the next line by three spaces. Parameters can also be used in defintions. Arguments are referenced using _$1, _$2, _$3, up to _$9. _$0 references the command name itself, allowing for recursive defintions. Now we can improve our paragraph request. .de PG .sp .ti +_$1 .en The equivalent of our original definition can now be specified as .PG 3 If the period is to be used in the first column as part of a particular application, the 'control character' can be changed. .cc % changes the 'control character' to a per cent symbol. All requests must be preceded by this symbol instead of the period. If an entire document needs to be offset, the '.po' request is the one for the job. The request line .po 7 will offset the entire page, including diagrams, to be offset by 7 spaces from the left margin. If a break is ever desired, the request .br will cause all formatting to be stopped for the next output line. Beginning a line with a space will have the same effect. Numbers can be inserted anywhere in the text using number registers. .nr a 9 defines the number register 'a' and places the value 9 in it, which can be referenced in the text with '_@na'. (A literal '@' may be inserted by using '___@'). There are a total of 26 number registers named a-z. SUMMARY OF ADVANCED REQUESTS .so file includes an input file .# start of a comment line .de xx defines command xx .en ends command definition .cc c specifies 'c' as the 'control character' default='.' .po n sets page offset to n spaces .br causes a break .nr x n defines number register x and places value n in it EXECUTING PROFF PROFF may be invoked with some command line instructions. The format of the command line looks like this: PROFF [+n] [-n] [-s] [-pon] [file] If the input file is not specified, PROFF uses standard input. Output goes to standard output. Standard input and output can also be redirected to a file or device. Here is a summary of the command line options. Instruction Function +n starts printing at page number n. -n stops printing after page number n. -s stops printing after each page to allow for paper change - a message is given before the first page and the bell is rung thereafter -pon moves the entire document n spaces from the left margin (same as the text request 'po') Combining the command line requests with the text requests can render PROFF a very powerful text formatting tool. Some of the advanced features allow for easy use in special applications; however, PROFF is easy to learn and can be used for any application with a minimum of requests. MISCELLANEOUS The folowing requests are not discussed in the tutorial, but are included for completeness. For more details on these requests, refer to the PROFF User's Guide. .eb enable bolding .db disable bolding .bp n causes a new page to begin with n, if present, as the page number .pn type defines page number format: type can be roman or arabic .np turns off paging .pa restores paging .ne n if less than n lines are available, start new page .cl n enter line in table of contents at level n .pc n print table of contents with offset set to n for each level .vs var def defines a variable to be used in the text preceded with a "_$" .vg var prmpt interactive version of .vs .ec c sets c to be the escape character; defaults to "__" .sv saves the PROFF environment on the stack .rs restores the last saved environment .lx comm eq replaces command with an equate .ap turns on autoparagraphing; causes a paragraph when a line begins with a blank or tab. .na turns off autoparagraphing .wr string writes an output string used in configuring a printer of terminal