ack/mkun/pubmac

." $Header$
.LL 6.5i
.MS T E
\!.TL `\\n(S1``PUBMAC user's guide`
.ME
.MS T O
\!.TL `PUBMAC user's guide``\\n(S1`
.ME
.MS B E
\!.TL '%'''
.ME
.MS B O
\!.TL '''%'
.ME
.SM S1 B S
.IN 5
.N
.AD R
Report no. 4
.N
second revision
.N
.AD B
.N 10
.CS
.SS 14
.BS
PUBMAC
.BE
.N 1
.US
.SS 12
A Set of  NROFF/TROFF-Macros
to Format Publications
.UE
.N 1
User's Guide
.N 2
Third, revised edition
March 1980
.N 11
.SS 10
Katholieke Universiteit Nijmegen
Informatics Department
Nijmegen, The Netherlands.
.CE
.N 8
.U ABSTRACT
.N 1
A set of NROFF/TROFF macros is presented, intended to facilitate the
formatting of a paper for publication purposes.
Predefined macros are supplied for the most frequent activities.
Sectioning, section-numbering, construction
of a table of contents and some other important
facilities are automated.
.S1 Introduction
The UNIX text formatting program NROFF/TROFF
.RS "NROFF/TROFF"
J.F. Ossanna, NROFF/TROFF User's Manual, Bell Laboratories, Murray Hill,
New Jersey
.RE
allows the user to define his own commands via a macro mechanism.
The present paper describes PUBMAC, a set of macros for a set
of very often repeated activities encountered in the text formatting
process for a paper to be published.
.P
These activities comprise e.g. the division of a paper into
sections, the automatic generation of a table of contents, footnote
handling etc.
PUBMAC is intended to simplify the user-interface of NROFF/TROFF in such a way
that it is suitable for use by personnel with little formal training
and no special talent for informatics.
The macro set described in this Guide is designed
by Thijs Zoethout
after the
.RS PUBMAC
H.M. Stahl, PUBMAC User's Guide, Report no.4 revised, Informatica Department,
Nijmegen University
.RE
macro set written by Hans-Michael Stahl for a previous version of NROFF.
The set was later adapted for use on a high-quality laser printer
allowing use of the full range of
.U troff's
capabilities
by E. G. Keizer.
.N
The construction of the macro set was influenced by the SYSPUB macro
set developed for SCRIPT at the University of Waterloo and described
in
.RS "SYSP77" "."
SYSPUB User's Guide, University of Waterloo Computing Centre,
1977
.RE
.P
However, in contrast to SCRIPT, NROFF/TROFF only allows two characters as name for commands,
so that it is quite difficult to select mnemonic command names.
We tried our best to make full use of the expressive power
of two characters...
.P
PUBMAC can be obtained from the author.
Prerequisites for its use are:
.PS
.PT
a machine with the UNIX operating system,
with NROFF or TROFF,
.PT
an output device e.g. a daisywheel printer or laser printer.
.PE
.S2 Invoking PUBMAC
calling NROFF/TROFF with the option
.B -mkun,
e.g.
.DS I 6
.BS
\&troff -mkun file....
.BE
.DE
The reader who desires to make use of further options may consult
[NROFF/TROFF].
Output from the preprocessors
.UW tbl ,
.U eqn
and
.U refer
is recognized by PUBMAC.
.N 1
The commands needed to print the formatted text differ between
installations.
.S2 PUBMAC Input
As for NROFF/TROFF, each line of
the input files for PUBMAC either contains text to be formatted
or is a command line.
A command line begins with a control
character (under PUBMAC ".") followed by the name of a
PUBMAC command or of a NROFF/TROFF request.
Command lines which do not contain a known PUBMAC or NROFF/TROFF
command are ignored without complaints.
.S2 Form of the PUBMAC commands
All PUBMAC commands have a name consisting of one or two capital letters
or a capital letter followed by a digit.
Most commands embedding some text, i.e. a start and an end command,
have a capital
.B S
(for start) and a capital
.B E
(for end)
as second letter to gain at least a bit of systematics.
.P
Some commands may have operands; these have to be enclosed
in double quotes ("), if they contain blanks.
The number of operands is restricted to 9, but operands can
be grouped into one operand by enclosing them in double quotes.
.P
Operands may be optional; this is indicated in the description by surrounding the
operand by square brackets (\ [\ and\ ]\ ).
A sequence of one or more operands is indicated by
one operand followed by ellipses, e.g
.B title... .
.S2  NROFF/TROFF Commands under PUBMAC
As PUBMAC does a lot of administration, NROFF/TROFF commands changing
global values (e.g. linelength, current indentation) nearly
always disturb this administration.
Therefore it is recommended not to use NROFF/TROFF commands
if not stated otherwise.
Also, a NROFF/TROFF command can be renamed and thus not available
any more under the old name.
.N
The renamed commands are:
.DS I
.TS 0
l l s
l l l.
PUBMAC	NROFF/TROFF
\&.PO	.po	set page offset
\&.TL	.tl	define title line
.TE 0
.DE
.S2 PUBMAC Output
Input text to PUBMAC is subject to two formatting processes:
filling and adjusting.
Filling means that output lines are about equally filled
within the current line length;
it is achieved
by taking words from input lines as long until
a complete output line is formed.
A word, in the context of formatting, is any text
surrounded by blanks.
Adjusting means that all output lines are adjusted
to some uniformity.
This is achieved by expanding the blank spaces between
output words as necessary or leaving one or both margins ragged.
.P
Under PUBMAC normally filling and adjusting
are switched on by default, but both may be turned off separately
(within certain limits).
.N 5
.U Acknowledgement
.N
I wish to thank all PUBMAC users,
for their help in finding
errors, and their proposals for correcting them.
.S1 Global Structure
This section describes the basic PUBMAC commands necessary to
divide a paper into sections, paragraphs etc.
If you are using PUBMAC for the first
time, you are recommended to experiment with the commands described
herein on a small document.
.DS I
.TS 0
l l.
\&.RP	select report layout
\&.S1	to create first level sections
\&.S2	to create second-level sections
\&.S3	to create third-level sections
\&.S4	to create fourth-level sections
\&.AP	to start an appendix
\&.SN	to set the start value for section numbers
\&.P	to start a paragraph
\&.A	to start an alinea
\&.PS	to start a list of points
\&.PT	to start a point
\&.PE	to end a list of points
.TE 0
.DE
.S2 Selecting a Layout
PUBMAC offers two kinds of layout:
.PS
.PT
the
.U report layout
which is suited for short papers and technical notes.
.PT
the
.U manual layout
which is thought for larger publications
.FS * .
This PUBMAC user's guide is an example of the
manual layout.
.FE
.PE
When the manual layout is selected, the first page is reserved
as a title page and not counted for page numbering purposes,
no headers and footers are printed on it,
and new sections appear on a new page.
.A
For the report layout no title page is reserved, thus the
output text immediately starts on the first page.
A new section is not forced to appear on a new page.
.A
The manual layout is selected by default;
to select the report layout, use the command
.DS I 6
.BS
\&.RP
.BE
.DE
.UW ( R e P ort).
This command has to appear in the input text before the first
.B .S1
(see below).
.S2 Sections
PUBMAC offers commands
to divide a paper into sections and subsections.
Sections are numbered automatically and their
numbers, titles and page numbers are collected for the table of contents
which can be put out at the end of the report.
.P
To start a new section, use the command
.DS I 6
.BS
\&.S1 title...
.BE
.DE
where
.B title...
is the title of the section.
If the manual report is selected, the section will appear on a new page and the title will be
translated to capital letters and centered.
If the report layout is chosen, the title only will be underlined and PUBMAC
takes care that the title and the first 6 lines of the section
text
will appear on the same page.
The text of a section immediately follows the
.B .S1
command.
.P
A section may be divided further into subsections, which again
may be divided further etc, up to the level 4:
.DS I 6
.BS
\&.S2 title...
\&.S3 title...
\&.S4 title...
.BE
.DE
All subsections will be numbered automatically and their titles
collected for the table of contents.
The title of second-,
third- and fourth-level subsections will be underlined;
to make the underlining continuous,
blanks separating the single words of
.B title...
will be translated to underscores.
PUBMAC takes care, that the title and the first 5 lines of the text
of subsections
will appear on the same page.
.P
As an example, the next section was prefixed by
.B .S2
.BW Appendices .
.S2 Appendices
To start an appendix, use the command
.DS I 6
.BS
\&.AP title...
.BE
.DE
.UW ( AP pendix).
This command acts like
.B .S1
with the exception, that appendices are numbered with capital letters instead of
arabic numbers.
.P
To divide an appendix into further sections, use the
.B .S2, .S3
and
.B .S4
commands as explained above.
.S2 Setting the Section Numbers
Sometimes the need is felt to format a large paper not as a
whole but in parts, especially when the final state
of the paper has not yet been reached. Nevertheless the parts of
the paper should contain consecutive section numbers
and the correct page numbers.
To achieve this, use the command
.DS I 6
.BS
\&.SN s1 [s2 [s3 [s4 [ap]]]]
.BE
.DE
.UW ( S ection
.UW N umbers).
The operands
.B s1, s2, s3, s4
determine the start value for the numbering of following sections and subsections.
The operand
.B ap
serves to set the appendix number to the desired start value.
.P
To get the full table of contents and a complete
bibliography list, the paper must be formatted as a whole.
.S2 Paragraphs
Two commands are supplied to start a new paragraph.
They take care, that at least the first two
lines of a paragraph are not split across a page boundary.
.P
To start a new paragraph, use the
.DS I 6
.BS
\&.P [count [indent]]
.BE
.DE
.UW ( P aragraph)
command. The first line of the paragraph will be indented
by
.B indent
(default is 3) columns and it will be separated from the previous paragraph by
.B count
(default is 1) blank line(s).
.P
If a paragraph should not be preceded by a blank line, use the command
.DS I 6
.BS
\&.A [count [indent]]
.BE
.DE
.UW ( A linea),
which has the same effect as
.B .P
except that the operand
.B count
has the default 0.
.S2 Lists of Points
It is often desired to present a number of related items
as a list of points. The PUBMAC commands
.B .PS, .PT
simplify the creation of such list.
.P
The command
.DS I 6
.BS
\&.PS [style] [indentation] [ [prefix] suffix ]
.BE
.DE
.UW ( P oint
list
.UW S tart)
starts a list of points.
The text of each point is indented from the current left margin and
preceded by a label.
.P
.NE 13
The operand
.B style
selects the labeling style of the points following the
.B .PS
command.
The following styles are available:
.PS
.PT a:
the points are labeled with small letters (a,b,..aa,bb,...);
.PT A:
the points are labeled with capital letters (A,B,..AA,BB...);
.PT i:
the points are labeled with small roman numbers (i,ii,iii...);
.PT I:
the points are labeled with capital roman numbers (I,II,III...);
.PT 1:
the points are labeled with arabic numbers (1,2,3...);
.PE
If
.B style
is not any of these then each point is labeled with the operand
.BW style .
.A
The default is
.DS I 6
.BS
\&.PS -
.BE
.DE
The operand
.B indentation
determines how many columns from the
current left margin the text of the points in the list is to be
indented.
If this operand is not specified, the default value 3 will be used.
All operands remain valid for all points in the list.
.P
If you want the label selected by
.B .PS
to be followed
by an additional string, for instance for labels as
.B 1)
and
.B 2),
use
the operand
.BW suffix .
It determines the string to follow
the point-label selected by
.BW .PS .
The default
.B suffix
is the empty string "".
The operand
.B prefix
determines the string to be inserted before each point label.
.P
To start a point in such a list, use
.DS I 6
.BS
\&.PT [label]
.BE
.DE
.UW ( P oin T ).
The text of the point has to follow on the next
input lines.
The optional operand
.B label
allows the replacement of the label selected
by the
.B .PS
command ("-" or numbers as selected by "style")
for a single point.
If the text of the label is longer than the indentation selected
by
.B .PS,
the text of the point in the output will appear on a new line.
.P
To continue the list of points, simply repeat the
.B .PT
command for every new point.
.P
A list of points is terminated by the command
.DS I 6
.BS
\&.PE
.BE
.DE
.UW ( P oint
list
.UW E nd).
The command returns to the indentation level being
actual when the last
.B .PS
was encountered by PUBMAC.
.P
Lists of points may be nested up to a maximum level of nine.
A
.B .PS
command
inside the actual list will create a new, nested list of
points.
A new numbering style and indentation value
can be selected for this nested list of points.
To return to the previous list of points, use the
.B .PE
command, which also will restore the old operand values.
After being returned to the old list, the numbering
of further points will continue as selected when this list was started.
.P
To give an impression how the
.B .PT
command can be used, the following example is given. The input text:
.DS B
.BS
\&The .PT command can be used
\&.PS a 5 )
\&.PT
\&to construct a list of points which appear marked and
\&properly indented in the output file
\&.PT
\&to give a summary of information related to one point of view
\&.PT
\&to give more detailed information
\&for a given statement in a top-down way
\&.PS i 4 [ ]
\&.PT
\&this is possible in a nested way
\&.PT
\&the maximum level of nesting is nine, which
\&in general will be enough
\&.PE 0
\&.PT
\&in all respects, the .PT command
\&is very useful to construct a "structured" paper.
\&.PE
\&Here the normal text processing continues on the
\&indentation level as it was before the first .PT
\&in this section.
.BE
.DE
produces the following output:
.N 1
The .PT command can be used
.PS a 5 )
.PT
to construct a list of points which appear marked and properly
indented in the output file
.PT
to give a summary of information
related to one point of view
.PT
to give more detailed information
for a given statement in a top-down
way
.PS i 4 [ ]
.PT
this is possible in a nested way
.PT
the maximum level of nesting is nine, which
in general will be enough
.PE 0
.PT
in all respects, the .PT command
is very useful to construct a "structured"
paper.
.PE
Here the normal text processing continues on the
indentation level as it was before the first .PS
in this section.
.P
Another application for points are lists like the
command summary in appendix B.
The whole summary is a list of points preceded by
.B .PS 1 8,
every item in the list is a point started with
.B .PT xx,
where
.B  xx
is the command name.
.S1 Local Layout
Two groups of commands are provided to determine the
local layout:
commands working on lines or groups of lines
(to create empty lines, for indenting, centering,  etc),
and commands working on words (underlining, marking etc).
.DS I
.TS 0
l l.
\&.N [count]	Begin new line, preceded by count blank lines
\&.BP	Begin new page
\&.IS [count]	Start indentating by count columns
\&.IE	End indentation
\&.UN	Undent temporarily
\&.CS	Start centering
\&.CE	End centering
\&.US	Start underlining
\&.UE	End underlining
\&.BS	Start bold type face
\&.BE	End bold type face
\&.NE [count]	Need count lines on the current page
\&.U word...	Underline word...
\&.CU word...	Continuous underline word...
\&.B word...	Bold face word...
.TE 0
.DE 0
.S2 Line Oriented Commands
The command
.DS I 6
.BS
\&.N [count]
.BE
.DE
.UW ( N ewline)
starts a new output line,
preceded by
.B count
blank lines.
If
.B count
is omitted, no blank lines are generated but only a new line is begun.
The command
.DS I 6
.BS
\&.BP
.BE
.DE
.UW ( B egin
.UW P age)
causes PUBMAC to put out the current page and start a new one.
.NE 6
.P
The command
.DS I 6
.BS
\&.IS [left indent [right indent [count]]]
.BE
.DE
.UW ( I ndentation
.UW S tart)
indents the output by
.B left indent
(default is 3) columns at the left margin.
Indents the output by
.B right indent
(default is 0) columns at the right margin,
after generating
.B count
(default 0) blank lines.
.DS I 6
.BS
\&.UN
.BE
.DE
.UW ( UN dent)
undents the next line temporarily, and the command
.DS I 6
.BS
\&.IE [count]
.BE
.DE
.UW ( I ndentation
.UW E nd)
undents the text permanently and
generates
.B count
(default 0) blank lines.
.P
Indentations can not be nested.
All three commands act as a break, i.e. put out a partially filled line.
.P
To center a piece of text, use the commands
.DS I 6
.BS
\&.CS [count]
\&.CE [count]
.BE
.DE
.UW ( C enter
.UW S tart,
.UW C enter
.UW E nd).
All input lines between the two commands will
appear centered, line for line without filling, in the output.
The operand
.B count
specifies the number of blank lines preceding and following the centered text
(default 0).
Both commands act as a break.
For instance, the title page of this report was formatted with the
commands
.DS I 6
.BS
\&.CS
\&PUBMAC
\&.N 1
\&A Set of  NROFF/TROFF-Macros
\&to Format Publications
\&.N 1
\&User's Guide
\&.N 2
\&Third, revised edition
\&March 1980
\&.N 11
\&.CE
.BE
.DE
.P
To underline a piece of text, use the commands
.DS I 6
.BS
\&.US [C]
\&.UE
.BE
.DE
The text between the two commands will appear underlined.
If no operand is specified, only letters and digits will be underlined and
filling will take place.
The optional operand C stands for Continuous underline.
In this mode all characters and spaces will be underlined,
no filling will occur.
.P
To print a piece of text in boldface, use the commands
.DS I 6
.BS
\&.BS
\&.BE
.BE
.DE
.UW ( B old
.UW S tart,
.UW B old
.UW E nd).
The text between the two commands will appear in boldface.
The result highly depends on the output device.
In some cases the effect will be nil.
.P
Normally an input line starting with the control
character "." or "\'" is interpreted as a command.
To consider such lines as normal input,
precede each of them by "\e&".
.NE 5
.P
To assure that a certain piece of text is not split across a page boundary,
use the command
.DS I 6
.BS
\&.NE count
.BE
.DE
.UW ( NE ed)
which has no visible effect if there are still
.B count
lines left on the current output page,
but causes a page eject if not.
.S2 Word Oriented Commands
The following commands all take a list of words as operands
which are subject to a special treatment.
None of the commands causes a break.
.P
To underline a sequence of words, use
.DS I 6
.BS
\&.U word...
.BE
.DE
.UW ( U nderline).
The letters and digits in the operands
.B word...
will appear underlined in the output text.
The command
.P
.DS I 6
.BS
\&.CU word....
.BE
.DE
.UW ( C ontinuous
.UW U nderline)
will underline
.U all
characters,
including the separating spaces.
.P
The command
.DS I 6
.BS
\&.B word...
.BE
.DE
.UW ( B old)
will print the operands
.B word...
in bold face.
The result highly depends on the output device.
.S1 Tables, Figures and Formulas
PUBMAC provides commands which allow the user to
do his own formatting for figures, examples and so on.
Another related group of commands allows the user
to lay special stress on a piece of text.
For these purposes, the following commands are available:
.DS I
.TS 0
l l.
\&.DS	start a display
\&.DS M	start a marked display
\&.DS X	start a boxed display
\&.DE	end a display
\&.DB	allow breaking of following display
.TE 0
.DE
A
.U display
is a text which should be kept together, i.e., if possible,
should not be split across a page
boundary, but moved as a whole to the next page
(however, see
.B .DB
below).
Provisions for several display types are made in PUBMAC.
To start a display, use
.DS I 6
.BS
\&.DS [mode]
.BE
.DE
.UW ( D isplay
.UW S tart),
where
.B mode
determines the kind of display.
To return to normal text processing, invoke the command
.DS I 6
.BS
\&.DE [count]
.BE
.DE
.UW ( D isplay
.UW E nd).
Where the operand
.B count
specifies the number of blank lines following the display (default 1).
.N
All text between both commands is subject to the formatting chosen
by the operands of the selected display.
Restrictions in the use of displays are discussed below.
.S2 Simple Displays
To start a simple display, use the command
.DS I 6
.BS
\&.DS
.BE
.DE
.UW ( D isplay
.UW S tart).
PUBMAC switches to no-format mode
i.e. input text lines are neither filled nor
adjusted.
The user himself has to take care for the formatting, especially that
the input text does not exceed the current linelength.
Other PUBMAC commands may be used inside the display to do
the formatting.
.S2 Marked and Boxed Displays
To lay special stress on a display,
e.g. to achieve more contrast between examples and running text,
it can be
.UW M arked
or
.UW bo X ed.
Optional operands specify the distance of the boundary of the display
from the left and right margin.
To start this kind of display, use the command
.DS I 6
.BS
\&.DS [mark] M [left-indentation]
\&.DS [mark] X [left-indentation] [right-indentation]
.BE
.DE
.UW ( D isplay
.UW S tart
.UW M arked,
.UW D isplay
.UW S tart
.UW bo X ed)
The boundary of the display will be
indented by
.B left-indentation
(default 3) columns from the current left margin.
.N
In the case of a marked display the left hand boundary of the display
will be represented by the
.B mark
character on each line.
.N
In the case of a boxed display the whole boundary of the display will
be indicated by the
.B mark
character.
The right hand boundary of the display will by indented by
.B right-indentation
(default 0) columns from the right margin.
.N
For instance, the input text
.DS I 6
.BS
\&.DS M
\&The marked display can be used
\&to make programming examples, formulae and similar text
\&distinguishable from the running text.
\&.DE
.BE
.DE
produces the output
.DS M
.BS
The marked display can be used
to make programming examples, formulae and similar text
distinguishable from the running text.
.BE
.DE
.S2 Inside the display
Inside simple and marked displays the text will be unformatted,
that is neither filled nor adjusted.
Inside boxed displays the text will be formatted.
.P
Appending
.B I
or
.B Q
operands after the before mentioned operands, allows the user
to control the formatting of the text and specify indentation
inside the boundary of the display.
.N
The possibilities are
.DS I 6
.BS
\&.DS [....] I [left-indentation]
\&.DS [....] Q [left-indentation] [right-indentation]
.BE
.DE
Use of the Q operand
.UW ( Q uoted)
causes
the text inside the display to be formatted.
Use of the I operand
.UW ( I ndent)
causes
the text to be unformatted.
The default for the
.B left-indentation
is 3 columns.
.N
The default for the
.B right-indentation
is
.BW left-indentation .
.P
As an example, the input lines
.DS
.BS
\&This is the sentence preceding the quotation; to start the
\&quotation use the command ".DS Q".
\&.DS Q 15
\&This is the quoted material.
\&Note that it is automatically indented from both margins.
\&To terminate the quotation, use ".DE"
\&.DE
\&This is the first sentence following the quoted text.
.BE
.DE
produce the following output:
.NE 7
This is the sentence preceding the quotation; to start the
quotation use the command ".DS Q".
.DS Q 15
This is the quoted material.
Note that it is automatically indented from both margins.
To terminate the quotation, use ".DE"
.DE
This is the first sentence following the quoted text.
.P
The box
.DS X 10 Q 5
The text within the box display is subject
to the normal PUBMAC formatting, but other PUBMAC commands
can be used to get the desired layout.
.CS
Text for instance can appear
centered
within a box display
.CE
.DE
was created with the input text:
.DS I 6
.BS
\&.DS X 10 Q 5
\&The text within a box display is subject
\&to the normal PUBMAC formatting, but other PUBMAC commands
\&can be used to get the desired layout.
\&.CS
\&Text for instance can appear
\&centered
\&within a box display
\&.CE
\&.DE
.BE
.DE
.S2 Breaking up a Display
Normally a display is moved to the next page, if there is
not enough space left on the current page to hold it completely.
Especially when a display is long,
this can lead to an annoyingly large amount of white paper
caused by the page eject.
.NE 5
The command
.DS I 6
.BS
\&.DB
.BE
.DE
.UW ( D isplay
.UW B reak
allowed),
.B .DS
allows all following displays to be split if necessary.
The same effect for one display only,
can be obtained by appending the operand
.B B
to the
.B .DS
request.
.S2 Restrictions with Displays
.PS
.PT
As already mentioned, the user has to take care in unformatted
displays that the length of the input lines does not exceed
the current output line length;
.ig
especially in multi-column mode too long display text can lead to overprinting
of columns.
..
.PT
To prevent ugly output,
the text of a box display should not be longer than a page.
.PT
It is not possible to nest displays.
.PE
.S2 Tables
The program
.B tbl
can be used to configure complicated tables.
A description of how to use it can be found in
the
.B tbl
user's manual.
.[
%A M. E. Lesk
%T T\s-2BL\s0\(emA program to format tables
%I Bell laboratories
%C Murray Hill, New Jersey
.]
PUBMAC will handle multiple page tables correctly.
To repeat the table's heading on each page it is necessary to
surround the heading with
.B ".TS H
and
.BW .TH .
The
.B ".TS H
command replaces the normal
.B .TS
command.
.S2 Formulas
The program
.B eqn
allows you to express formulas in a rather natural syntax.
For more documentation about how to use
.B eqn
see [UPM75].
.A
The program
.B eqn
converts formula descriptions into NROFF/TROFF commands.
Typical usage is
.DS I 6
.BS
\&eqn file | troff
.BE
.DE
where file contains both the
.B eqn
and PUBMAC requests.
.P
In PUBMAC the requests
.DS I 6
.BS
\&.EQ [I/C] [indent] [L/R number] [R/L number] [count]
\&.EN [count]
.BE
.DE
.UW ( EQ uation,
.UW E quation
.UW e N d)
are recognized.
The first operand of
.B .EQ
can be
.B I
or
.B C
\&, C has the effect of centering the formula on the line and is
the default, I has the
effect of indenting the display by the value of the operand following the
.B I
(default 0).
.P
The following operands allow the formula to be numbered in one or
both margins.
.B L
or
.B R
specify the the formula should be numbered at the Left or Right margin.
The number to be placed in that margin should follow the
.B L
or
.BW R .
.P
The operand
.B count
of
.B .EQ
and
.B .EN
specifies the amount of blank lines to be inserted at the
before and after the
formula.
.S1 Page Format
If you want to use another format than the standard format
which is described below, you only may do this with special PUBMAC
commands:
.DS I
.TS 0
l l.
\&.IN	set standard indentation
\&.PO	set page offset
\&.PN	set page number
\&.PL	set page length
\&.LL	set line length
\&.MS T	define top margin titles
\&.MS B	define bottom margin titles
\&.ME	end titles
\&.IN	set default indent
\&.AD	adjust rigth margin
\&.NA	do not adjust right margin
\&.HY	switch hyphenation on
\&.NH	switch hyphenation off
\&.HC	set hyphenation indicator character
.TE 0
.DE
.S2 The Standard Format
PUBMAC uses the following standard values for the page format:
.DS I
the width of 3 digits for the standard indentation
16.02 cm of text per line
pages of 29.7 cm
25.7 cm of text per page, including the margin titles
2 cm of blank on top of page
the page offset is 0
bottom title of page is "-- % --"
   where % is the current page number in arabic numerals
adjust both margins, fill output lines
hyphenation enabled
.DE
.S2 Setting the Page Offset
If you want to have a larger
blank margin on the left hand side of your paper (e.g. for binding
purposes),
use the command
.DS I 6
.BS
\&.PO offset
.BE
.DE
.UW ( P age
.UW O ffset).
The output will be moved as a whole by
.B offset
columns to the right.
This command should precede all input text.
The default offset is zero, i.e. printing starts at the leftmost
position of the output device.
.NE 10
.S2 Changing the Page Format
To change the length of the page, use the command
.DS I 6
.BS
\&.PL paperlength [textlength [top offset]]
.BE
.DE
.UW ( P age
.UW L ength).
The operand
.B paperlength
determines the physical length of the page (the number of lines
which fit on one sheet of paper);
the operand
.B textlength
determines the number of lines used by PUBMAC (excluding top and bottom margin)
for text output.
If
.B textlength
is not specified it is defaulted to
.BW 26.03cm .
The default value for
.B paperlength
is 29.7cm, which is
the right value A4 paper.
.A
The offset of the text from the top of the paper is given by the operand
.B top offset
(default is 1.8cm).
The sum of
.B textlength
and
.B "top offset"
must be smaller then or equal to
.BW paperlength .
.A
This command must precede all other input text, as it is not
possible to change the page length during the text processing.
.P
To change the linelength, use the command
.DS I 6
.BS
\&.LL length [footnote length]
.BE
.DE
.UW ( L ine
.UW L ength).
The default line length 16.02cm.
The default footnote line length is 10/11 of the line length.
.S2  Head and Foot Titles
To define a head title, to appear at the start of each page, or to change
the standard foot title ("\-\-~%~\-\-") at the bottom of each page,
the commands
.DS I
.TS 0
l l.
\&.MS T	define Top Margin titles
\&.MS B	define Bottom Margin titles
\&.ME	Title End
.TE 0
.DE
are supplied.
As with NROFF/TROFF, the current page number is represented by "%" in the
.B .TL
request.
.P
To define a head title, use the command
.DS I 6
.BS
\&.MS T [E/O] [count]
.BE
.DE
.UW ( M argin
.UW T op text).
The first optional operand allows the definition of different
titles for even and odd numbered pages;
specify
.B E
for titles to appear on even numbered, and
.B O
for titles to appear on odd numbered pages.
If the second operand is omitted, the title defined will
appear on all pages, regardless whether the page number
is even or odd.
The operand
.B count
specifies the number of blank lines between the top margin text
and the start of further text
(default 2).
.A
The text defining the head title
follows on the next input lines. If you want to enter PUBMAC
commands into the title which have to be executed each time the
head title is processed (e.g.
.B .TL
commands), precede the command lines with the character
sequence "\e!".
Commands that affect the general layout,
like
.BW .SS
and
.BW .IN ,
should be used with care.
In general it is wise to reset the altered environment to its
original state at the end of the title definition.
.P
To terminate the title definition, use
.DS I 6
.BS
\&.ME
.BE
.DE
.UW ( M argin
text
.UW E nd).
.P
Equivalent to head titles, foot titles can be defined. Use
.DS I 6
.BS
\&.MS B [E/O] [count]
.BE
.DE
.UW ( M argin
.UW B ottom
text) to start the input of the foot title. Use
the command
.B .ME
to terminate the foot title definition, too.
.P
The foot titles of this manual, for instance, have been
defined by:
.DS I 6
.BS
\&.MS B E
\&\e!.TL \'%\'\'\'
\&.ME
\&.MS B O
\&\e!.TL \'\'\'%\'
\&.ME
.BE
.DE
This example also shows the usage of the escape sequence
"\e!",
which prevents both
.B .TL
commands from being executed during the definition
of the titles, and causes them to be executed every time a new page
is processed.
This is essential to get the current page number
and not the page number being actual when the title is defined.
.NE 4
.P
To delete the standard foot title, simply define an empty foot title:
.DS I 6
.BS
\&.MS B 0
\&.ME
.BE
.DE
.S2 Setting the Standard Indentation
The value used for indenting paragraphs, after section start,
indented and quoted displays, and for the command
.B .IS,
by default is set to 3.
This value can be changed by invoking the command
.DS I 6
.BS
\&.IN [indent]
.BE
.DE
.UW ( IN dentation).
After this command, further sections, paragraphs etc. are indented by
the number of columns specified by
.BW indent .
If no indentation at all is desired, specify
.B 0
as operand.
.B Indent
has as default value 3.
.S2 "Page Number"
Sometimes a paper is formatted in parts.
The number of the first page of a certain part will not
always be 1.
The command
.DS I 6
.BS
\&.PN number [style]
.BE
.DE
.UW ( P age
.UW N umber)
allows you to use a different start value for page numbers.
The
.B style
operand
can have one of the values: a, A, i, I and 1.
These letters have the same meaning as for the
.B style
operand of the
.B .PS
request.
The new number ( and format ) becomes valid at the next printed page,
or at the first page if given before any text.
.S2 Adjusting
As already has been mentioned, the default mode for formatting
is filling and adjusting.
.A
Adjusting can be switched off
by the command
.DS I 6
.BS
\&.NA
.BE
.DE
.UW ( N o
.UW A djust).
All text following will not be aligned to a uniform right margin,
until a
.DS I 6
.BS
\&.AD [type]
.BE
.DE
.UW ( AD just)
is encountered, which switches on adjusting again.
The operand
.B type
can be one of the following,
.PS i 5
.PT "~~R"
Right adjusted: uniform right margin, ragged left margin
.PT "~~L"
Left adjusted: uniform left margin, ragged right margin
.PT "~~C"
Centered: both margins ragged by the same amount
.PT "~~B"
Both adjusted (default): uniform left and right margin
.PE
.S2 Hyphenation
Hyphenation can be switched off globally by using the command
.DS I 6
.BS
\&.NH
.BE
.DE
.UW ( N o
.UW H yphenation).
.NE 6
.N
The command
.DS I 6
.BS
\&.HY
.BE
.DE
.UW ( HY phenation)
enables hyphenation again.
.P
A second possibility is to use the command
.DS I 6
.BS
\&.HC character
.BE
.DE
(set
.UW H yphenation
.UW C haracter),
which determines the operand
.B character
to be the indicator character for hyphenation.
I.e. a word will be hyphenated
at the points indicated by this character.
The character itself will not appear in the
output, even if the word is not hyphenated.
Example:
.DS I 6
.BS
\&.HC `
\&    .....
\&    ... Algo`rithmus ...
.BE
.DE
This occurence of
.B Algorithmus
will now, if necessary, be hyphenated as
.BS
Algo-rithmus.
.BE
.A
To prevent a word to be hyphenated at all,
it has to be preceded by the hyphenation indicator character, e.g.
.BW `Algorithmus .
.S1 Footnotes, Table of Contents, Bibliography
PUBMAC provides commands for the creation of
footnotes, a table of contents and a list of bibliograpy.
.P
The following commands are available:
.DS I
.TS 0
l l.
\&.FS	start a footnote
\&.FN	start numbered footnote
\&.FE	end a footnote
\&.CT	put out the table of contents
\&.RS	start a bibliography reference
\&.RF	start a reference
\&.RE	end a bibliography reference
\&.RT	give list of bibliography
.TE 0
.DE
.S2 Footnotes
Three commands are provided to create a footnote.
Footnotes appear on the bottom of the page where they are
defined; if the remaining place on the page is too small
for the text of a footnote it will be shifted to the bottom of the next page.
.P
To start a footnote text, use the PUBMAC command
.DS I 6
.BS
\&.FS [prefix] indicator [ suffix ]
\&.FN [prefix] [suffix]
.BE
.DE
.UW ( F ootnote
.UW S tart,
.UW F ootnote
start
.UW N umbered).
.B indicator
allows to identify the footnote:
it will appear in the output text at the place where
.B .FS
was encountered in the input text, and it will appear at the start
of the footnote text.
.P
The
.B .FN
request has as default indicator a number.
This number is automaticaly incremented at each occurence of a
.B .FN
request.
The footnote counter is reset to one for each new section, when
in manual mode.
.A
The operand
.B suffix
is meant for the special case that
a full stop, comma, semicolon etc. immediately has to follow
the footnote indicator in the output text (otherwise the special
character and the indicator would be separated by a blank, or even worse,
by a newline).
The operand
.B prefix
serves a similar purpose.
.A
If only two of the three operands are specified, the last is
interpreted as the prefix.
.P
To end the text of a footnote, the command
.DS I 6
.BS
\&.FE
.BE
.DE
.UW ( F ootnote
.UW E nd)
is used. If the footnote is referenced in the middle of a sentence,
the rest of the sentence has to follow the
.B .FE
on the next line.
.NE 5
.P
As an example
.FS (*) ,
this is an example of a footnote
.FE
the footnote at the bottom of this page was created by the following
input lines:
.DS I 6
.BS
\&As an example
\&.FS (*) ,
\&this is an example of a footnote
\&.FE
\&the footnote at the .....
.BE
.DE
This example also shows the usage of the operand
.B suffix
of the
.B .FS
command, you see that the indicator "(*)"
is followed by "," immediately without a separating space.
.S2 Table of Contents
As mentioned above, all titles of sections are saved for a table
of contents.
To put out the table of contents,
at the end of the input text invoke the command
.DS I 6
.BS
\&.CT
.BE
.DE
.UW ( C ontents
.UW T able).
The table of contents collected up to now is put out and then deleted.
No headers or new page commands are generated.
This gives one the flexibility to put out the table of contents
for example at
the end of each chapter on a separate page or at the end of the
text in an appendix.
To have the pages on which the table of contents is printed, numbered
with roman numbers starting
with "i", use the command
.B .PN 1 i
before the
.B .CT
command.
The table of contents can then be inserted
before the front page of your paper instead of at the end.
In report mode the table of contents is also entered in the table of contents.
.S2 Bibliography
Besides supporting the
.U refer
utility PUBMAC provides
commands to collect literature references and
to print them at the desired place.
.A
To generate an entry in the bibliography and to refer to it, use
.DS I 6
.BS
\&.RS [prefix] refname [suffix]
.BE
.DE
.UW ( R eference
.UW S tart).
The text following this command is saved for the bibliography.
Similar to the operands of the footnote command ,
.B refname
is placed in the running output text and at the start of the
bibliography entry.
.B refname
will be enclosed in square brackets
(\ [ and\ ]\ ).
.B suffix
and
.B prefix
have the same meaning as with the footnote command.
PUBMAC commands for formatting the bibliography text have to be escaped
by "\e!", as the layout of the bibliography is determined
when the
.B .RT
command is invoked.
.P
.NE 8
If you want to create an entry without referring to it
in the text explicitely, use the command
.DS I 6
.BS
\&.RF refname
.BE
.DE
.UW ( R e F erence
start).
The result is the same as with
.B .RS,
but
.B refname
will not appear in the running text.
.P
To terminate a bibliography entry, use the command
.DS I 6
.BS
\&.RE
.BE
.DE
.UW ( R eference
entry
.UW E nd),
which will switch back to normal text
processing.
.P
To put out the collected bibliography, invoke the command
.DS I 6
.BS
\&.RT
.BE
.DE
.UW ( R eference
.UW T able).
The bibliography collected up to now is put out and then deleted,
so that it is possible to start a new bibliography.
In this way, bibliographies can be made either per section
or for the whole paper.
The bibliography is put out in the format being chosen the
point at which the
.B .RT
command is invoked.
.S2 Using refer
The program
.B refer
can be used to add references to articles mentioned in a
systemwide database, a private database or in the text.
It places an indicator in the text and the reference in a footnote
on the same page.
If the
.I \-e
option of
.B refer
is used the references will appear at the appropiate place.
The
collected references have to be surrounded by appropiate
PUBMAC commands.
.S2 Indeces
Commands are provided to collect index words accompanied by the number
of the page they occur.
Another command causes the list of collected index words to be printed
on NROFF/TROFF's error output.
.A
To add an index entry to the list use
.DS I 6
.BS
\&.IX index-word ...
\&.IW [prefix] index-word [suffix]
\&.IR index-word ...
.BE
.DE
The arguments of the
.B .IX
.UW ( I nde\c
.UW X )
and
.B .IW
.UW ( I ndex
.UW W ord)
commands appear in the running text,
as opposed to
.B .IR
.UW ( I ndex
.UW R ference)
whose arguments only appear in the index list.
.B Suffix
and
.B prefix
have the same meaning as with the footnote command.
.A 1
The collected references can be produced
on NROFF/TROFF's error output with the command
.DS I 6
.BS
\&.IT
.BE
.DE
.UW ( I ndex
.UW T able).
By redirecting the error output of NROFF/TROFF
one can save this list for further processing.
.DS I
.BS
troff -mkun files .... 2>indeces
awk -f .... indeces | troff -mkun
.BE
.DE
.A
The index entries are produced on one line each with the index words
enclosed in square brackets and
inmediatly followed by the appropiate page number.
An example:
.DS I 6
.BS
[indeces]\n%
.BE
.DE
.S1 Special Considerations
This section discusses
the use of the tabulator, special characters and some other special
facilities in PUBMAC.
.S2 Tabulator
The tabulator stops in PUBMAC are set to
.DS I 6
.BS
9,17,25,33,....
.BE
.DE
by default.
To set the tabulator positions to your needs, use
.DS I 6
.BS
\&.ta pos...
.BE
.DE
(set
.UW TA bulator),
which will set the tabulator stops to the
positions indicated by
.B pos...
If pubmac is used in conjuction with
.B tbl
the tab stops will be heavily used by tbl and thereby rendered
almost unusable outside the tables.
.S2 Special characters
.SP
The character
"~"
is replaced by the unpaddable space character,
which permits tying two or more words together so that
they will neither be moved apart nor split across two lines.
For example, if you want the words
"integral number denotation" not to be separated by more
than one blank, enter them as
.BW integral~number~denotation .
.P
The command
.DS I 6
.BS
\&.SP [character]
.BE
.DE
allows you to use any other character as indicator for the unpaddable space.
If you specify no operand, you will have no single character to
indicate a unpaddable space.
.SP ~
.P
Since the backslash character "\e" is used heavily by NROFF/TROFF as escape
character,
it has to be written twice if one wants to see it back in the output.
As the text of displays is processed several times,
even a doubled backslash will be lost.
Therefore a backslash in a display should be entered
either eight or a higher power of 2 times (which is a nuisance) or as "\ee".
.S2 Halfline Motions
NROFF/TROFF, thus also PUBMAC, provides the
possibility for half line motions, e.g. for formatting
mathematical formulas.
The sequence
.B \ed
moves down half a line, and the sequence
.B \eu
moves up half a line.
The output
.N 1
        (i\d1\u - i\d2\u)\u2\d
.N 1
was produced with the input
.DS I 6
.BS
(i\ed1\eu - i\ed2\eu)\eu2\ed
.BE
.DE
Usage of
.B \ed
and
.B \eu
can result in messy output on devices
not capable of performing half line motions; messy output
also will result if not the same number of "ups" and "downs" is
used.
.P
Typically lineprinters and display terminals can not perform half line
motions, whereas the HyPrint devices are capable of doing so.
.P
See also the section describing the use of
.B eqn
with PUBMAC.
.S2 The Actual Section Number
The actual section numbers are stored in registers named
.B Sn,
where
.B n
stands for any of the digits 1, 2, 3, 4 and 5.
If you want to refer to it, access it in the input text through
.B \en(Sn,
which will be replaced in the output text by the current section
number of the corresponding section depth.
For example if you wish to insert the number of the current chapter
use
.BW \en(S1 .
The register named S5 is used for the numbering of appendices.
.A
To use it in a page title definition, two backslashes have to be written:
.BW \e\en(Sn .
The first line of the page header of
this manual, for instance, has been produced by entering the
command
.DS I 6
.BS
\&\e!.TL \'PUBMAC users guide\'\'\e\en(S1\'
.BE
.DE
when defining the head title with the commands
.B .MS T
and
.B .ME
(see previous chapter).
.SM AP A
.AP "Error messages"
Besides error messages issued by NROFF/TROFF,
messages from PUBMAC may be written to the users terminal
(Unix error output file 2).
The messages have the following form:
.DS I 6
.BS
Error (p=.., l=..): message
.BE
.DE
.B message
gives information about the kind of error encountered.
The location of the error is described between the parentheses
in the order
.DS I
p = page number
l = line number on the page
.DE
Additionally, errors are marked by three plus signs (\(pl\(pl\(pl) or a \(lh
.DS I 6
.BS
\&\(lh Error
.BE
.DE
appearing on the right margin of the output text.
Since many errors are detected much too late,
the actual error is always located before the location stated.
.LL
.AP "Command Summary"
In the summary, the following abbreviations are used for operands:
.VS 0.8 0.2
.PS - 6
.PT n
denotes a number (e.g. '1', '5', '231')
.PT c
denotes a single character (e.g. 'i', 'F', 'O')
.PT w
denotes a word (e.g. 'NROFF', 'pubmac')
.PT w...
denotes a sequence of 1 or more words
(e.g. 'Table of Contents')
.PE
.VS
.N 4
.PS 1 14
.PT Command
Explanation
.PT .A [n]
.B Alinea.
.N
First line of alinea will be indented.
.N
The alinea will be preceded by n (default 0) blank lines.
.PT .AD [c]
.B Adjust mode.
.N
Left, Right, Centered or Both.
.NE 3+1
.PT ".AP w..."
.B Appendix.
.N
Same as .S1.
.NE 6+1
.PT ".B w..."
.B Boldface.
.N
Write the words given as operands w... in
bold face letters (this is done in a output device dependant way).
.PT .BE
.B Bold end.
.N
End of bolt text.
.PT .BP
.B Begin page.
.PT ".BS"
.B Bold start.
.N
All following text is printed in bold face up to .BE.
.N
The way bold face is printed depends on the output device.
.NE 10
.PT .CE
.B Centering end.
.N
The centered text will be followed by n blank lines.
.NE 3
.PT .CS
.B Centering start.
.N
Following input lines up to .CE will be centered.
.N
The centered text will be preceded by n blank lines.
.NE 10+1
.PT ".CT"
.B Table of contents.
.N
All titles collected from previous .S1, .S2, .S3, .S4 and .AP commands
are put out.
.PT ".CU w..."
.B Continuous underline.
.N
Like .U only all characters are underlined.
.NE 4+1
.PT .DB
.B Display break.
.N
Allow the following displays to be broken
up, if necessary.
.PT .DE [n]
.B Display end.
.N
The display will be followed by n (default 1) blank lines.
.NE 6+1
.PT ".DS "
.B Display.
.N
A display is text
which is kept together and not spread over a page boundary.
.N
The operands determine the kind of display.
The first few operands are:
.N
.PS - 4
.PT B
.B box display
.N
the text between .DS B and .DE
will be surrounded by a box, the text will be formatted and adjusted
.PT M
.B marked display
.N
the text will be marked by |
on the left hand side, not adjusted and not filled
.PT no
.N 1
not adjusted, not filled
.PE
These operands can be followed by:
.PS - 4
.PT I
.B indented display
.N
not adjusted, not filled
.PT Q
.B quoted display
.N
indented from both margins,
adjusted and filled
.PE
.PT .FE
.B Footnote end.
.NE 3
.PT ".FN [[w2] w1]"
.B Numbered footnote start
.N
As with .FS, but the indicator is defaulted to a number in parenthesis.
.NE 17+1
.PT ".FS [w3] w1 [w2]"
.B Footnote start.
.N
The footnote will be moved to the bottom of the page.
Operands: w1=indicator, w2=suffix and w3=prefix.
The indicator (w1) appears in the output text and
at the start of the footnote text as well to identify the footnote.
Prefix and suffix are for the special case that the indicator
has to be preceded or followed by e.g. comma, full stop etc.
The running text will contain w3w1w2.
.NE 10+1
.PT ".HC c"
.B Hyphenation character.
.N
The hyphenation control character is set to c.
It can be imbedded in words to indicate where they should be
hyphenated. If it precedes a word, this word will not be
hyphenated. The hyphenation character itself will not appear in
the output.
.PT .HY
.B Hyphenation.
.PT .IE
.B Indentation end.
.N
Return to the indentation level before the last .IS.
.NE 4+1
.PT ".IN n"
.B Set Indentation.
.N
The indentation used for paragraphs, section start etc
is set to n.
.NE 4+1
.PT .IR w...
.B Index Reference
add the words to the index list, do not
insert them in the running text.
.NE 4+1
.PT .IS [n]
.B Indentation start.
.N
Indent following text by n (default three) columns until
a .IE is encountered.
.NE 4+1
.PT .IT
.B Index Table
Produce the index table on file descriptor 2.
.NE 4+1
.PT .IW [w3] w1 [w2]
.B Index word
Insert w1, w2 and w3 in the running text as with
.B .FS
and add w1 to the index list.
.NE 4
.PT IX w...
.B Index
Insert the words in the running text and the index list.
.NE 5+1
.PT ".LL n"
.B Linelength.
.N
The line length is set to n.
The default line length is 66.
Must occur before any input text.
.NE 6+1
.PT .ME
.B Margin input end
.NE 13+1
.PT ".MS c1 c2"
.B Title input start.
.N
Operands: c1=T for T title, c1=B for bottom title,
c2=E for even pages, c2=O for odd pages.
The text between .MS and .ME will appear
as top and bottom margin text on each page.
Defaults: no top margin text, bottom margin text= ".TL \'\'-- % --\'\'".
Attention: NROFF/TROFF commands to be executed every time
(e.g. .TL \'\'-%-\'\')
a title is processed, have to be preceded by "\e!".
.PT ".N [n]"
.B New line.
.N
The new line will be preceded by n (default 0) blank lines.
.PT .NA
.B No adjust mode.
.N
The right margin will be ragged.
.NE 4+1
.PT ".NE n"
.B Need lines.
.N
If no n lines are left on the current page, a new page is begun.
.PT .NH
.B No hyphenation.
.NE 5+1
.PT ".P [n]"
.B Paragraph.
.N
The paragraph is separated from the preceding text
by n (default 1) blank lines and its first line is indented.
.PT .PE [n]
.B End list of points.
.NE 5+1
.N
The list will be followed by n (default 1) blank lines.
.NE 9+1
.PT ".PL n m"
.B Set pagelength.
.N
The first operand determines the physical length of the
page, the second one the number of lines printed per physical page.
The default value for n is 66, for m 59.
Must occur before any input text.
.PT ".PN n c"
.B Page number.
.N
The firts operand specifies the number of the next printed page.
The second operand specifies the format of the page number when printed.
(see .PS, but only a,A,i,I and 1).
.PT ".PO [n] "
.B Set page offset.
.N
The left margin is moved n columns to the
right.
.NE 12+1
.PT ".PS [c [n]] [[w2] w1]"
.B List of points start.
.N
Operands:
c=numbering style, n=indentation of points (default=3).
If c=- or empty, points are labeled with "-", if c=1
numbering of points will be arabic, if c=a with small letters,
if c=A with capital letters, if c=i with small roman numbers, if c=I
with capital roman numbers.
w1 is a suffix that will follow each point, w2 is a point prefix.
.NE 4+1
.PT ".PT w... "
.B Point.
.N
The operands w...  replace the label chosen by .PS
for this point only.
.NE 4+1
.NE 2
.PT .RE
.B Reference entry end
.N
To close the text of the reference entry started by .RF or .RS.
.NE 12+1
.PT ".RF [w3] w1 [w2]"
.B Reference.
.N
Operands: w1=reference abbreviation,
w2=suffix, w3=prefix.(see .FS)
The reference abbreviation is embedded in square brackets
and inserted to the output text and to the start of the reference
entry as well for identification purposes.
References are collected to be put out
with .RT.
.PT .RP
.B Report layout.
.NE 4+1
.PT ".RS w"
.B Reference start.
.N
Same as .RF, but the reference w will not appear in the running output
text.
.NE 7+1
.PT .RT
.B Give bibliography.
.N
Via .RF and .RS collected bibliography is put out and then deleted.
.PT ".S1 w..."
.B Section.
.N
t is the section title, also saved for the table of contents.
Sections and subsections (see below) are numbered automatically.
.NE 5+1
.PT ".S2 w..."
.B Subsection.
.N
The title will be saved for the table of contents, as for
the following commands .S3 and .S4
.PT ".S3 w..."
.B Subsubsection.
.PT ".S4 w..."
.B Subsubsubsection.
.NE 6+1
.PT ".SN n n n n n"
.B Section numbers.
.N
The first, second, third and fourth operands
set the start values for section numbers, subsection numbers and so on.
The last operands sets the start value for the appendix number.
.NE 4+1
.PT ".ta n..."
.B Set tabulator.
.N
The tabulator stops are set to the positions n...
given in the operand list.
Usage conflicts with use of
.B tbl.
.NE 4+1
.PT ".TL x"
.B Title.
.N
To define a three part title; x is of the
form \'left\'center\'right\'.
.PT ".U w..."
.B Underline.
.N
The words given as operands w... are underlined.
.PT .UE
.B Underlining end.
.PT .UN
.B Undent temporarily.
.PT ".US [c]"
.B "Underlining start"
.N
All following text up to .UE is underlined.
Operand: c=C then the input text is non-filled and continuously underlined,
normaly only letters and digits are underlined.
.PE
.AP Bibliography
.N 2
.RT
.PN 1 A
.MS T E
\!.TL ```PUBMAC user's guide`
.ME
.MS T O
\!.TL `PUBMAC user's guide```
.ME
.BP
.N 0.5
.CS
Table of Contents
.CE
.N 1.5
.CT