Usenet 1994 January

home *** CD-ROM | disk | FTP | other *** search

/ Usenet 1994 January / usenetsourcesnewsgroupsinfomagicjanuary1994.iso / sources / unix / volume21 / ro / part03 < prev next >

Wrap

Internet Message Format | 1990-02-05 | 48.8 KB

Subject: v21i005: A text formatter with some nroff-like capabilities, Part03/03 Newsgroups: comp.sources.unix Sender: sources Approved: rsalz@uunet.UU.NET Submitted-by: tcamp@dukeac.UUCP (Ted A. Campbell) Posting-number: Volume 21, Issue 5 Archive-name: ro/part03 #! /bin/sh # # This is a shell archive. Save this into a file, edit it # and delete all lines above this comment. Then give this # file to sh by executing the command "sh file". The files # will be extracted into the current directory owned by # you with default permissions. # # The files contained herein are: # # -rw-r--r-- 1 tcamp users 36027 Nov 24 12:50 ro.doc # -rw-r--r-- 1 tcamp users 6666 Nov 10 12:57 ro.qrf # -rw-r--r-- 1 tcamp users 2829 Nov 24 12:50 tmac.m # -rw-r--r-- 1 tcamp users 663 Nov 24 12:50 test.doc # echo 'x - ro.doc' if test -f ro.doc; then echo 'shar: not overwriting ro.doc'; else sed 's/^X//' << '________This_Is_The_END________' > ro.doc X.. \"------------------------------------------------------- X.. \" X.. \" ro.doc X.. \" X.. \" documentation for the ro text formatter X.. \" X.. \" NOTE: This documentation is in "ro" X.. \" format and will not read correctly unless X.. \" it is processed by ro and postprocessed by X.. \" an ro filter. To read the document on X.. \" a computer with the "more" pager, the X.. \" command line: X.. \" X.. \" ro ro.doc | termnull | more X.. \" X.. \" should work. X.. \" X.. \"------------------------------------------------------- X.so tmac.m X.PH "'ro v1.00''\*(DT'" X.PF "''Page #''" X.nr Pi 5 X.nr Ps 1 X.ls 1 X.ll 65 X.sp 2 X.ce X\fBRO.DOC\fR X.sp 1 X.ce X\fBDocumentation for the RO Text Formatter\fR X.sp 2 X.ce X\fICopyright Information\fR: X.nf X X ro, version 1.00: X X Portions copyright (c) 1989 by Ted A. Campbell X Bywater Software X P. O. Box 4023 X Duke Station X Durham, NC 27706 X X Contains portions of ROFF4, Version 1.61 X (c) 1985 by Konrad Kwok X 20 3rd Street, Section M X Fariview Park, X Hong Kong X X Contains portions of ROFF4, Version 1.60 X (c) 1983, 4 by Ernest E. Bergmann X Physics, Building #16 X Lehigh University X Bethlehem, Pa. 18015 X.fi X.P X\"ro" and its predecessor ROFF4 are based on Xthe ROFF text processor described in Brian W. Kernigan Xand P. J. Plauger's now-classic text \fISoftware Tools\fR X(Reading, MA: Addison-Wesley, 1976). X.P XPermission is hereby granted for all commercial and Xnon-commercial reproduction and distribution of this Xmaterial provided this notice is included. X.ne 4 X.sp 2 X.ce X\fIGeneral Description\fR X.P X\"ro" is a text formatter. It is based on the XCP/M ROFF4 formatter, Xwhich was an expanded version of ROFF, itself based on the Xformatter in Kernigan and Plauger's \fISoftware Tools\fR. XIt is written in the C programming language, and has Xbeen successfully compiled on both Unix and DOS Xcomputers. X.P X\"ro" is designed to be downwardly-compatible Xwith the Unix-based "nroff" text formatter, Xand efforts have been made to make this Xversion of ro as much like nroff as possible, Xalthough many nroff features (like Xwithholding traps) are not yet implemented Xin ro. X\"ro" adds some features to nroff, such as Xdebug and verbose modes (using the "-x" and "-v" Xflags, respectively), and a number of predefined Xcommands which are usually implemented as macros Xin nroff (e.g., .HE, which sets a three-part Xpage header). X.P XIncluded with this implementation of ro Xis a package of macros named "tmac.m". XThis implements some of the macros Xfound in the popular nroff-based X\"-mm" macro package. X.ne 8 X.sp 2 X.ce X\fIUsing ro\fR X.sp 1 X\fIInvoking the Program\fR: X.P X\"ro" is command-line based, Xand by default takes its input Xfrom "standard input." XAll output is sent to "standard output." XThe command X.sp X.ti 5 X\ro X.sp Xby itself would simply read input from Xthe keyboard and output to the screen. XUtilizing the command-line "<" and ">" Xoperators in Unix and DOS, you can redirect Xboth the standard input and the standard output. XThus the command X.sp X.ti 5 X\ro <infile >outfile X.sp Xwould take its input from "infile" and send output Xto "outfile." X.P XIt is possible to send output Xdirectly to the printer utilizing Xoutput redirection. In Unix, the command X.sp X.ti 5 X\ro <infile >/dev/lp X.sp Xwould take its input from "infile" and Xsend the output to "/dev/lp", Xwhich is usually implemented as the line printer. XSimilarly, in DOS, the command X.sp X.ti 5 X\ro <infile >prn X.sp Xwould send output to the "PRN" device, Xwhich is normally attached to the printer. X\fBHowever\fR, it is usually undesirable Xto send output directly to a printer X(or the screen, for that matter), Xsince ro output will likely Xinclude unprocessed printer escape codes. XFor this reason, it is deirable to use an Xoutput "post-processor" (see below Xunder \fIUsing a Post-Processor\fR). X.P X\"ro" can also take its input from files named Xdirectly on the command line (without the X\"<" operator). The command X.sp X.ti 5 X\ro infile X.sp Xwould read input directly from "filename", Xand the command X.sp X.ti 5 X\ro file1 file2 file3 X.sp Xwould read input from files "file1", X\"file2", and "file3" successively. XNote that input must be from named files X(and not from standard input) Xif you wish to utilize the "-s" flag Xoption (described below). X.ne 4 X.sp 2 X\fICommand-Line Flags\fR X.P X\"ro" utilizes a number of command-line flags Xto control the program. XAll flags are processed before text input is received. X.P XThe \fB-s\fR flag, causes the formatter to stop (pause) Xat the start of each page of output; a tone at the Xconsole is sounded and the program Xwaits until the RETURN key is pressed. It Xis essential for printers that are fed single sheets Xat a time! X\fBPlease note\fR that to utilize this feature, Xyou must name files directly on the command Xline. (This is because the key-press to resume Xprinting must itself come from standard input.) X.P XThe \fB-o[page or range]\fR flag Xis used to selectively generate output of ONLY certain Xpages. It is useful to retype pages that got "eaten" Xby the printer (Henry Harpending's aptly put language). XTo retype only page 23, say, make the option: -o23 XTo retype pages 23 through 29 use: -o23-29 XTo retype pages 23 to the end use: -23- XThese options changes the values of the internal Xvariables, FIRSTPAGE and LASTPAGE which originally Xhave the values of 1 and 30000, respectively. X.P XThe comamnd-line flag \fB-f\fR will introduce a formfeed (0CH) Xinto the output stream at the bottom of every page. XThis is usefull, e.g., if you want to output in compressed Xpitch where the end of the printed page might not Xcorrrespond to the end of the physical page. X.P XThe flag \fB-v\fR turns on "verbose" mode. XIn this mode, some chit-chatty messages are Xprinted to "standard error" (almost always Xthe console), including some rather important Xerror messages. Normally, only fatal error Xmessages are printed when verbose mode is not on X(because ro is expected Xto do much of its work in the background). X.P XThe option \fB-x\fR turns on the "debug" flag so as to Xprint out lots of diagnostics to the STDERR [console]. XProbably only useful for those who are trying to Xtrace the operation of the formatter for elusive X\"bugs". XSpecifying the "-x" flag will also turn on Xthe "verbose" mode (but not \fIvice versa\fR). X.ne 4 X.sp 2 X\fIDefault Values\fR X.P XUsing ro, you can make nice printouts of a file, Xwith as little or as much help from the program as you want, Xdepending on the commands. There are default values for all Xparameters, so if you don't put any commands in at all, your Xfile will come out with filled, right-justified lines. The Xdefault line-length is 65 characters; the default page- Xlength is 66 lines per page. "Filled lines" means that as Xmany input words as possible are packed onto a line before Xit is printed; "non-filled" lines go through the formatter Xw/o rearrangement. "Adjusted" or "right-justified" simply means that Xspaces are added between words to make all the right margins Xline up nicely. To change a parameter, use the appropriate Xcommands below. All commands have the form of a period Xfollowed by two letters. A command line should have nothing Xon it but the command and its arguments (if any); any text Xwould be lost. X.ne 4 X.sp 2 X\fIUsing a Postprocessor\fR X.P X\"ro" does not handle printer-specific control codes itself; Xinstead, it sends out simple (but consistent) escape Xsequences which have to be "post-processed" by another program Xto fit a particular terminal or printer. XThree example post-processors are provided Xwith ro: X.sp X.nf X termnull strips out all printer codes X termansi prepares sequences for an ANSI- X compatible terminal X termnx10 prepares sequences for the Star X NX10 printer X.fi X.sp XAll of these postprocessors take their input Xfrom standard input, and send their output Xto standard output. X.P XYou can use the "|" ("pipe") operator Xto send the output from ro directly to Xa postprocessor, and you can use "|" again Xto send the post-processor's output to Xa print spooler, pager, or other program. XHere are some useful examples: The command X.sp X.ti +5 X\ro filename | termnull | more X.sp Xinvoles ro with input from "filename", Xpipes its output to termnull, where all Xprinter sequences are stripped away, Xand then sends its output to the "more" Xpager. Utilizing this sequence, one Xcould preview "filename" on any terminal, Xalthough no printer-specific sequences would Xbe shown. For ANSI-compatible terminals X(including DOS computers which have ANSI.SYS Xinstalled), the sequence X.sp X.ti +5 X\ro filename | termansi | more X.sp Xwould do the same as the previous command, Xexcept that boldface would appear Xin bold, and italics would appear underlined Xin the output. XThe Unix sequence X.sp X.ti +5 X\ro filename | termnx10 | lp X.sp Xwould take input from "filename", Xset up sequences for the Star NX10 Xprinter, and send the output Xto the "lp" print spooler. XSimilarly, under DOS, X.sp X.ti +5 X\ro filename | termnull >prn X.sp Xwould take input from "filename", Xstrip out all printer codes, and Xsend the output to the PRN device X(normally attached to the printer). X.P XThe escape codes sent out by ro are simple, and are Xlisted at the end of this document. XWith these and the source code to termnx10 (included), Xit should Xbe relatively easy to write a post-processor Xfor almost any terminal or device. X.ne 8 X.sp 2 X.ce X\fIInput to ro\fR X.sp 1 X\fIInput Text\fR X.P X\"ro" generally reads input until it can fill out Xa complete line of text (specfied by the "line length" Xvariable, set by the command .ll). XBy default, it then "adjusts" or justifies these Xinput line when putting them out. XBoth the "filling" and the "adjustment" of lines Xcan be toggled on and off (see the commands Xdescribed below, .fi, .nf, .ad, .na). X.P XExtra space will separate text sentences. The sentence Xis recognized by a trailing ':',';','!','?', or a '.'. For Xthe '.' there is the additional requirement that either two Xor more spaces must spaces must follow it, or that it is at the Xend of the source line. X.ne 4 X.sp 2 X\fIInput Commands and Their Arguments\fR X.P X\"ro" is controlled internally by commands Xthat are identified by a period ('.') in the Xfirst place on a line. XBe carefull: if you inadvertently place Xa period in the first place in a line, X\"ro" will try to interpret it Xas a command. X\"ro" commands are either one or two letters Xin length, and are all case-sensitive, Xi.e., the command X.sp X.ti +5 X .In X.sp Xis different from the command X.sp X.ti +5 X .in X.sp Xand so on. XBy convention, built-in commands are lower-case, Xand macros (see below) are upper-case; Xhowever, this is not a rule, and we have elected Xto place all non-nroff compatible commands Xin upper case, since this is how they appear Xin nroff implementations. X.P XA command argument can be either ABSOLUTE or RELATIVE : X.br X.nf X.sp X .in 5 sets the indent value to 5 spaces X .in +5 sets the indent value to the CURRENT value+5 X .ls -1 sets the line spacing to the current value-1 X.fi X.P XAlso, all commands have a minimum and maximum value Xthat will weed out any odd command settings (like setting Xthe line spacing to zero, for example. It won't let you do Xthat, but it could be changed (by recompiling Xthe program). X.P XSome commands cause a "break", which is noted in the Xtable below. Before such a command goes into effect, the Xcurrent line of text is put out, whether it is completely Xfilled or not. (this is what happens at the end of a Xparagraph, for example.) A line beginning with spaces or a Xtab will cause a break, and will be indented by that many Xspaces (or tabs) regardless of the indent value at that time X(this is a "temporary indent", which can also be set Xexplicitly). An all blank line also causes a break. If you Xfind that some lines that are indented strangely, and it's Xnot obvious WHY, look at which commands are causing a break, Xand which aren't. For instance: X.sp X.nf X .fi X .ti 0 X this is a line of text X .in 8 X <- blank line X more text for the machine to play with X.fi X.P XAt first glance it seems obvious that the line "this is a Xline of text" will be indented zero spaces, but it won't - Xit will be indented 8. The indent command does NOT cause a Xbreak (although the .ti does) so it will not cause the line Xto be put out before setting the indent value to 8. Then, Xwhen the blank line is encountered, it will cause a break - Xand "this is a line of text" will be indented incorrectly. XThe above example will give the following lines. X.sp X.fi X.ti +5 Xthis is a line of text X.sp X.ti +5 Xmore text for the machine to play with X.br X.in X.P XIt is worthwhile considering placing a ".br", the Xbreak command, before each use of ".in". X.P XCertain system variables are "stacked" to enable Xreversion to earlier environments instead of "hardcoded" Xdefaults. For example: X.sp X.nf X .ls 1 X . X . X .ls X.sp X.fi XThe first command will produce single line spacing (which is Xthe default, but which may have been set otherwise at the Xbeginning of the manuscript). The second command causes Xresumption of the original line spacing (either the default Xor whatever had been chosen previously). Stacked variables Xinclude: linespacing, indent column, line length, Xtranslation flag character, page length, top and bottom Xmargin sizes, unexpandable space character, output width, Xand tabsize. X.nf X.ne 8 X.sp 4 X*********************** Table of Commands ********************* X X Command Break? Default stacked Function X ------- ------ ------- ------- --------- X XA. nroff-compatible commands (* denotes compatibility limitation) X -------------------------------------------------------------- X X .. string no string is "mere" comment X (or end of macro definition) X X .ad no initially on turn right justification X on (use .na to turn off); X only applicable if X "filling" is also on. X X .bp n yes n = +1 begin page numbered n X X .br yes cause a break (this X line is not justified) X X .ce n yes n = 1 center next n lines X X .di name (*) no junk.$$$ diversion file X (see "PREPROCESSOR") X X .de name no define (multiline) X macro ("PREPROCESSOR") X X .ds name string no null string define string replace- X ment ("PREPROCESSOR") X X .em end macro X (see "PREPROCESSOR") X X .ex no immediate abort back to X system X X .fi yes start filling lines X X .ig string no "ignore" string (see ..) X X .in n no n = 10 Yes set indent value to n X X .ll n no n = 65 Yes set line length (right X margin) X X .ls n no n = 1 Yes set line spacing to n X X .na no initially on turn right justification X off (use .ad to turn on) X X .ne n no/yes n = 2 "need" n lines; if have X them no action; else X begins new page X X .nf yes stop filling lines X X .nr name n no n=0 No create or modify X register variable X (see "PREPROCESSOR") X X .pl n no n = 66 Yes sets page length to n X X .pm print macros defined X (for debugging) X X .po no 0 No sets page offset (spaces X at left margin of every X line. X X .so filename no ignored Yes reads named file into X input stream; cannot be X invoked from keyboard X input. X X .sp n yes n = 1 space down n lines X X .ta n no n = 8 Yes sets value of tab space X X .tc c no ~ Yes set translation flag X character, see .tr X X .ti n yes n = 0 set temp. indent of n X X .tm string send message to terminal X (console); like a comment X but displayed to X operator during run. X X X.ne 8 XB. non-nroff-compatible commands (must be upper-case) X -------------------------------------------------- X X .BJ yes break with right X justification (current X line only) X X .DB n no n = 0(NO) set debug flag 1 for X diagnostics X X .EF /../../../ no blanks even footer titling X X .EH /../../../ no blanks even header titling X X .FF n no n = 1(yes) initially, formfeeds X are "off". Can turn X them on. Each page X then terminated with X one formfeed. X X .FO /../../../ no empty sets both even and odd X page footers X X .HE /../../../ no empty sets both even and odd X page headers X X .M1 no n = 2 Yes set topmost margin to n X X .M2 no n = 2 Yes set 2nd top margin to n X lines X X .M3 no n = 2 Yes 1st bottom margin to n X lines X X .M4 no n = 2 Yes bottom-most margin to n X lines X X .OF /../../../ no empty odd page footer title X X .OH /../../../ no empty odd page header title X X .SC c no blank Yes space character; the X visible character X that will be trans- X literated to unexpanded X blank. X X .SR show registers defined X X .SS show strings defined X X .ST n no n = 1 (yes) stop (pause) at each page X start; initially off; X may also be enabled by X the -s option. X X.ne 27 X.sp 2 XHere's what the page parameters look like: X X |<--------output width ------------------------>| X X|- po --| ( "po = page offset") X_ _________________________________________________ X| | top margin(m1) - (includes header) | X| |-----------------------------------------------| X| | top margin 2 | X| |-----------------------------------------------| XP | : : | XA | :<-indent : | XG | : : | XE | :lots and lots of silly text and: | XL | :other garbage. Get the picture?: | XE | :This is a temp. indentation: | XN | : : | XG | : right margin -> : | XT | : : | XH | : : | X| |-----------------------------------------------| X| | margin 3 | X| |-----------------------------------------------| X| | margin 4 - (includes footer,perhaps ff) | X- ------------------------------------------------- X X.fi XMinimum acceptable values for M1, M2, M3, and M4: if M1 is set Xto zero, no header will be shown (even if one was declared). XSimilarly, if M4 is set to zero, no footer will be displayed. X.P XTo change the default for any parameter, you must alter ro.h Xand recompile. X.ne 4 X.sp 2 X\fISome Notes on Input Commands\fR X.P X\fB".ce"\fR. XIf you want to center lots of lines, but don't Xwant to count them, do something like this: X.sp X.nf X .ce 1000 X lots and X lots of words to X be centered X .ce 0 X.sp Xwill give the lines: X.ce 1000 Xlots and Xlots of words to Xbe centered X.ce 0 X.fi X.sp X.P X\fB".ti"\fR. XA new paragraph may be caused by using the temporary indent Xcommand, like X.sp X.nf X .ti +5 X.fi X.sp Xor by simply beginning the paragraph with a tab. X.ne 4 X.sp 2 X\fIHeader and Footer Commands\fR X.P XA page number can be incorporated into any header or Xfooter by putting a "#" in the title where you want the number Xto go: X.nf X .he //This is a witty header title for page #// X.fi XEach time this is printed at the top of a page, the current Xpage number will be substituted for the "#". XEach footer and header are ".in 0", even if text is Xindented. X.P XHeaders and footers are in three parts. These parts are left Xjustified, centered, and right justifed. Any of these three Xparts may be left out. One may pick the Xheaders and footers separately for even and odd pages. For Xexample, one could place even and odd page numbers at the Xbottom outside of each page by: X.sp X.nf X .EF /Page #/// X .OF ///Page #/ X.fi X.P XAny printable character, here the '/', can be used to Xdelimit the three strings that make up the titles, so long Xas it is not the backslash character ('\\') and is Xnot present in any of the three strings. X.P XThe program can be made to wait for the operator to Xload single sheets of paper by the -s option and/or by the Xcommand: .ST X.P XIf you want to send the output to a file, and don't want the Xpage breaks in there set margins 1-4 to zero. X.ne 4 X.sp 2 X\fIPrinter Control Input\fR X.P XAt present, ro recognizes only five sequences Xfor printer control. These, with their input Xsymbols, are: X.sp X.nf X \\fR Switch to Roman Font X X \\fI Switch to \fIItalic\fR Font X X \\fB Switch to \fBBold\fR Font X X \\u Up \uone-half\d line X X \\d Down \done-half\u line X.fi X.sp XThe "Roman" (or perhaps "Regular") font turns off Xboth Italic and Bold fonts. The \\u and \\d Xcommands are useful in depicting superscripts Xand subscripts. X.P XFonts can also be switched using the ".ft" Xinput command. For example, the command X.sp X.ti +5 X .ft R X.sp Xwould set the Roman font for subsequent input. X.ne 8 X.sp 2 X.ce X\fIThe Preprocessor\fR X.sp 1 X\fIString Definitions\fR X.P XIn the following we describe the advanced macro Xpreprocessing features of this formatter which provide users Xwith labor saving tools but which are probably not necessary Xat first. The beginning user may be able to achieve most Xgoals without the "preprocessing", but by using an editor Xmore then otherwise. The more advanced user will begin to Xappreciate these features more. X.P XFor example, in: X.sp XToday, \\*(da, is special. X.sp Xthe block, "\\*(da", would be replaced as this sentence is Xbeing input. If a prior string definition of the form: X X .ds da "January 1, 1983" X.ds da "January 1, 1983" X Xhad been processed previously then the example, after text Xsubstitution, would become: X.sp X.ti +5 XToday, \*(da, is special. X.P XThe string definition command, .ds, expects two arguments: Xa name of one or two characters (case is significant), Xand then either a single word (no whitespace) or Xa string delimited by double quotation marks ("..."). XA single-letter string name is expanded on output Xwhen the letter is preceded by "\\*". XFor example, one could define a string N using X.sp X.ti +5 X .ds N "Alfred E. Newman" X.sp Xand then whenever the sequence \\*N appears Xin the input text, the string "\*N" would Xbe output. XA two-letter string name is expanded on output Xwhen it is preceded by "\\*(". XThus, in the example above, the string "da" Xis defined, and output with "\\*(da", Xyielding "\*(da". Did it work? X.ne 4 X.sp 2 X\fINumber Registers\fR X.P XSimilar to string definitions are number register Xvariables, which are created and modified with the \fB.nr\fR Xcommand. Variables are useful for enumeration such as Xequation numbering: X.sp X.ti +5 X .nr eq 1 X.nr eq 1 X.sp Xwould create a register named "eq" with the current value Xof 1. The the text might use it with, say: X.sp X.ti +5 Xx = y+1 \\n(eq X.sp Xwhich would be converted on input into: X.sp X.ti +5 Xx = y+1 \n(eq X.sp XA subsequent instruction: X.sp X.ti +5 X .nr eq +1 X.nr eq +1 X.sp Xwould take the current value of "eq" and increase it by 1 X(so that it would now be 2 in our example: X.sp X.ti +5 Xa = b+c \\n(eq X.sp Xwould become: X.sp X.ti +5 Xa = b+c \n(eq X.P XNumber Register values are expanded on output Xin a manner similar to string variables, except Xthat "n" (must be lower-case) is used in place Xof "*". Thus the register variable "P" would Xbe expanded by "\\nP", and the register "Pi" Xwould be expanded by "\\n(Pi", just as "eq" Xis expanded by "\\n(eq" above. X.P XThere is a special, reserved insertion, \#\, which Xwill provide the current page number. It should prove Xuseful in setting up tables of contents (see "diversions", Xbelow). X.P XSince we have defined a special register name, '#', Xwe should comment on what happens if you create a register Xinstruction with that name, such as: X.sp X.ti +5 X .nr # +1 X.sp XYou will be changing the value of the page number of the XFOLLOWING pages. This is useful for leaving gaps in the Xpagination for later inclusion of full page illustrations. XThis feature is demonstrated (tested) in the file, MARGINS. XI wish to thank Henry Harpending for suggesting this. X.P X\"ro" includes some predefined number registers Xthat are available to users. These are: X.sp X.nf X dy current day of the month X mo current month as integer (1-12) X yr current year -1900 X.fi X.sp XThus, a user could say, X\"Today's date is \\n(dy/\\n(mo/\\n(yr", Xand this would be ouput as X\"Today's date is \n(dy/\n(mo/\n(yr". X.ne 4 X.sp 2 X\fIUsing Backslashes\fR X.P XThe backslash character has other properties. XIt can be placed into the input by repeating Xit, namely, "\\\\" becomes "\\". (useful for delaying Xsubstitutions). For example, defining: X.sp X.ti +5 X .ds EN "\\n(eq" X.ds EN "\\n(eq" X.sp Xwill identify "EN" with "\\n(eq" and so our equation Xexample above could have been: X.sp X.ti +5 Xa = b + c \*(EN X.sp XDelaying the evaluation of "eq" until EN is invoked X(instead of when it was defined) means that the proper Xnumbering of equations will occur instead of wrongly Xsupplying the value of "eq" from the time that EN was Xfirst created. XUtilizing this technique, Xthe "tmac.m" package defines a macro for the Xcurrent date, which is: X.sp X.ti +5 X .ds DT "19\\\\n(yr/\\\\n(mo/\\\\n(dy" X.ds DT "19\\n(yr/\\n(mo/\\n(dy" X.sp XThis would be expanded using "\\*(DT", Xwhich would produce "\*(DT" (did it work?). X.ne 4 X.sp 2 X\fIMacro Definitions\fR X.P X"Macro" definitions are used when we wish to Xidentify several lines with an insertion. Such definitions Xare created with the .de ["define macro"] and completed with Xthe .. ["end macro"] commands. For example, we might wish Xto use the following sequence over and over again at the Xstart of paragraphs: X.sp X.nf X .sp 1 X .ne 2 X .ti +5 X.fi X.P Xto separate the paragraphs by blank lines, keep them from Xstarting excessively close to the bottom of the page, and Xindenting them 5 spaces to the right of the current left Xmargin. X.nf X.sp X .de P X .sp 1 X .ne 2 X .ti +5 X .. X.fi X.P XSubsequently, whenever we wished to start a paragraph we Xwould create a command line: X.sp X.ti +5 X .P X.sp Xinstead of more tediously creating every time the three Xcommands we mentioned above. X.P XThe names of all macros, strings, and number Xregisters are "case sensitive". That is to say that Xcapitalization and/or lower case are distinguished and, say, X.sp X.ti +5 X .p X.sp XWould not be recognized as the same as the sample macro we Xjust defined. XThe macro is read until a line beginning with ".em" (end macro) Xor simply ".." is reached. X.P XA macro command may contain parameters(s). For example X.sp X.nf X .de He X $0 X .. X.de He X$0 X.. X.fi X.sp Xdefines a simple macro for printing a heading. XWhen the line ".He Heading" Xappears at the beginning of a line, the word "Heading" Xwill be printed, i.e.: X.sp X.He Heading X.P XThe maximum number of parameters for a macro is 10 ($0-$9). XThe parameter(s) must be on the same line of the macro call. XThe parameters are separate by a non-alphanumeric character Xexcept '+' and '-' which Xappear as the first character of the parameter line. If the Xfirst character is a alphanumeric character, then white space Xwill be assumed as the delimiter. An example can be found Xabove. If the require parameter(s) is/are not defined by the Xmacro call, then the parameter(s) will be treated as null Xstring. X.ne 4 X.sp 2 X\fIDiversions\fR X.P XThere is another object formed and used somewhat Xlike a macro; it is called a "diversion (file)" and is Xuseful for making lists such as references [notes] and Xtables of contents. A diversion is created or continued Xwith the command: \fB.di\fR [diversion]. XIt is ended with the same command X(the command to begin the diversion should Xhave a one- or two-letter name argument; Xthe command to end it should have no argument. XA diversion can grow to be quite large and is, in "ro", a Xdisk file. To "regurgitate" the diversion file, its Xname must be entered as a command at the beginning of a line. X.P XFor example, the "tmac.m" macros define .FS X(start footnote -- actually and endnote) Xas including the command ".di no". XInternally, at this point, ro creates a disk file Xnamed "no_ro.div" and begins placing all input Xin this file. XThe macro ".FE" (footnote end) includes the command ".di". XAt this point the diversion to "no_ro.div" is Xceased, and input is again read as normal. XFor each .FS - .FE pair, this sequence is Xrepeated, so that the diversion file collects Xall the footnotes. XFinally, the macro ".PN" (printout notes) Xincludes the command ".no" which ro Xrecognizes as the signal to send out all Xthe material collected in the diversion file. X\".PN" is placed last in the text file, so that Xthe notes follow after the text. X.ne 8 X.sp 2 X.ce X\fIUsing the tmac.m Macro Package\fR X.P XThe file "tmac.m" included with this distribution Xdefines some macros for use in processing documents. XThese are roughly equivalent to the nroff "-mm" macros Xof similar names. XYou can very easily customize this package and add Xto it for your own uses. X.P X\fIParagraph Control\fR. XUsing the tmac.m macros, the command X.sp X.ti +5 X .P X.sp Xis used to begin a paragraph. XThere are two number registers associated with Xthis command: X.sp X.ti +5 X.nf X Ps paragraph spacing, and X.ti +5 X Pi paragraph indent. X.fi X.sp XEach time .P is called, "Ps" lines are skipped, and a Xtemporary indent of "Pi" characters is set. X.P X\fIThe Date String\fR. XWith the tmac.m package, the current date Xis stored in the string "DT" and can Xtherefore be output at any point with \\*(DT. XThis yields "\*(DT", and is used in the page Xheader for this documentation (see at the top of this page). X.P X\fIEndnote Control\fR. XAlthough ro does not currently support footnotes X(because it does not implement a withholding trap), Xthere are three macros and a string definition to Xsupport endnotes. These are: X.sp X.nf X \\*F prints current note number, superscript X .FS starts text of note X .FE ends text of note X .PN prints out all notes collected X.fi X.sp XThe command ".FS" begins diversion to a separate file, Xso you must be careful to end the text of the note with Xthe ".FE" command. Also, be sure to include the ".PN" Xcommand at the point where you want the notes to be Xprinted out (normally at the very end of the file). X.P X\fIFont Control\fR. XThe tmac.m package contains three macros Xconsistent with the "-mm" package for switching Xfonts. These are: X.sp X.nf X .R switch to Roman (regular) font X .I switch to Italic font X .B switch to Bold font X.fi X.P X\fIPage Header and Footer Control\fR. XThe tmac.m package defines two macros Xconsistent with "-mm" which reset page Xheaders and footers: X.sp X.nf X .PH page header X .PF page footer X.fi X.sp XNote that the arguments to these must be three-part titles Xenclosed in double quotation marks, e.g., X.sp X.fi X .PH "'left'center'right'" X.sp XThis differs from the usage of the built-in .HE Xand .FO commands. X.P X\fIText and Block Macros\fR. XFinally, the tmac.m package defines macros Xnot found in "-mm" that I have found helpful Xin writing papers. These are: X.sp X.nf X .TA begin double-spaced text segment X .TZ end double-spaced text segment X .BA begin single-spaced indented block X .BZ end single-spaced indented block X.fi X.ne 8 X.sp 2 X.ce X\fIro Output and Post-Processor Development\fR X.P XThe five sequences to control the printer are Xsen, on output, as the ESCAPE character (0x1b hex, X27 decimal) followed by a single ASCII character. XThese sequences are: X.sp X.nf X ESCAPE 'R' Set Roman Font X X ESCAPE 'I' Set Italic Font X X ESCAPE 'B' Set Bold Font X X ESCAPE 'u' Up One-Half Line X X ESCAPE 'd' Down One-Half Line X.fi X.sp XAn ro postprocessor should intercept any XESCAPE character, then determine based Xon the next character following it what Xcodes to send out. X.P XAs an example, the folowing is the entire Xtext of the "termnx10" postprocessor. XIt should be relatively easy to alter Xthe escape code sequences here to suit any Xprinter. X\fBPlease note\fR that in the version below Xwe have had to doule each backslash character Xso that it would print correctly when output Xby ro. If you want to cut this program Xout of ro.doc to compile it, you'll need Xto convert each double backslash to a single one. X.sp X.nf X X#include "stdio.h" X#include "term.h" X Xchar progname[] = "termnx10"; X Xmain() X { X register int c; X X while( !feof( stdin )) X { X c = getchar(); X switch( c ) X { X case ESCAPE: X getpc(); X break; X case EOF: X break; X default: X putchar( c ); X break; X } X } X } X Xgetpc() X { X register int c; X X c = getchar(); X switch( c ) X { X case ROMAN: X roman(); X break; X case ITALIC: X italic(); X break; X case BOLD: X bold(); X break; X case HALFUP: X halfup(); X break; X case HALFDOWN: X halfdown(); X break; X default: X fprintf( stderr, "%s: unrecognized output escape sequence ESC-0x%x \n", progname, c ); X break; X } X } X Xroman() X { X printf( "\\0335\\033H" ); X } X Xitalic() X { X printf( "\\0334" ); X } X Xbold() X { X printf( "\\033G" ); X } X Xhalfup() X { X printf( "\\033j\\022" ); X } X Xhalfdown() X { X printf( "\033J\022" ); X } X X-------------------------------------------- X XHere's the included "term.h" file: X X-------------------------------------------- X X#define ESCAPE 0x1b X X/** Single-character printer code designations ***/ X X#define ROMAN 'R' /* Restore "roman" or "regular" font */ X /* Should turn off Bold and Italic */ X#define ITALIC 'I' /* Switch to italics or underline */ X#define BOLD 'B' /* Switch to bold */ X#define HALFUP 'u' /* Half-line up */ X#define HALFDOWN 'd' /* Half-line down */ X X.fi X ________This_Is_The_END________ if test `wc -l < ro.doc` -ne 1254; then echo 'shar: ro.doc was damaged during transit (should have been 1254 bytes)' fi fi ; : end of overwriting check echo 'x - ro.qrf' if test -f ro.qrf; then echo 'shar: not overwriting ro.qrf'; else sed 's/^X//' << '________This_Is_The_END________' > ro.qrf X*********************** Table of Commands ********************* X X Command Break? Default stacked Function X ------- ------ ------- ------- --------- X XA. nroff-compatible commands (* denotes compatibility limitation) X -------------------------------------------------------------- X X .. string no string is "mere" comment X (or end of macro definition) X X .ad no initially on turn right justification X on (use .na to turn off); X only applicable if X "filling" is also on. X X .bp n yes n = +1 begin page numbered n X X .br yes cause a break (this X line is not justified) X X .ce n yes n = 1 center next n lines X X .di name (*) no JUNK.$$$ diversion file X (see "PREPROCESSOR") X X .de name no define (multiline) X macro ("PREPROCESSOR") X X .ds /../../../ no null string define string replace- X ment ("PREPROCESSOR") X X .ed (*) no end diversion X (see "PREPROCESSOR") X X .em end macro X (see "PREPROCESSOR") X X .ex no immediate abort back to X system X X .fi yes start filling lines X X .ig string no "ignore" string(see ..) X X .in n no n = 10 Yes set indent value to n X X .ll n no n = 70 Yes sets line length (right X margin) to n X X .ls n no n = 1 Yes set line spacing to n X X .na no initially on turn right justification X off (use .ad to turn on) X X .ne n no/yes n = 2 "need" n lines; if have X them no action; else X begins new page X X .nf yes stop filling lines X X .nr name n no n=0 No create or modify X register variable X (see "PREPROCESSOR") X X .pl n no n = 66 Yes sets page length to n X X .pm no prints currently defined X macros X X .so filename no ignored Yes reads named file into X input stream; cannot be X invoked from keyboard X input. X X .sp n yes n = 1 space down n lines X X .ta n no n = 8 Yes sets value of tab space X X .tc c no ~ Yes set translation flag X character, see .tr X X .ti n yes n = 0 set temp. indent of n X X .tm string send message to terminal X (console); like a comment X but displayed to X operator during run. X X XB. non-nroff-compatible commands (must be upper-case) X -------------------------------------------------- X X .BJ yes break with right X justification (current X line only) X X .CF c no c = '^' Yes to be used as a prefix X to a character that X controls print func- X tions such as ^+,^- X might be used to X bracket superscripts, X somewhat like X WORDSTAR(TM). X X .DB n no n = 0(NO) set debug flag 1 for X diagnostics X X .EF /../../../ no blanks even footer titling X X .EH /../../../ no blanks even header titling X X .FF n no n = 1(yes) initially, formfeeds X are "off". Can turn X them on. Each page X then terminated with X one formfeed. X X .FO /../../../ no empty sets both even and odd X page footers X X .HE /../../../ no empty sets both even and odd X page headers X X .IC c no c = '\' Yes? to specify the char- X acter used for macro X preprocessing to denote X the token that follows. X X .M1 no n = 2 Yes set topmost margin to n X X .M2 no n = 2 Yes set 2nd top margin to n X lines X X .M3 no n = 2 Yes 1st bottom margin to n X lines X X .M4 no n = 2 Yes bottom-most margin to n X lines X X .OF /../../../ no empty odd page footer title X X .OH /../../../ no empty odd page header title X X .OW no n = 80 sets output width for X header and footer title X X .SC c no blank Yes space character; the X visible character X that will be trans- X literated to unexpanded X blank. X X .ST n no n=1(yes) stop(pause)at each page X start; initially off; X may also be enabled by X the -s option. X X ------------------------------------------------------------- X ________This_Is_The_END________ if test `wc -l < ro.qrf` -ne 161; then echo 'shar: ro.qrf was damaged during transit (should have been 161 bytes)' fi fi ; : end of overwriting check echo 'x - tmac.m' if test -f tmac.m; then echo 'shar: not overwriting tmac.m'; else sed 's/^X//' << '________This_Is_The_END________' > tmac.m X.. \"=================================================== X.. \" X.. \" tmac.m X.. \" X.. \" text macros for the "ro" text formatter X.. \" by Ted A. Campbell X.. \" X.. \"=================================================== X.. \" X.. \"=================================================== X.. \" Reset top and bottom margin registers X.M1 6 X.M2 2 X.M3 2 X.M4 6 X.ll 65 X.po 8 X.. \"=================================================== X.. \" Number register "P" -- current page number X.nr P 0 X.. \"=================================================== X.. \" String "DT" -- current date X.ds DT "19\\n(yr/\\n(mo/\\n(dy" X.. \"=================================================== X.. \" Macro "PH" -- page header X.de PH X.nr P +1 X.HE $0 X.. X.. \"=================================================== X.. \" Macro "PF" -- page footer X.de PF X.FO $0 X.. X.. \"=================================================== X.. \" Number register "Ps" -- paragraph spacing X.nr Ps 1 X.. \"=================================================== X.. \" Number register "Pi" -- paragraph indent X.nr Pi 0 X.. \"=================================================== X.. \" Macro "P" -- begin paragraph X.de P X.sp \\n(Ps X.ne 2 X.ti \\n(Pi X.. X.. \"=================================================== X.. \" Macro "R" -- set Roman font X.de R X.ft R X.. X.. \"=================================================== X.. \" Macro "I" -- set Italic font X.de I X.ft I X.. X.. \"=================================================== X.. \" Macro "B" -- set Bold font X.de B X.ft B X.. X.. \"=================================================== X.. \" Number register "Fn" -- current footnote number X.nr Fn 1 X.. \"=================================================== X.. \" String "F" -- print current footnote number superscript X.ds F "\\u\\n(Fn\\d" X.. \"=================================================== X.. \" Macro "FS" -- start footnote X.de FS X.di no X.sp X.ti +5 X\\u\\n(Fn\\d X.. X.. \"=================================================== X.. \" Macro "FE" -- end footnote X.de FE X.di X.nr Fn +1 X.. X.. \"=================================================== X.. \" Macro "PN" -- print footnotes X.de PN X.sp 2 X.ls 1 X.na X.ne 6 X.ce XNOTES X.sp 1 X.no X.. X.. \"=================================================== X.. \" Macro "TA" -- text segment beginning X.de TA X.ls 2 X.nr Pi 5 X.nr Ps 0 X.sp X.. X.. \"=================================================== X.. \" Macro "TZ" -- text segment ending X.de TZ X.ls 1 X.nr Ps 1 X.. X.. \"=================================================== X.. \" Macro "BA" -- block segment beginnning X.de BA X.ls 1 X.nr Pi 0 X.nr Ps 1 X.in +5 X.ll -5 X.sp X.. X.. \"=================================================== X.. \" Macro "BZ" -- block segment ending X.de BZ X.in -5 X.ll +5 X.. X.. \"=================================================== X.. \" X.. \" End of tmac.m X.. \" X.. \"=================================================== ________This_Is_The_END________ if test `wc -l < tmac.m` -ne 129; then echo 'shar: tmac.m was damaged during transit (should have been 129 bytes)' fi fi ; : end of overwriting check echo 'x - test.doc' if test -f test.doc; then echo 'shar: not overwriting test.doc'; else sed 's/^X//' << '________This_Is_The_END________' > test.doc X.so tmac.m X.ls 2 X.nr Pi 5 X.ce X\fBA Test Document\fR X.P XThis is a test document that has been written Xutilizing MicroEMACS 3.9e, and is intended Xto be formatted with the "ro" text formatter. X.P XThis should be \usuper\dscript, Xand this should be \fIitalicized\fR, Xand this should be \fBbold\fR. XHow did it all come out? X.P XThis sentence should be followed by Xthe first end note.\*F X.FS XThis is the text of the first end note. X.FE XThis sentence should be followed Xby the second end note.\*F X.FS XThis is the text of the second end note. X.FE XThis sentence should be followed by Xthe third end note.\*F X.FS XThis is the third end note. X.FE X.sp X.PN X ________This_Is_The_END________ if test `wc -l < test.doc` -ne 33; then echo 'shar: test.doc was damaged during transit (should have been 33 bytes)' fi fi ; : end of overwriting check exit 0