home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The C Users' Group Library 1994 August
/
wc-cdrom-cusersgrouplibrary-1994-08.iso
/
vol_300
/
304_01
/
ma.doc
< prev
next >
Wrap
Text File
|
1990-02-14
|
9KB
|
265 lines
USING "MA."
E. E. Bergmann
I.INTRODUCTIONI.INTRODUCTIONI.INTRODUCTION
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.
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 )
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
II.SIMPLE MACROSII.SIMPLE MACROSII.SIMPLE MACROS
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.
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.
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"'.
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
DOCUMENTATION FOR "MA."
-2-
margin is controlled by the number register Pi which has a
default value of 5.
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.
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 (1)
d = e + f (2)
(examine the source of this file to see how it was done!)
Another quick macro line is '.signed "E. E. Bergmann"' which
provides a simple way to end some documents, such as this one.
III.COMPOUND MACROSIII.COMPOUND MACROSIII.COMPOUND MACROS
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
1
"troff Typsetting for UNIX(tm) Systems."
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
2
with the macro command, ".RF" (reference finished).
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\.
A very similar set of commands exists for figures or
illustrations. The numbering of illustrations is done
automatically 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
DOCUMENTATION FOR "MA."
-3-
serves the analogous function we previously described for ".RS".
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.
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.*
To mark where there is an automatic numbering for a
1
footnote, one uses \fn\ as I have at the end of this line. To
change the spacing before each footnote, change the number
register, "Fs"; its default value is 0.
IV.CONCLUDING MACROSIV.CONCLUDING MACROSIV.CONCLUDING MACROS
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.
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.
E. E. Bergmann
730 Seneca Street
Bethlehem, PA 18015
__________
*As I have just done here.
1. I have just demonstrated an automatic numbered footnote here!
DOCUMENTATION FOR "MA."
-4-
REFERENCES __________ REFERENCES __________ REFERENCES __________
1
Sandra L. Emerson and Karen Paulsell, "troff Typesetting for
UNIX(tm) Systems," Prentiss-Hall (New Jersey, 1987) ISBN
0-13-930959-4.
2
I just could not resist creating a reference here to show off!
DOCUMENTATION FOR "MA."