oz@yetti.UUCP (Ozan Yigit) (01/24/86)
Second part of the PROFF user manual
------------- SNIP SNIP ------------------------------
#!/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.2
# This archive created: Fri Jan 24 10:02:30 1986
export PATH; PATH=/bin:$PATH
echo shar: extracting "'proffman.2'" '(17147 characters)'
if test -f 'proffman.2'
then
echo shar: over-writing existing file "'proffman.2'"
fi
sed 's/^X//' << \SHAR_EOF > 'proffman.2'
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 <macro name>"
X\comm DEF
XDefine is used to define a <macro name> 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 "_$<first parameter>". 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 17147 -ne "`wc -c 'proffman.2'`"
then
echo shar: error transmitting "'proffman.2'" '(should have been 17147 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.