The C Users' Group Library 1994 August/wc-cdrom-cusersgrouplibrary-1994-08.iso/vol_300/304_01/ma.src

Text File | 1990-02-14 | 7KB | 174 lines

.nr Pt 1\"Yes, we want pragraph indenting in this paragraph!
.fo //DOCUMENTATION FOR "MA."//
.ce 1
USING "MA."
.sp
.ce 1
E. E. Bergmann
.H "INTRODUCTION"
.P
The file, "ma.", is a collection of device independent macros and
initializations.  It is the first such file for ROFF5 and so will
benefit from further testing and will probably be enhanced in the
future.
.P
It is normally preceeded by a printer initialization file and
followed by the file or files to be formatted.  For example, I am
using an Okidata Microline 92 printer (so I use the printer
initialization file, "ml92.") and I wish to generate a three chapter
work contained in files, "chap1.", "chap2.", and "chap3.".  Assuming
that the relevent files are all accessed from the current directory,
my command line may look like:

C>roff5 ml92 ma chap1 chap2 chap3 )

A second example is to print this documentation:

C>roff5 ml92 ma ma.src )
.P
The purpose of the final ")" is, of course, to redirect the output
of the roff5 formatter to the printer;  it is equivalent to "}prn".
We have generated the file, "ma.doc" by using:

C>roff5 ma ma.doc }ma.doc

.H "SIMPLE MACROS"
.P
We have developed a few simple macros which we recommend studying
their "source code" in the "ma." file to begin to understand writing
one's own macros for special needs and to modify to suit one's own
tastes.
.P
PAGINATION will start placing page numbers at the top center of each
page.  In the file it is automatically invoked by the line:
".wh#10#PAGINATION" which will start it when we have gotten into the
first page.  Since the top of page 1 is already done, pagination
will first be visible on the top of page 2.
.P
Major section headings are achieved with the H macro.  We provide
for left alignment with roman numerals and bold type.  For example,
the header for this section was created with the
line, '.H#"SIMPLE#MACROS"'.
.P
Each paragraph is preceded by the macro command line, ".P".  The
default style is controlled by a number of registers that could be
changed to suit taste.  The spacing between paragraphs is Ps lines;
its default value is 1 blank line.  The register Pt is 1 or 0
depending upon wanting to indent or not (respectively).  The size of
the indent relative to the current margin is controlled by the
number register Pi which has a default value of 5.
.P
To enhance the ".rl" ruler command of roff5, we have a macro
command, ".RL" which will act like the original when given an
argument, but will give a reasonable default ruler when no argument
is supplied.
.P
When we are in fill mode (the default), we can conveniently number
equations or expressions with the ".En" request.  For example, we
can get:

a#=#b#+#c
.En

# d#=#e#+#f
.En

(examine the source of this file to see how it was done!)
.P
Another quick macro line is '.signed "E. E. Bergmann"' which
provides a simple way to end some documents, such as this one.
.H "COMPOUND MACROS"
.P
Many of the useful macros work in cooperation to achieve their
results.  The naming of these macros was chosen to align reasonably
well with the macro packages used in UNIX(R by AT&T) for their text
formatters.  We recommend reading books such as "troff Typsetting
for UNIX(tm) Systems."\rn\
.RS
Sandra L. Emerson and Karen Paulsell, "troff Typesetting for
UNIX(tm) Systems," Prentiss-Hall (New Jersey, 1987) ISBN
0-13-930959-4.
.RF
.P
For example, the pair of macro commands, ".RS" and ".RF",
which are to handle reference starts and finishes, are a convenient
way to provide a means to collect all ones references at the end of
the paper, chapter, or book.  The references are also automatically
numbered at the same time.  To use them, one generally wants to
place in the text a superscripted referenmce number.  This is
achieved with the defined string (created in the macro package with
the ".ds" command), \\rn\\ at the text location.  Immediately after
this place in the source file one should start a new line with the
command, ".RS".  The following lines contain the text that is to be
collected as the reference information and printed at the end of the
document.  This reference information is terminated with a new line
beginning with the macro command, ".RF" (reference finished).\rn\
.RS
I just could not resist creating a reference here to show off!
.RF
.P
One can place the same reference in several places.  To create a
copy of the \\rn\\ named, say, "TAG" to be used later for the same
reference number, one places the name in the reference
start: ".RS#TAG".  Later, for this same reference, one uses \\TAG\\
instead of \\rn\\.
.P
A very similar set of commands exists for figures or illustrations.
The numbering of illustrations is done automatically
.sc _
using the i# number register.  The figure caption is placed after
the macro command line, ".IS <tag>", and followed by the macro
command line, ".IE".  The <tag> is optional and serves the analogous
function we previously described for ".RS".
.P
The production of footnotes (at the bottom of the current page,
instead of references that appear at the end of the document), has
proven the most trying for me.  I have included a demo file, "fs."
to excercise the relevent macros in a large variety of conditions.
We provide the option of automatically numbering or of other means
such as "*" or "**" to label each footnote.  The numbering of
footnotes will run consecutively throughout the document unless one
resets the counter, f# with a command of the form: ".nr f# 1".
A lot of the complexity arises because the amount of space needed on
the page varies and one may run out of space on the current page
under certain circumstances.  We have striven to handle all cases
automatically.
.P
We use the ".FS" and ".FE" (footnote start and footnote end) in a
manner similar to the ".RS",".RF", and ".IS",".IE" pairs.  However,
the optional use of a <tag> in ".FS <tag>" is different;  here we
would use for the <tag> a "*", "**", etc. to substitute for
automatically numbering.*
.FS *
As I have just done here.
.FE
.sc #
.P
To mark where there is an automatic numbering for a footnote, one
uses \\fn\\ as I have at the end of this line.\fn\
.FS
I have just demonstrated an automatic numbered footnote here!
.FE
To change the spacing before each footnote, change the number
register, "Fs";  its default value is 0.
.H "CONCLUDING MACROS"
.P
We have provided a "finish" macro that is the initial choice of end
macro (achieved by using ".em finish").  This "finish" will complete
the production of any remaining footnotes at the end of the
document, generate one or more new pages for references (if needed),
and, if needed, one or more pages for the illustration captions
listing.
.P
It should be educational to examine how this documentation was
created as well as by studying the contents of "ma.".  It should be
emphasized that this macro package is neither necessary nor
complete.  One may be happy without using a macro package, since the
basic ROFF5 formatter does most needed functions without further
elaboration.  One may have very complex needs and wish to achieve a
uniform set of documents with automatic numbering and sub-numbering,
in which case, this initial macro package may provide a starting
point.

.signed "E. E. Bergmann" "730 Seneca Street" "Bethlehem, PA 18015"