Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP Posting-Version: version B 2.10.2 9/5/84; site yetti.UUCP Path: utzoo!utcs!mnetor!yetti!oz From: oz@yetti.UUCP (Ozan Yigit) Newsgroups: net.sources Subject: PROFF - Portable ROFF (5 of 5) Message-ID: <302@yetti.UUCP> Date: Tue, 14-Jan-86 00:02:36 EST Article-I.D.: yetti.302 Posted: Tue Jan 14 00:02:36 1986 Date-Received: Tue, 14-Jan-86 08:48:17 EST Reply-To: oz@yetti.UUCP (Ozan Yigit) Organization: York University Computer Science Lines: 1592 #!/bin/sh # This is a shell archive, meaning: # 1. Remove everything above the #!/bin/sh line. # 2. Save the resulting text in a file. # 3. Execute the file with /bin/sh (not csh) to create the files: # proffman.prf # This archive created: Mon Jan 13 23:54:56 1986 export PATH; PATH=/bin:$PATH echo shar: extracting "'proffman.prf'" '(46207 characters)' if test -f 'proffman.prf' then echo shar: over-writing existing file "'proffman.prf'" fi sed 's/^X//' << \SHAR_EOF > 'proffman.prf' X X.! Proff user's manual X.! Feb. 1984 by Ozan S. Yigit X.! X.! Edited by Steven Tress and Terry Lim X.! vers. 1.0 X.! X.! ----------- macros ---------- X.! sect - produce a bold section header and X.! enter a contents line. First parameter X.! is indent level for contents line. X.define sect X.sp X.cl $1 $2 $3 $4 $5 $6 $7 X.bd X$2 $3 $4 $5 $6 $7 X.en X.! ----------------------------- X.define note X.sp X.ce XNOTE X.sp X.fi X.in +5 X.rm -5 X.en X.define endnote X.sp X.nf X.in -5 X.rm +5 X.en X.! ----------------------------- X.! Macros to create a point-form lists. X.! Note the use of number registers within X.! the macros. See section 5. X.! X.define list X.nr a $1 X.in +$1 X.en X X.define item X.sp X.ti -@na X$1 X.en X X.define nolist X.in -@na X.sp X.en X.! ----------------------------- X.ce 100 X.st 8 XPROFF User's Guide X.sp XVersion 1.0 X.ce 0 X.nf X.in +25 X.sp 15 X*** ******* X*** ********* X ** ** X ** ** X ********* X ******* X ** X ** X ** X****** X**** X.in -25 X.fi X.ce 100 X.st -8 XOzan S. Yigit & Steven Tress XMarch 1984 X.ce 0 X.bp 1 X.he /1.0/Proff User's Guide/#/ X.ap X.fi X.ju X.sect 0 1.0 Introduction X This manual describes PROFF, a formatter based on the FORMAT utility Xpresented in X.ul XSoftware Tools. X PROFF was produced to provide a powerful formatter that can be used under Xa variety of microcomputers, thus providing a consistent formatting tool Xacross environments. PROFF can be used to format memos, reports, form letters Xand Xdocuments such as this manual. It can also be configured to mimic Xother formatting Xsystems of similar nature. X This document itself was produced with PROFF, using most of its advanced features. XPROFF took care of such things as auto-paragraphing and the production of Xthe Table of Contents as the manual was being formatted. X PROFF was developed under a Digital Equipment Corporation Rainbow 100, Xusing Mark Williams C Compiler for portability reasons. PROFF is Xavailable under VAX/VMS operating system. PROFF implementations for XIBM PC and APPLE ][ microcomputers are also underway. X.st -14 XRainbow, VAX/VMS are trademarks of Digital Equipment Corporation. X.br XMark Williams C Compiler is a trademark of Mark Williams Company. X.br XIBM is a registered trademark of International Business Machines Inc. X.br XAPPLE is a trademark of Apple Computer Inc. X.br XUNIX is a trademark of Bell Laboratories. X.bp X.cl X.sect 0 2.0 General Description X.cl X.sect 1 2.1 The Input X The text that is to be formatted by PROFF is typed into an input file Xusing any text editor. This file contains the text to be formatted Xas well as PROFF commands. X Each line in the input file is either a command line or a text line. A Xcommand line is a line that begins with a period ("."). All other lines are Xtext lines. The command lines are not printed - they tell PROFF how you want Xit to format the text that follows. Appendix A summarizes all of the PROFF Xcommands for a quick reference. X.sect 2 2.1.1 Text X Text can be entered into the input file in any format. PROFF removes all extra Xblanks and tabs between words when operating in fill mode. This means you do Xnot have to worry about how many words you put on a line, and you can break Xlines wherever it is convenient to your typing. Note however, that you cannot Xbreak a word between two lines. X Blanks and tabs at the beginning of a line are not removed. This is useful Xfor producing special tables and performing special types of indentation. XThus, normal text lines should not have any leading tabs or blanks. X.sect 2 2.1.2 Commands X A command is a line that starts with a period. Immediately following the Xperiod is a command name. Some commands accept a numeric quantity or a Xcharacter string parameter, which must be separated from the command name Xby a space or a comma. For example, an indent command might appear as follows: X.save X.in +5 X.nf X.nj X.sp X| X|It is to do nothing that the elect exists. X|.in 5 X|- Oscar Wilde X| X.restore X Assuming that the left margin was at column 1, PROFF would produce the Xfollowing: X.save X.in +5 X.nf X.nj X.sp X.need 4 X| X|It is to do nothing that the elect exists. X| - Oscar Wilde X| X.restore X.sp X(In the examples above, as in those following, the vertical line indicates Xthe left edge of input or the left edge of the printed page). X The number following the command may be preceeded by a "+" or "-" sign. XThis plus or minus sign indicates an addition or subtraction of the number Xto or from the current value for the command. for example, the text: X.sp X.save X.in +5 X.nf X.nj X.need 11 X| X|Nothing to do but work, X|.in +3 X|Nothing to eat but food, X|.in -3 X|Nothing to wear but clothes X|.in +3 X|To keep one from going nude. X|.in +7 X|-Benjamin King X| X.in -5 X.sp Xwill produce as output: X.sp X.in +5 X.need 6 X| X|Nothing to do but work, X| Nothing to eat but food, X|Nothing to wear but clothes X| To keep one from going nude. X| -Benjamin King X| X.restore X If a number is not supplied with a command that requires a number, PROFF Xwill use a default value. The defaults for each command are summarized in XAppendix A. X.cl X.sect 1 2.2 The Output X The main functions performed by PROFF are X.ul Xfilling Xand X.ul Xjustifying. XA line is Xfilled by packing as many words onto it as will fit. The line is justified Xby spacing words evenly between the left and right margins. When PROFF starts, Xit assumes that the text is to be filled and justified. Of course, when fill Xand justify are not needed (as in the case of a letter or a table), there are Xcommands to turn these features off, and back on again, as necessary. X When PROFF is in fill mode, it normally strips out extra spaces and tabs Xbetween words. X Many PROFF commands cause a X.ul Xbreak Xto occur in the output. This means that the line currently being filled is Ximmediately output. Any following text goes into a new output line. X.cl X.sect 1 2.3 Executing PROFF X Once a text file is ready for formatting, PROFF is started by typing Xthe program name, various options, name of the input file and the name Xof the output file. For example the command X.sp X.in +5 XA> proff -po5 proffman.prf proff.man X.sp X.in -5 Xwould produce this document as proff.man, from an input file proffman.prf, Xshifted right by 5 spaces. X(The symbol "A>" is CP/M system prompt). X.cl X.sect 1 2.4 Bibliographic Notes X PROFF wa produced by re-writing the Software Tools Formatter FORMAT. XSome of the ideas are from Freshwater Institute RUNOFF, NROFF, XUniversity of Waterloo SCRIPT Xand other formatters of similar nature. The underlying ideas of the Xmentioned above formatters may be found in X.ul XSoftware Tools Xby B.W. Kernighan and P.J. Plauger. 1976. (Addison-Wesley, Reading, Mass.). X.cl X.sect 1 2.5 References and Readings X.nf X.nap X.sp XBrian W. Kernighan and P. J. Plauger, X.ul XSoftware Tools XAddison-Wesley (1976) X.sp XR. Furuta, J. Scofield and A. Shaw, X.ul XDocument Formatting Systems: X.ul XSurvey, Concepts, and issues XACM Computing Surveys, Sept. 1982, Pp. 417 X.sp XMark Stuart Brader, X.ul XAn Incremental Text Formatter XDepartment of Computer Science XUniversity of Waterloo, CS-81-12 X.bp X.fi X.ap X.cl X.sect 0 3.0 Command Descriptions X This section describes PROFF commands. Commands specify how the program is Xto process the text lines in the input file. Lines in the input file that Xbegin with a period (or the control character selected by the user) Ximmediately followed by a command name are commands. Any line that begins Xwith a period and followed by a _# or _! is a comment line and is ignored Xby PROFF - this allows you to put information in the file that will be neither Xprocessed nor output by PROFF. X As described earlier, some of the commands can be followed by "parameters". XParameters are used in executing a command; for example, in the command X".sp 3", the parameter "3" tells the formatter to insert 3 blank lines into Xthe document. The following conventions are used in describing the parameters: X.sp X.in +5 X.ti -2 Xo Parameters surrounded by square brackets are optional. If not supplied, PROFF Xassumes a default value. X.br X(e.g. .sp [n]) X.sp X.ti -2 Xo Parameters surrounded by angle brackets are mandatory. PROFF will display Xa fatal error message if the parameter is absent. (e.g. .set ) X.sp X.ti -2 Xo Parameters surrounded by squiggly brackets are to be typed exactly as Xindicated. (e.g. .pn {roman}) X.sp X.ti -2 Xo A bar character seperating the parameters within brackets indicate an Xalternative. (e.g. .st [+|-][n] means both .st [+n] and .st [-n]) X.in -5 X In describing the commands, the command is typed exacty as accepted by PROFF Xwith the associated control character default ("."). If more than one form of Xthe command is accepted by PROFF, the command names are separated with a Xbar indicating an alternative. X.bp X.cl X.sect 1 3.1 Filling and Justifying X.nap X.in +5 X.! X.! define a simple macro for generating the headers. X.! note that the second "$" within macro is for X.! variable expansion. Initially, the variable name X.! is passed into the macro WITHOUT any expension. X.! we also use the new control character within macro. X.! X.define comm X\sp X\cl 2 $$1 X\ti -5 X$$1 X\sp X.en X.! change the control character from period (".") to a backslash ("\") X.! to avoid the interpretation of the command headers X.! X.cchar \ X\! X\! Variable creation X\! We use variables to avoid re-typing of multiple options over X\! and over again. These variable names will be reused in the X\! appendix to produce a quick referance X\! X\set FILL ".fi | .f | .fill" X\comm FILL XThe fill command causes a line to be filled with as many words as the right Xmargin allows. For this purpose, all extra blanks and tabs are removed between Xwords. Each word is separated with a single blank. PROFF automatically assumes Xfill mode during the startup. X\set NOFILL ".nf | .nofill" X\comm NOFILL XNo fill discontinues the filling of the text. PROFF simply copies the text Xto the output. This command may be used to pass tables and other text Xunaltered through the formatter. X\set JUST ".ju | .j | .justify" X\comm JUST XJustify causes the words on a line to be evenly spaced between the left and Xthe right margins. Note that lines can be justified only if lines are also Xbeing filled. PROFF automatically assumes justify mode during the startup. X\set NOJUST ".nj | .nojustify" X\comm NOJUST XNo justify discontinues the text justification. X\in -5 X\cchar . X.bp X.cl X.sect 1 3.2 Text Formatting X.in +5 X.cchar \ X\set BREAK ".br | .break" X\comm BREAK XBreak causes a break: the current line is printed without justification, Xand the next word is placed at the beginning of a new line. Note that many XPROFF commands cause an implicit break. X\set INDENT ".in | .lm | .leftmargin [+|-][n]" X\comm INDENT XIndent causes a break and indents the following lines [n] spaces to the Xright of the left margin. [n] can be negative to allow beginning a line Xto the left of the left margin, however, a line cannot begin to the left of Xcolumn 0. If a plus or minus sign is used with n, then [n] is added or Xsubtracted to or from the current value. X\set TINDENT ".ti | .i | .left [+|-][n]" X\comm TINDENT XTemporary indent is identical to the indent command except that it Xapplies only to the next line of printed text. Thus, the command X".ti +5" would cause the next line to be printed 5 spaces to the right Xof those that follow. X\set SPACETO ".st | .spaceto [-][n]" X\comm SPACETO XSpaceto allows spacing to line [n] from the top of the current page. XIf a negative [n] is specified, than spacing is performed to line [n] Xfrom the bottom of the page (excluding the footer lines). Thus, footnotes Xcan be set at a fixed distance from the bottom of the page by a command such Xas ".st -5". X\set SPACE ".sp | .s | .skip [n]" X\comm SPACE XSpace causes a break and skips [n] lines, except at the top of Xa page. The space command Xis dependent on the setting of line spacing. X\set CENTER ".ce | .center [n | on | off]" X\comm CENTER XCenter causes the next [n] lines of text to be centered between the left Xand right margins. Centering may be started with "on" and terminated with X"off", in which case all input lines between these commands will be centered. X\set UNDLINE ".ul | .underline [n | on | off]" X\comm UNDLINE XUnderline command causes the text on the next [n] input lines to be underlined Xwhen printed. If [n] is omitted, only the next line is underlined. This command Xdoes not cause a break, so words in filled text may be underlined by: X\sp X\save X\cchar . X.in +5 X.nf X.need 11 X.sp X| X|The "Pay-off" Theory: Only X|.ul X|losers X|believe in luck, horses, horoscopes X|and X|.ul X|lotteries. X| X.in -5 X.sp Xto get X.in +5 X.sp X.fi X| X.br X|The "Pay-off" Theory: Only X.ul Xlosers Xbelieve in X.br X|luck, horses, horoscopes and X.ul Xlotteries. X.br X| X.sp X.restore XUnderlining may be started with "on" and terminated with "off", similar to Xthe centering command. X\set CUNDLINE ".ul | .underline [all | words]" X\comm CUNDLINE XThis version of the underline command is used to set the mode of Xunderlining: X\sp X\nap X\in +5 X\nf Xall - underline across all characters, X including spaces. X\br Xwords - underline words only X\fi X\sp X\in -5 X\ap X\set BOLD ".bd | .bold [n | on | off]" X\comm BOLD XThe bold command causes the text on the next [n] input lines to be highlighted Xby overstriking. If [n] is omitted, only the next line is highlighted. XBolding may be started with "on" and terminated with "off" as in the Xcase of the center and underline commands. X\set DBO ".db | .dbo | .disablebolding" X\comm DBO XTurns the bolding off, all bolding commands are ignored. This feature is Xuseful for rough drafts. X\set EBO ".eb | .ebo | .enablebolding" X\comm EBO XTurns the bolding feature back on. Bolding is turned on during the PROFF Xstartup. X\in -5 X\cchar . X.bp X.cl X.sect 1 3.3 Page Formatting X.in +5 X.cchar \ X\set LS ".ls | .spc | .spacing [n]" X\comm LS XLine spacing is the command to set line spacing. Set n to 1 for single spacing, X2 for double spacing etc. X\set BP ".bp | .pg | .page [n]" X\comm BP XThe begin page command causes a break, ends the current page, outputs Xfooters if required and begins a new page. If [n] is present, the page number Xis set to [n]. The default action is to number the pages incrementally. X\set PN ".pn | .pagenumber {roman} | {arabic}" X\comm PN XPage number command defines the format of the page number. Uppercase roman Xnumerals may be obtained with "roman" keyword. To convert the page numbers Xback to normal, "arabic" is specified. PROFF uses arabic numerals as Xa default. X\set NPA ".np | .nopaging" X\comm NPA XNo paging disables the pagination. When PROFF is in no paging mode, X"begin page" (.bp) and "page length" (.pl) commands are ignored. This mode Xof operation is especially useful for using the proff output with the Xmulti-column formatter (MC). X\set PA ".pa | .paging" X\comm PA XPaging enables normal page generation. This command starts a Xnew page and restores the page length to the Xvalue previous to the ".np" command. X\set NE ".ne | .need | .tp | .testpage [n]" X\comm NE XTest page checks to see whether at least [n] lines remain in the Xcurrent page. If less than this number of lines remain, printing will resume Xat the top of a new page. If [n] is missing, it is assumed to be zero. X\set HE ".he | .header " X\comm HE XHeader sets the text to be printed on top of each page. is Xdivided into sections which are to be left justified, centered and right Xjustified. To divide into these three parts, the first character is Xassumed to be a separator. (e.g. /left/center/right/) But any non-alphanumeric Xcharacter may also be used. The characters "#" and "%" are replaced with the Xcurrent page number and day/time in the header. X\set FO ".fo | .footer " X\comm FO XFooter is identical to header except that it sets the text to be printed Xat the bottom of each page. X\set OHE ".oh " X\comm OHE XThe odd header command sets the header for odd pages only. X\set EHE ".eh " X\comm EHE XThe even header command sets the header for even pages only. X\set OFO ".of " X\comm OFO XThe odd footer command sets the footer for odd pages only. X\set EFO ".ef " X\comm EFO XThe even footer command sets the footer for even pages only. X\in -5 X\cchar . X.bp X.cl X.sect 1 3.4 Page Layout X.ap X These commands are used to specify where on the page you want the formatted Xtext to be placed. The general layout of a page is as follows: X.nap X.need 30 X.nf X X page offset (.po) | X | | X V | X +----+-------------------------------------+----+ -+ X | | top margin (m1) includes header | | | X +----+-------------------------------------+----+ | X | | top margin 2 (m2) | | | X +----+-------------------------------------+----+ | X | | . | | P X | |<-- indent (.in) . | | A X | | . | | G X | | T | | E X | | E | | X | | X | | L X | | T | | E X | | . | | N X | | right margin (.rm) -->| | G X | | . | | T X | | . | | H X | | . | | | X +----+-------------------------------------+----+ | X | | bottom margin 3 (m3) | | | X +----+-------------------------------------+----+ | X | | bottom margin (m4) includes footer | | | X +----+-------------------------------------+----+ -+ X | | X | | X.fi X.in +5 X.cchar \ X\set PO ".po | .offset [+|-][n]" X\comm PO XThe page offset command moves the entire page to the right or left depending on the Xspecified value. All indentation is according to the page offset. PROFF Xassumes a page offset of 0 during the startup. If [n] is specified with a Xplus or minus, it will be added or subtracted from the current value. X\set RM ".rm | .rightmargin [+|-][n]" X\comm RM XRight Margin sets the position of the last printable character from the Xleft edge of the page to [n]. Default value for right margin is 65. XA plus or minus value will be added or subtracted from the current value. XIf [n] is not specified, right margin is set to the default value. X\set PL ".pl | .ps | .pagesize [n]" X\comm PL XPage length is used to set the number of lines that are to be printed Xon a page including the header and footer lines. After [n] lines are printed, Xthe paper will advance to the top of next page. The default page length is X66 lines (11 inches for 6 lines/inch). This command is disabled if nopaging Xis set. X\set M1 ".m1 [n]" X\comm M1 XMargin 1 sets the number of lines (including the header) which will be left at Xthe top of the page to [n]. The default setting is 3. If [n] is omitted, is Xset to the default. X\set M2 ".m2 [n]" X\comm M2 XMargin 2 sets the number of blank lines between the header and the first Xline of text. The default setting is 2. X\set M3 ".m3 [n]" X\comm M3 XMargin 3 sets the number of blank lines between the footer and the last line Xof text. The default setting is 2. X\set M4 ".m4 [n]" X\comm M4 XMargin 4 sets the number of lines (including the footer) which will be left at Xthe bottom of the page to [n]. The default setting is 3. X\in -5 X\cchar . X.bp X.cl X.ap X.sect 1 3.5 Table of Contents X This section describes the the commands that are used to generate a table of Xcontents. Basically, a contents line command is used in every place in Xthe document where an entry is needed in the table of contents. PROFF Xstores the text and the page number when it encounters this command. XAfter the the body of the document is processed, a print contents command Xdumps the contents table. The contents should be dumped in a new page, with Xnofill. Page numbering should be disabled if the table of contents is to be Xused in front of the document. X.sp X.in +5 X.ap X.cchar \ X\set CL ".cl | .contline [ ]" X\comm CL XContents line specifies a line of to be entered into the table of Xcontents. specifies the level at which the item is to be printed Xin the table. When the table is printed, each level of entry will be Xindented by specific number of spaces. X appears in the output exactly as it appears Xin the contents line command, except that leading blanks are removed. XIf no options specified in the contents line, a blank is inserted during Xthe table output. X\set PC ".pc | .printcont [n]" X\comm PC XPrint Contents causes the currently accumulated table of contents to be Xprinted. If [n] is specified, it is used as the indent value for each Xlevel. If [n] is not specified, it is defaulted to 3. X A contents line at level 0 is as wide as rightmargin-indent. The Xoutlook of the table of contents may be changed by altering the right Xmargin and indent values. A typical table of contents may be produced as Xfollows: X\in +5 X\nf X\sp X|.page X|.he //// X|.fo //// X|.nofill X|.sp X|.center X|Table of Contents X|.sp X|.printcont X\in -5 X\fi X\sp XThe following example illustrates the generation of a table of contents. Note Xthat only one table of contents is active for a PROFF session. X\need 40 X\sp X\in +5 X\nf X\nap X.cl X.cl 0 A. Introduction XIntroduction X text X . X.cl X.cl 0 B. Methods XMethods X text X . X.cl 1 a) Sampling Procedures XSampling X text X . X.cl 1 b) Laboratory Procedures XLaboratory X text X . X.cl X.cl 0 C. Results XResults X text X . X . X.pg X.nf X.he //// X.fo //// X.ce XTable of Contents X.sp X.pc X\sp X\in -5 XThese commands will produce the following table: X\sp X\in +5 X Table of Contents X XA. Introduction............................... 1 X XB. Methods.................................... 3 X a) Sampling Procedures..................... 3 X b) Laboratory Procedures................... 4 X XC. Results.................................... 5 X\sp X\in -5 X\fi XMacros may be defined as described in the following sections to help the generation Xof the table of contents. X\cchar . X.in -5 X.bp X.cl X.ap X.sect 1 3.6 Miscellaneous X This section describes miscellaneous commands that radically increase the Xformatting powers of PROFF. With the assistance of variables, PROFF can Xgenerate form letters and documents with dynamic parts. The ability to save Xand restore formatter context eliminates the need to remember the exact Xsettings of the formatter across the document. X.in +5 X.cchar \ X\set VSET ".vs | .set [definition]" X\comm VSET XSet variable defines a variable to be later used in the document. XIf the definition part is left out, PROFF uses the variable name as a prompt Xand allows the user to define the variable interactively. Variable names cannot Xstart with a numeric character, and may only contain alphanumeric Xcharacters. The definition of a variable may not contain any blanks, unless Xthey are surrounded by double-quotes. To get a double quote within a a quoted Xdefinition, two double-quotes are used. X Once the variable is Xdefined, it can be used anywhere in the document, including the command Xline itself. A variable substitution is invoked by a dollar sign (_$). (A Xliteral _$ is inserted into text using ___$). XA variable name must be delimited by a non-alphanumeric character within the Xtext. If the contents of the variable is to be appended to other Xalphanumeric characters, it must be surrounded by wiggly braces X("{" and "}"). The following is an example of variable usage: X\need 12 X\sp X\nf X|.nf X|.vs v1 Murphy X|_${v1}'s first law: X| Nothing is as easy as it looks. X|_${v1}'s second law: X| Everything takes longer than you think. X|Charley's observation: X| Computers were invented by _$v1. X| X\sp XProduces the following: X\sp X\need 8 X| X|Murphy's first law: X| Nothing is as easy as it looks. X|Murphy's second law: X| Everything takes longer than you think. X|Charley's observation: X| Computers were invented by Murphy. X| X\sp X\fi X\set VGET ".vg | .get " X\comm VGET XGet variable is the interactive version of variable definition. In this Xvariant, a prompt string is used to obtain the value of the variable, Xwhich is typed at the user's terminal. If the prompt string is to Xcontain blanks, tabs etc., it must be enclosed in double quotes. No quotes Xare necessary for input text. X\set VRG ".nr [+|-][n]" X\comm VRG XNumber register is used to define registers that contain numeric values. XThere are 26 number registers, named a-z. The command ".nr x n" sets the Xnumber register "x" to value n; ".nr x +n" increments the number register Xby n; ".nr x -n" decrements the number register by n. The value of the Xnumber register x is placed in the text by the appearance of _@nx. A literal X_@ may be inserted using ___@. XNumber registers may be used on command lines and anywhere in the text. X\set CCHAR ".cc | .cchar [char]" X\comm CCHAR XControl Character sets the character that distinguishes PROFF Xcommands from text to be formatted. As a default, control character is set to X(".") period. XThis character may be changed to something other than a period, either Xto mimic other formatters or to disallow interpretation of lines beginning Xwith a period. (This document makes heavy use of the .cc command). X\set ECHAR ".ec | .echar [char]" X\comm ECHAR XEscape Character sets the character that disallows the Xinterpretation of spacial characters such as _@ and _$. PROFF uses an Xunderline ("__") character as a default. X\set SOU ".so | .source | .include | .require [filename]" X\comm SOU XThe source (include) command allows external files to be inserted into the Xinput file Xduring the formatting. Using this feature, tables, graphs and other Xdocuments generated outside PROFF may be included into the document Xbeing formatted. This feature is also very useful in including a common set Xof macros during formatting. Include files may be nested inside other Xinclude files. Currently, PROFF only allows a nested include Xfiles level of 8. Filename may be enclosed in quotes. X\set SAVE ".sv | .save" X\comm SAVE XThe save command allows the saving of the current formatter context on a Xpushdown stack. The saved context of the formatter segment (FSECT) includes Xthe following values and flags: X\need 14 X\sp X\nf X\nap Xvalues flags on | off X------ ----- Xindent (.in) fill (.fi | .nf) Xright margin (.rm) justify (.ju | .nj) Xoffset (.po) paging (.pa | .np) Xline spacing (.ls) number type (.pn) Xpage length (.pl) bolding (.eb | .db) Xmargin values (.m1) autoparagraph (.ap | .na) X (.m2) X (.m3) X (.m4) Xcontrol char (.cc) Xescape char (.ec) X\sp X\ap X\fi X\set RST ".rs | .restore" X\comm RST XThe restore command pops the context stack and restores the values and flags Xas defined above. X\set LEX ".lx | .lex [equate]" X\comm LEX XThe lexical modification command is essentially a permanent replacement of a Xgiven command. This command is used for changing the command names without Xresorting to the macro facility. Lex permanently removes the old Xcommand name from command tables and replaces it with the new definition. XIf the equate is not specified, the command becomes undefined and is Xno longer recognised by PROFF. The command equate should not contain Xnon-alphanumeric characters. X\set APR ".ap | .autoparagraph" X\comm APR XThe autoparagraph command turns on the automatic paragraphing feature. If Xauto-paragraphing is on, every line that starts with a X\ul Xblank Xor a X\ul Xtab Xcharacter starts a new paragraph. A new line is generated (.sp) and Xthe beginning of the paragraph is indented by five spaces. XAutoparagraphing is the equivalent of the following commands: X\in +5 X\nf X| X|textextextextext X|.sp X|.ti +5 X|textextextextext X| X\in -5 X\fi X\set NAP ".na | nap | .noautoparagraph" X\comm NAP XNo Autoparagraph command disables auto-paragraphing. X\set WRT ".wr | .write " X\comm WRT XWrite is a special output command, only to be used to configure printers Xand other output devices with escape sequences. This command outputs the Xassociated string as it is encountered, without going through the normal Xoutput routines of the formatter. Currently, the output string may contain Xcontrol characters specified as "^", decimal numbers within the range Xof 1-255, and other characters. Blanks within the string are skipped. Any Xportion of the string enclosed with double quotes is output as is. To output Xa double quote, two double quotes must be used within the quoted string. XFollowing is a typical string to set a Digital La-100 printer to letter Xquality print mode: X\sp X\nf X\in +5 X| X|.wr ^["[2z" X| X\sp X\fi X\in -5 XIn the control string, "^[" is the ASCII equivalent of the Escape (esc) character. XFollowing mapping table is used to convert characters starting with a caret Xto their binary equivalents: ("|" indicates an alternative) X\nf X\nap X\sp X\in +5 XControl chr Dec. Oct. Hex. X----------- ---- ---- ---- X^a | ^A (soh) 1 01 01 X^b | ^B (stx) 2 02 02 X^c | ^C (etx) 3 03 03 X^d | ^D (eot) 4 04 04 X^e | ^E (enq) 5 05 05 X^f | ^F (ack) 6 06 06 X^g | ^G (bel) 7 07 07 X^h | ^H (bs) 8 10 08 X^i | ^I (ht) 9 11 09 X^j | ^J (nl) 10 12 0A X^k | ^K (vt) 11 13 0B X^l | ^L (np) 12 14 0C X^m | ^M (cr) 13 15 0D X^n | ^N (so) 14 16 0E X^o | ^O (si) 15 17 0F X^p | ^P (dle) 16 20 10 X^q | ^Q (dc1) 17 21 11 X^r | ^R (dc2) 18 22 12 X^s | ^S (dc3) 19 23 13 X^t | ^T (dc4) 20 24 14 X^u | ^U (nak) 21 25 15 X^v | ^V (syn) 22 26 16 X^w | ^W (etb) 23 27 17 X^x | ^X (can) 24 30 18 X^y | ^Y (em) 25 31 19 X^z | ^Z (sub) 26 32 1A X^[ (esc) 27 33 1B X^\ (fs) 28 34 1C X^] (gs) 29 35 1D X^^ (rs) 30 36 1E X^__ (us) 31 37 1F X\sp X\in -5 X\ap X\fi X\cchar . X.in -5 X.bp X.cl X.sect 1 3.7 Defining New Commands (Macros) X In document formatting, it is common to repeat a series of commands at Xseveral places in the document. PROFF allows you to define a new command Xthat will replace these repeated commands. This not only saves typing but Xensures that X.ul Xexactly Xthe same sequence of commands are applied throughout the document. A new Xcommand that you define is formally called a X.ul Xmacro. XTo define a macro, you must use the define macro (.de | .define) and Xend macro (.en) commands. X.in +5 X.cchar \ X\set DEF ".de | .define " X\comm DEF XDefine is used to define a to which a series of commands to Xbe assigned. This definition line is followed by any number of PROFF Xcommands and/or text which define the action that the macro Xwill subsequently produce. Macros may refer to other macros. X\set ENM ".en" X\comm ENM XEnd macro is the last line in the command definition. You must put in this Xcommand to finish a currently defined macro. ".en" command should not be Xre-defined as a macro. X\in -5 X\sp XThe example below defines macros ".note" and ".endnote", similar to the XRUNOFF commands of the same name. X\in +5 X\nap X\nf X\need 20 X\sp X| X|.define note X|.sp X|.ce X|NOTE X|.sp X|.fi X|.in +5 X|.rm -5 X|.en X| X|.define endnote X|.sp X|.nf X|.in -5 X|.rm +5 X|.en X| X\in -5 X\ap X\fi X A macro is used like any other PROFF command, control character followed Ximmediately by the name of the macro. For example, the above macros Xmay be used as follows: X\in +5 X\nap X\need 9 X\nf X\sp X| X|.note X|textextextextextextextextextext X| . X| . X| . X|.endnote X| X\in -5 X\sp X\fi XThe following note is generated by the same macros described previously. X\cc . X.nap X.note XFlap's Law: Any inanimate object, regardless of its position or configuration, Xmay be expected to perform at any time in a totally unexpected manner for Xreasons that are either entirely obscure or else completely mysterious. X.endnote X.fi X.cc \ X\ap XSpecial symbols may be used within a macro definition. These symbols represent Xthe parameters passed to a macro, delimited by blanks or commas. XThese symbols are _$0 for macro name, _$1 for the first parameter, _$2 for Xthe second parameter and so on, up to _$9 for the ninth parameter. Currently, Xmacro parameters may only contain alphanumerics, no string parameters are Xpossible. The previous macro "note" may now be defined as follows: X\in +5 X\nap X\nf X\need 20 X\sp X| X|.define note X|.sp X|.ce X|_$2 _$3 _$4 _$5 _$6 _$7 _$8 _$9 X|.nr m _$1 X|.sp X|.fi X|.in +_$1 X|.rm -_$1 X|.en X| X|.define endnote X|.sp X|.nf X|.in -_@nm X|.rm +_@nm X|.en X| X\in -5 X\ap X\fi X In this version of the "note" and "endnote" macros, the first parameter (_$1) Xis used to pass the value for indentation and right margin adjustment. XAll the rest of the macro parameters (_$2 - _$9) are used as the title of Xthe note. The indent value passed as the first parameter is also saved in the Xnumber register "m" to communicate it to the "endnote" macro, such that Xwhen the endnote macro is called, both indent and right margin values are Xadjusted back to normal. It is possible and may be more useful to use X".save" and ".restore" commands to accomplish the same task, especially if Xthe macro alters the current formatting context drastically. The ".note" Xand ".endnote" macros may be called as follows: X\in +5 X\nap X\need 9 X\nf X\sp X| X|.note 5 Asimov's Law of Robotics X|textextextextextextextextextext X| . X| . X| . X|.endnote X| X\in -5 X\fi X\ap X In this usage, the indent value will be adjusted by +5, right margin will Xbe adjusted by -5, and the title "Asimov's Law of Robotics" will appear Xcentered above the note. X\cchar . X.bp X.cl X.sect 0 4.0 Executing PROFF X The PROFF program may be invoked with a series of optional parameters and Xfilenames on the command line. The command synopsis is: X XPROFF [+n] [-n] [-v] [-s] [-pon] [-ifile] input [output] X XThe square brackets indicate an optional parameter. Interpretation of the Xparameters is as follows: X.nap X.in +10 X.define opt X.need 5 X.sp X.ti -5 X.bd X$1 X.br X.en X.opt +n XStart the printing of the document at the first page with Xnumber n. X.opt -n XStop printing at the first page numbered higher than n. X.opt -v XVerbose mode. PROFF indicates the source files being included into Xdocument, and produces a summary of the number of textlines read in, the number Xof lines and actual pages generated. A memory usage summary of internal Xstorage for macros, stacks and tables is also displayed. X.opt -s XStop before each page, including the first one to allow paper Xadjustment. A prompt is given just before the first page. For each Xpage thereafter, the terminal bell is rung to indicate that another sheet Xof paper is needed. X.opt -pon XSets the page offset to n. This is equivalent to ".po" command within Xthe document. It is recommended that -pon option be used instead of Xembedding the offset value within the document. X.opt -ifile XIncludes the given file to the formatted document. This is equivalent to Xa ".include file" command within the document. This option may be Xrepeated more than once, -ifile1 -ifile2 etc. X.opt input XSpecifies the input file to be formatted. PROFF does not impose any Xfile extension. The recommended extension is ".PRF". X.opt output XSpecifies the output file for the formatted document. If this is omitted, Xoutput is directed to the user's terminal. X.in -10 X XFollowing are some examples of PROFF command lines: X X.ti +5 XA>PROFF -v proffman.prf X XFormat this document (proffman.prf) in verbose mode, and output the Xformatted document to the Xterminal. X X.ti +5 XA>PROFF +5 -imacros.pma proffman.prf X XFormat this document, include the external file MACROS.PMA, skip the first Xfour pages and output the formatted document to the terminal. X X.ti +5 XA>PROFF -po10 proffman.prf proff.man X XFormat this document, shift the entire document by 10 spaces to right and Xoutput to a file called proff.man. X.bp X.cl X.sect 0 5.0 Tips on using PROFF X.ap X.sect 1 5.1 Care and Feeding of Memory X PROFF uses a dynamic memory allocation scheme for some of its operations. XThese are macro definitions, contents lines, variables and save context Xoperation. XRunning PROFF under microcomputers with limited memory resources (64k or less) Xrequire some care in using these commands: X.list 3 X.item a) XDo not declare macros that are not needed within the document. X.item b) XDo not use comments within macros. Due to delayed evaluation, comments Xwill also be stored as a part of the macro definition. X.item c) XWhere possible, avoid using too much text within macros. It is just as Xeasy to pass the information during the macro call. X.item d) XUse only the shortest form of commands within macros. X.item e) XBe brief in contents line text. X.item f) XUse short variable names as long as it is not so cryptic as to be confusing. X.item g) XAvoid unnecessary blanks within the variable definitions. X.item h) XAvoid too many context saves without a corresponding restore. The restore Xoperation reclaims the memory used for a save. X.nolist X Even if the formatter is used with a system of large memory resources, Xsome of the precautions above are applicable. (Utz's 4th law of Computer XProgramming: Any given program will eventually expand to fill all the Xavailable memory.) Using the -v option under memory-restricted systems Xmay be useful in determining the memory usage. X X.sect 1 5.2 Formatting without fuss X PROFF, using its default settings, may provide reasonably formatted output Xin many situations. XAs an example, examine the document PROFF.TUT. This document does not use XANY formatting commands. All formatting is done with the default settings. X X.sect 1 5.3 Variables within macros X Variable expansions may be performed within the macros. Typically, one Xof the parameters of the macro is assumed to be a variable, which is expanded Xonly after the macro is used. Thus: X.in +5 X.nf X X| X|.define xx X|.ce X|_$_$1 X|.cl _$_$1 X|.en X| X X.in -5 X.fi XThe macro xx assumes the first parameter to be a variable, which is Xcentered on the page, and also entered in the table of contents. XNote the usage of "_$_$1". The lines within a macro are scanned from Xright to left for parameter expansion. Thus, "_$1" is expanded first, Xresulting in "_$". This is later expanded as a variable. X X.bp X.cl X.sect 0 6.0 Example macros X X.nf X.in +5 X.cc \ X.! X.! macros to create a point-form lists. X.! note the use of number registers within X.! the macros. X.!------------ X.define list X.nr a _$1 X.in _$1 X.en X.!------------ X.define item X.sp X.ti -_@na X_$1 X.en X.!------------ X.define nolist X.in -_@na X.sp X.en X.!------------ X X\in -5 X\fi XThe "list" macro is used to generate point-form lists. The first parameter Xis an indent value, size of point-str + 1. A typical usage may be as Xfollows: X\need 16 X\in +5 X X\nf X| X|Project work involves: X|.sp X|.list 3 { size-of-point-str + 1 } X|.item a) { "a)" is the point-str } X|choosing a topic X|.item b) X|defining the topic X|.item c) X|research X|.item d) X|organizing the notes X|{etc.} X|.nolist { readjusts the indent } X| X\in -5 X XThe above usage will produce the following: X\need 12 X\in +5 X X| X|Project work involves: X| X|a) choosing a topic X| X|b) defining the topic X| X|c) research X| X|d) organizing the notes X| X X\in -5 X\fi XThe point-form recommendations under section 5.1 (Care and Feeding of XMemory) were generated with the same set of macros described above. X\cc . X.bp X.cl X.sect 0 7.0 Acknowledgements X This document was edited by Terry Lim and Steven Tress. XThe format of the document is largely based on The Freshwater Institute XRUNOFF User's Guide. The Quotes for the various formatting examples are Xfrom THE QUOTABLE NOTHING BOOK and from 1001 LOGICAL LAWS, ACCURATE XAXIOMS, PROFOUND PRINCIPLES, TRUSTY TRUISMS, HOMEY HOMILIES, COLORFUL XCOROLLARIES, QUOTABLE QUOTES, AND RAMBUNCTIOUS RUMINATIONS FOR ALL XWALKS OF LIFE, by Peers, Bennet and Booth, Fawcett Columbine Books, XNew York. X.bp X.cl X.sect 0 Appendix A X.he /1.0/Appendix A/#/ X.cc \ X\nf X\nap X\ce XSummary of Commands X X---------------------------------------------------------- X$FILL X default: initial: yes break: yes X begin filling output lines X---------------------------------------------------------- X$NOFILL X default: initial: no break: yes X stop filling X---------------------------------------------------------- X$JUST X default: initial: yes break: yes X begin justifying filled lines X---------------------------------------------------------- X$NOJUST X default: initial: no break: yes X stop justifying X---------------------------------------------------------- X$BREAK X default: initial: break: yes X cause a break and output current line X---------------------------------------------------------- X$INDENT X default: 0 inital: 0 break: yes X set left margin to column n+1 X---------------------------------------------------------- X$TINDENT X default: 0 initial: break: yes X temporarily indent next output n spaces X---------------------------------------------------------- X$SPACETO X default: 0 initial: break: yes X space to line +n from top X space to line -n from bottom X---------------------------------------------------------- X$SPACE X default: 1 initial: break: yes X space n lines except at top of page X---------------------------------------------------------- X$CENTER X default: 1 initial break: yes X center next n lines X center until turned off X---------------------------------------------------------- X$UNDLINE X default: 1 initial break: no X underline next n lines X underline until turned off X---------------------------------------------------------- X\bp X---------------------------------------------------------- X$CUNDLINE X default: words initial: words break: no X set mode for underline - words or all X---------------------------------------------------------- X$BOLD X default: 1 initial: break: no X boldface (overstrike) next n lines X boldface until turned off X---------------------------------------------------------- X$DBO X default: initial: no break: no X disable bolding X---------------------------------------------------------- X$EBO X default: initial: yes break: no X enable bolding X---------------------------------------------------------- X$LS X default: 1 initial: 1 break: no X set line spacing to n X---------------------------------------------------------- X$BP X default: +1 initial: 1 break: yes X begin a new page and number it n X---------------------------------------------------------- X$PN X default: initial: arabic break: no X set page numbering to arabic or roman X---------------------------------------------------------- X$NPA X default: initial: no break: yes X disable paging X---------------------------------------------------------- X$PA X default: initial: yes break: yes X enable paging X---------------------------------------------------------- X$NE X default: 0 initial: break: yes/no X need n lines. Break and generate a new page X if not available X---------------------------------------------------------- X$HE X default: null initial: null break: no X set header to text (/left/center/right/) X---------------------------------------------------------- X$FO X default: null initial: null break: no X set footer to text (/lef/center/right/) X---------------------------------------------------------- X\bp X---------------------------------------------------------- X$OHE X default: null initial: null break: no X set header on odd pages to text X---------------------------------------------------------- X$EHE X default: null initial: null break: no X set header on even pages to text X---------------------------------------------------------- X$OFO X default: null initial: null break: no X set footer on odd pages to text X---------------------------------------------------------- X$EFO X default: null initial: null break: no X set footer on odd pages to text X---------------------------------------------------------- X$PO X default: 0 initial: 0 break: yes X set page offset to n spaces X---------------------------------------------------------- X$RM X default: 65 initial: 65 break: no X set right margin to column n X---------------------------------------------------------- X$PL X default: 66 initial: 66 break: no X set page length to n lines X---------------------------------------------------------- X$M1 X default: 3 initial: 3 break: no X lines between top of page and header X---------------------------------------------------------- X$M2 X default: 2 initial: 2 break: no X lines between header and text X---------------------------------------------------------- X$M3 X default: 2 initial: 2 break: no X lines between text and footer X---------------------------------------------------------- X$M4 X default: 3 initial: 3 break: no X lines between footer and bottom X---------------------------------------------------------- X$CL X default: initial: break: yes X enter text into table of contents at level X n X---------------------------------------------------------- X\bp X---------------------------------------------------------- X$PC X default: 3 initial: 3 break: yes X print table of contents, indent each level X n spaces X---------------------------------------------------------- X$VSET X default: initial: break: no X set variable to text X---------------------------------------------------------- X$VGET X default: initial: break: no X set variable interactively, using text X as prompt X---------------------------------------------------------- X$VRG X default: 0 initial: 0 break: no X set number register (a-z) to n X---------------------------------------------------------- X$CCHAR X default: "." initial: "." break: no X set command control character to char X---------------------------------------------------------- X$ECHAR X default: "__" initial: "__" break: no X set universal escape character to char X---------------------------------------------------------- X$SOU X default: initial: input break: no X switch input to file X---------------------------------------------------------- X$SAVE X default: initial: break: yes X save the current formatter context on X context stack X---------------------------------------------------------- X$RST X default: initial: break: yes X restore the formatter context from context X stack X---------------------------------------------------------- X$LEX X default: initial: break: no X rename a command X---------------------------------------------------------- X$APR X default: initial: no break: no X enable auto-paragraphing X---------------------------------------------------------- X\bp X---------------------------------------------------------- X$NAP X default: initial: yes break: no X disable auto-paragraphing X---------------------------------------------------------- X$WRT X default: initial: break: no X write a special string to output. line X counter does not change X---------------------------------------------------------- X$DEF X default: initial: break: no X define a macro command - ends at ".en" X---------------------------------------------------------- X$ENM X default: initial: break: no X end the macro definition X---------------------------------------------------------- X\cc . X.bp 1 X.pn roman X.he //// X.fo //- # -// X.ce on XTable Of Contents X XPROFF 1.0 X.ce off X.pc SHAR_EOF if test 46207 -ne "`wc -c 'proffman.prf'`" then echo shar: error transmitting "'proffman.prf'" '(should have been 46207 characters)' fi # End of shell archive exit 0 -- Usenet: [decvax|allegra|linus|ihnp4]!utzoo!yetti!oz Bitnet: oz@[yusol|yuyetti] In the beginning, there was Word all right, except it wasn't fixed number of bits.