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.INTRODUCTION
I.INTRODUCTION
I.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 MACROS
II.SIMPLE MACROS
II.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 MACROS
III.COMPOUND MACROS
III.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 MACROS
IV.CONCLUDING MACROS
IV.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."