C/C++ Interactive Guide/c-cplusplus-interactive-guide.iso/c_ref/csource5/304_01/ma.doc

Text File | 1990-02-14 | 8.8 KB | 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."