2284 lines
51 KiB
Text
2284 lines
51 KiB
Text
." $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
|
|
\"ation 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
|
|
\¢ered
|
|
\&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
|