path: root/share/doc/usd/17.msmacros/ms

.\"	$OpenBSD: ms,v 1.3 2004/04/09 11:05:50 jmc Exp $
.\"
.\" Copyright (C) Caldera International Inc.  2001-2002.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code and documentation must retain the above
.\"    copyright notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed or owned by Caldera
.\"	International, Inc.
.\" 4. Neither the name of Caldera International, Inc. nor the names of other
.\"    contributors may be used to endorse or promote products derived from
.\"    this software without specific prior written permission.
.\"
.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT,
.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.\"	@(#)ms	8.2 (Berkeley) 6/1/94
.\"
.if n \{\
.po 5n
.ll 70n
.\}
.EH 'USD:17-%''Using the \-ms Macros with Troff and Nroff'
.OH 'Using the \-ms Macros with Troff and Nroff''USD:17-%'
.\".RP
.\" ....TM 76-1274-16 39199 39199-11
.\" ....ND October 8, 1976
.nr CW 2.85i
.nr GW .3i
.TL
Typing Documents on the UNIX System:
.br
\!.br
Using the \-ms Macros with Troff and Nroff
.AU "MH 2C-572" 6377
M. E. Lesk
.AI
.\" .MH
.\" .OK
\"Text Formatting
\"Phototypesetting
.AB
This document describes a set of easy-to-use macros
for preparing documents on the UNIX system.
Documents may be produced on either the
phototypesetter or on a computer terminal,
without changing the input.
.PP
The macros provide facilities for paragraphs, sections (optionally
with automatic numbering), page titles, footnotes,
equations,
tables, two-column format, and
cover pages for papers.
.PP
This memo includes, as an appendix,
the text of the ``Guide to Preparing
Documents with \-ms''
which contains additional examples
of features of \-ms.
.PP
This manual is a revision of, and replaces,
``Typing Documents on UNIX,''
dated November 22, 1974.
.AE
.\" .CS 6 6 12 1 0 8
.bd I 3
.PP
.I
Introduction.
.R
This memorandum describes a package of commands to produce
papers
using the
.bd I
.I
troff
.R
and
.I nroff
formatting programs on the
.SM
UNIX
.NL
system.
As with other
.I roff -derived
programs,
text is prepared interspersed with formatting commands.
However, this package,
which itself is written in
.I troff
commands,
provides higher-level commands
than those provided with the basic
.I troff
program.
The commands available in this package are listed in
Appendix A.
.bd I 3
.PP
.I
Text.
.R
Type normally, except that instead of indenting for paragraphs,
place a line reading ``.PP'' before each paragraph.
This will produce indenting and extra space.
.LP
Alternatively, the command .LP that was used here will produce
a left-aligned (block) paragraph.
The paragraph spacing can be changed: see below under ``Registers.''
.PP
.I
Beginning.
.R
For a document with a paper-type cover sheet, the input should start as follows:
.DS L
	[optional overall format .RP \- see below]
	.TL
	Title of document (one or more lines)
	.AU
	Author(s) (may also be several lines)
	.AI
	Author's institution(s)
	.AB
	Abstract; to be placed on the cover sheet of a paper.
	Line length is 5/6 of normal; use .ll here to change.
	.AE  (abstract end)
	text ... (begins with .PP, which see)
.DE
To omit some of the standard headings
(e.g. no abstract, or no author's institution) just
omit the corresponding fields and command lines.
The word
.SM
ABSTRACT
.NL
can be suppressed by writing ``.AB no'' for ``.AB''.
Several interspersed .AU and .AI lines can be used for multiple authors.
The headings are not compulsory: beginning
with a .PP command is perfectly OK and will just
start printing an ordinary paragraph.
.I Warning:
You can't just begin a document with a line of text.
Some \-ms command must
precede any text input.  When in doubt, use .LP
to get proper initialization, although any of
the commands .PP, .LP, .TL, .SH, .NH is good enough.
Figure 1 shows the legal arrangement of commands at the
start of a document.
.PP
.I
Cover Sheets and First Pages.
.R
The first line
of a document signals the general format of the first page.
In particular, if it is ".RP" a cover sheet with title and
abstract is prepared.
The default format
is useful for scanning drafts.
.PP
In general \-ms is arranged so that only one form
of a document need be stored, containing all
information;  the first command gives the format,
and unnecessary items for that format are ignored.
.PP
Warning: don't put extraneous material
between the .TL and .AE commands.  Processing
of the titling items is
special, and other data placed in them may not behave
as you expect.
Don't forget that some \-ms command must precede any input text.
.PP
.I
Page headings.
.R
The \-ms macros, by default, will print a page heading containing
a page number (if greater than 1).
A default page footer is provided only in
.I nroff ,
where the date is used.
The user can make minor adjustments to the page headings/footings
by redefining the
strings
LH, CH, and RH
which are the left, center and right portions of the page headings,
respectively; and the
strings
LF, CF, and RF,
which are the left, center and right portions of the page footer.
For more complex formats, the user can redefine
the macros PT and BT, which are invoked respectively at the top
and bottom of each page.
The margins (taken from registers HM and FM for the top and bottom
margin respectively) are normally 1 inch; the page header/footer are
in the middle of that space.
The user who redefines these macros should be careful
not to change parameters such as point size or font
without resetting them to default values.
.PP
.I
Multi-column formats.
.R
If you place the command ``.2C'' in your document, the document will
be printed in double column format beginning
at that point.  This feature is not too useful in computer
terminal output, but is often desirable on the typesetter.
The command ``.1C'' will go
back to one-column format and also skip to a new page.
The ``.2C'' command is actually a special case of the command
.DS L
	.MC [column width [gutter width]]
.DE
which makes multiple columns with the specified column
and gutter width; as many columns as will fit across the page
are used.
Thus triple, quadruple, ... column pages can be printed.
Whenever the number of columns is changed (except going from
full width to some larger number of columns)
a new page is started.
.PP
.I
Headings.
.R
To produce a special heading, there are two commands.
If you type
.DS L
	.NH
	type section heading here
	may be several lines
.DE
you will get automatically numbered section headings (1, 2, 3, ...),
in boldface.
For example,
.DS L
    .NH
    Care and Feeding of Department Heads
.DE
produces
.NH
Care and Feeding of Department Heads
.PP
Alternatively,
.DS L
	.SH
	Care and Feeding of Directors
.DE
will print the heading with no number added:
.SH
Care and Feeding of Directors
.PP
Every section heading, of either type, should be followed
by a paragraph beginning with .PP or .LP, indicating
the end of the heading.
Headings may contain more than one line
of text.
.PP
The .NH command also supports more complex numbering schemes.
If a numerical argument is given, it is taken to be a
``level'' number and an appropriate sub-section
number is generated.
Larger level numbers indicate deeper
sub-sections, as in this example:
.DS L
	.NH
	Erie-Lackawanna
	.NH 2
	Morris and Essex Division
	.NH 3
	Gladstone Branch
	.NH 3
	Montclair Branch
	.NH 2
	Boonton Line
.DE
.ne 1i
generates:
.NH
Erie-Lackawanna
.NH 2
Morris and Essex Division
.NH 3
Gladstone Branch
.NH 3
Montclair Branch
.NH 2
Boonton Line
.PP
An explicit ``.NH 0'' will reset the numbering of level 1
to one, as here:
.DS L
	.NH 0
	Penn Central
.DE
.ft 3
.if n .ul 1
.sp 1
1.  Penn Central
.PP
.I
Indented paragraphs.
.R
(Paragraphs with hanging numbers, e.g. references.)
The sequence
.DS L
	.IP [1]
	Text for first paragraph, typed
	normally for as long as you would
	like on as many lines as needed.
	.IP [2]
	Text for second paragraph, ...
.DE
produces
.IP [1]
Text for first paragraph, typed normally for as long
as you would like on as many lines as
needed.
.IP [2]
Text for second paragraph, ...
.LP
A series of indented paragraphs may be followed by an ordinary paragraph
beginning with .PP or .LP,
depending on whether you wish indenting or not.
The command .LP was used here.
.PP
More sophisticated uses of .IP are also possible.
If the label is omitted, for example, a plain block indent
is produced.
.DS L
	.IP
	This material will
	just be turned into a
	block indent suitable for quotations or
	such matter.
	.LP
.DE
will produce
.IP
This material
will just be turned
into a block indent
suitable for
quotations or such matter.
.LP
If a non-standard amount of indenting is required,
it may be specified after the label (in character positions)
and will remain in effect until the next .PP or .LP.
Thus, the general form of the .IP command
contains two additional fields: the label and the indenting
length.  For example,
.DS L
	.IP first: 9
	Notice the longer label, requiring larger
	indenting for these paragraphs.
	.IP second:
	And so forth.
	.LP
.DE
produces this:
.IP first: 9
Notice the longer label, requiring larger
indenting for these paragraphs.
.IP second:
And so forth.
.LP
It is also possible to produce multiple nested indents;
the command .RS indicates that the next .IP starts from the
current indentation level.
Each .RE will eat up one level of indenting
so you should balance .RS and .RE commands.
The .RS command should be thought of as ``move right'' and
the .RE command as ``move left''.
As an example
.DS L
	.IP 1.
	Bell Laboratories
	.RS
	.IP 1.1
	Murray Hill
	.IP 1.2
	Holmdel
	.IP 1.3
	Whippany
	.RS
	.IP 1.3.1
	Madison
	.RE
	.IP 1.4
	Chester
	.RE
	.LP
.DE
will result in
.IP 1.
Bell Laboratories
.RS
.IP 1.1
Murray Hill
.IP 1.2
Holmdel
.IP 1.3
Whippany
.RS
.IP 1.3.1
Madison
.RE
.IP 1.4
Chester
.RE
.LP
All of these variations on .LP leave the right
margin untouched.  Sometimes, for purposes
such as setting off a quotation, a paragraph indented
on both right and left is required.
.QP
A single paragraph
like this is obtained
by preceding it with .QP.
More complicated material (several paragraphs) should be
bracketed with .QS and .QE.
.LP
.I
Emphasis.
.R
To get
italics
(on the typesetter) or underlining (on the terminal)
say
.DS L
	.I
	as much text as you want
	can be typed here
	.R
.DE
.bd I
.br
as was done for
.I
these three words.
.R
The .R command restores the normal (usually Roman) font.
If only one word is to be italicized, it
may be just given on the line with the .I command,
.br
.bd I 3
.DS
	.I word
.DE
and in this case no .R is needed to restore
the previous font.
.B
Boldface
.R
can be produced by
.DS L
	.B
	Text to be set in boldface
	goes here
	.R
.DE
and also will be underlined on the terminal or line printer.
As with .I, a single word can be placed in boldface
by placing it on the same line as the .B command.
.PP
A few size changes
can be specified similarly with
the commands .LG (make larger), .SM (make smaller), and .NL
(return to normal size).
The size change
is two points; the commands may be repeated for
.SM
increased
.SM
effect
.NL
(here one .NL canceled two .SM commands).
.PP
If actual
.UL underlining
as opposed to italicizing is required on the typesetter,
the command
.DS
	.UL word
.DE
will underline a word.  There is no way to underline
multiple words on the typesetter.
.PP
.I
Footnotes.
.R
Material placed between lines with the commands .FS
(footnote) and .FE (footnote end) will
be collected, remembered, and finally placed
at the bottom of the current page*.
By default, footnotes are 11/12th the
length of normal text,
but this can be changed using the FL register (see below).
.FS
* Like this.
.FE
.PP
.I
Displays and Tables.
.R
To prepare displays of lines, such as tables, in which
the lines should not be re-arranged,
enclose them in the commands .DS and .DE
.DS L
	.DS
	table lines, like the
	examples here, are placed
	between .DS and .DE
	.DE
.DE
By default, lines between .DS and .DE are indented and left-adjusted.
You can also center lines, or retain the left margin.
Lines bracketed by .DS C and .DE commands are
centered (and not re-arranged); lines bracketed
by .DS L and .DE are left-adjusted, not indented, and
not re-arranged.
A plain .DS is equivalent
to .DS I, which indents and left-adjusts.  Thus,
.DS C
these lines were preceded
by .DS C and followed by
a .DE command;
.DE
whereas
.DS L
these lines were preceded
by .DS L and followed by
a .DE command.
.DE
Note that .DS C centers each line; there is a variant .DS B
that makes the display into a left-adjusted block of text, and
then centers that entire block.
Normally a display is kept together, on one page.
If you wish to have a long display which
may be split across page
boundaries,
use .CD, .LD, or .ID in place of
the commands .DS C, .DS L, or .DS I respectively.
An extra argument to the .DS I or .DS command is taken
as an amount to indent.
Note: it is tempting to assume that .DS R will right adjust
lines, but it doesn't work.
.PP
.I
Boxing words or lines.
.R
To draw rectangular boxes around words the command
.DS L
	.BX word
.DE
will print
.BX word
as shown.
The boxes will not be neat on a terminal, and this
should not be used as a substitute for italics.
.B1
Longer pieces of text may be boxed
by enclosing them with .B1 and .B2:
.DS L
	.B1
	text...
	.B2
.DE
as has been done here.
.B2
.ne 1i
.PP
.I
Keeping blocks together.
.R
If you wish to keep a table or other block of lines
together on a page, there are ``keep - release'' commands.
If a block of lines preceded by .KS and followed by .KE does
not fit on the remainder of the current page, it will begin
on a new page.
Lines bracketed by .DS and .DE commands are automatically
kept together this way.
There is also a ``keep floating'' command: if the
block to be kept together is preceded by .KF instead of .KS
and does not fit
on the current page, it will be moved down through the text
until the top of the next page.  Thus, no large blank space
will be introduced in the document.  
.PP
.I
Nroff/Troff commands.
.R
Among the useful commands from the basic formatting programs
are the following.  They all work with both typesetter and
computer terminal output:
.DS L
	.bp - begin new page.
	.br - ``break'', stop running text
	          from line to line.
	.sp n - insert n blank lines.
	.na - don't adjust right margins.
.DE
.PP
.I
Date.
.R
By default, documents produced on computer terminals have the
date at the bottom of each page; documents produced on
the typesetter don't.
To force the date, say ``.DA''.  To force no date, say ``.ND''.
To lie about the date, say ``.DA July 4, 1776''
which puts the specified date at the bottom of each page.
The command
.DS L
	.ND May 8, 1945
.DE
in ".RP" format
places the specified date on the cover sheet and nowhere else.
Place this line before the title.
.PP
.I
Registers.
.R
Certain of the registers used by \-ms can
be altered to change default
settings.
They should be changed with .nr commands,
as with
.DS
	.nr PS 9
.DE
.bd I
to make the default point size 9 point.
If the effect is needed immediately, the
normal
.I
troff
.R
command should be used
in addition to changing the number register.
.br
.ps 9
.vs 10p
.TS
c0 c c c
c c c c
a l l l.
Register	Defines	Takes	Default
		effect
PO	page offset	next page	1\(fm\(fm
LL	line length	next para.	6\(fm\(fm
LT	title length	next para.	6\(fm\(fm
HM	top margin	next page	1\(fm\(fm
FM	bottom margin	next page	1\(fm\(fm
PS	point size	next para.	10 pts
VS	line spacing	next para.	12 pts
PI	para. indent	next para.	5 ens
PD	para. spacing	next para.	0.3 VS
QI	quote para ind	next para.	5 ens
FL	footnote length	next FS	*5/6 LL
FI	footnote indent	next FS	*5/6 LL
FF	footnote format	next FS	*5/6 LL
MINGW	min. column wid	next page	2 ens
.TE
.ps \n(PS
.vs \n(VS
You may also alter
the strings
LH, CH, and RH which are the left, center, and right headings
respectively; and similarly LF, CF, and RF which are strings in the
page footer.
The page number on
.I
output
.R
is taken from register PN, to permit
changing its output style.
For more complicated headers and footers
the macros PT and BT can be redefined, as
explained earlier.
.bd I 3
.PP
.I
Accents.
.R
To simplify typing certain foreign words,
strings representing common accent marks are defined.
They precede the letter over which the mark
is to appear.
Here are the strings:
.TS
center;
c c6 c c.
Input	Output	Input	Output
\e*\(fme	\*'e	\e*~a	\*~a
\e*\(gae	\*`e	\e*Ce	\h'0.15m'\v'-0.6m'\s6\zv\s0\v'0.6m'\h'-0.15m'e
\e*:u	\*:u	\e*,c	\*,c
\e*^e	\o'^e'
.TE
.PP
.I
Use.
.R
After your document is prepared and stored on a file,
you can print it on a terminal with the command*
.bd I
.FS
* If .2C was used, pipe the
.I nroff
output
through
.I col;
make the first line of the input
``.pi /usr/bin/col.''
.br
.FE
.DS L
.I
   nroff \-ms file
.R
.DE
and you can print it on the typesetter with the
command
.DS L
.I
   troff \-ms file
.R
.DE
(many options are possible).
In each case, if your document is stored in several files,
just list all the filenames
where we have used ``file''.
If equations or tables are used,
.I
eqn
.R
and/or
.I
tbl
.R
must be invoked as preprocessors.
.br
.bd I 3
.PP
.I
References and further study.
.R
If you have to do Greek or mathematics, see
.I eqn
[1]
for equation setting.
To aid
.I eqn
users,
.I \-ms
provides definitions of .EQ and .EN
which normally center the equation and set it off slightly.
An argument on .EQ is taken to be an equation
number and placed in the right margin near the equation.
In addition, there are three special arguments to EQ:
the letters C, I, and L indicate centered (default),
indented, and left adjusted equations, respectively. 
If there is both a format argument
and an equation number,
give the format argument first, as in
.bd I
.DS
	.EQ L (1.3a)
.DE
for a left-adjusted equation numbered (1.3a).
.PP
Similarly,
the macros .TS and .TE
are defined
to separate tables (see [2]) from text with a little space.
A very long table with a heading may be broken
across pages by beginning it with .TS H
instead of .TS,
and placing the line .TH in the table data
after the heading.  If the table
has no heading repeated from page to page,
just use the ordinary .TS and .TE macros.
.PP
To learn more about
.I troff
see
[3] for a general introduction, and [4]
for the full details (experts only).
Information on related UNIX commands
is in [5].
For jobs that do not seem well-adapted
to \-ms, consider other macro packages.
It is often far easier to write a specific macro packages
for such tasks as imitating particular journals than
to try to adapt \-ms.
.PP
.bd I 3
.I
Acknowledgment.
.R
Many thanks are due to Brian Kernighan for
his help in the design and implementation of this package,
and for his assistance in preparing this manual.
.bd I
.SH
.ce
References
.PP
.IP [1]
B. W. Kernighan and L. L. Cherry,
.I
Typesetting Mathematics \(em Users Guide (2nd edition),
.R
Bell Laboratories Computing Science Report no. 17.
.IP [2]
M. E. Lesk,
.I
Tbl \(em A Program to Format Tables,
.R
Bell Laboratories Computing Science Report no. 45.
.IP [3]
B. W. Kernighan,
.I
A Troff Tutorial,
.R
Bell Laboratories, 1976.
.IP [4]
J. F. Ossanna,
.I
Nroff\|/Troff Reference Manual,
.R
Bell Laboratories Computing Science Report no. 51.
.IP [5]
K. Thompson and D. M. Ritchie,
.I
UNIX Programmer's Manual,
.R
Bell Laboratories, 1978.
.1C
.SH
.ce
Appendix A
.ce
List of Commands
.ft R
.TS
expand;
l2 l5 l2 l.
1C	Return to single column format.	LG	Increase type size.
2C	Start double column format.	LP	Left aligned block paragraph.
AB	Begin abstract.	
AE	End abstract.	
AI	Specify author's institution.	
AU	Specify author.	ND	Change or cancel date.
B	Begin boldface.	NH	Specify numbered heading.
DA	Provide the date on each page.	NL	Return to normal type size.
DE	End display.	PP	Begin paragraph.
DS	Start display (also CD, LD, ID).	
EN	End equation.	R	Return to regular font (usually Roman).
EQ	Begin equation.	RE	End one level of relative indenting.
FE	End footnote.	RP	Use released paper format.
FS	Begin footnote.	RS	Relative indent increased one level.
I	Begin italics.	SH	Specify section heading.
		SM	Change to smaller type size.
IP	Begin indented paragraph.	TL	Specify title.
KE	Release keep.	
KF	Begin floating keep.	UL	Underline one word.
KS	Start keep.	
.TE
.sp
.ce
.ft B
Register Names
.ft R
.PP
The following register names are used by \-ms internally.
Independent use of these names in one's own macros may
produce incorrect output.
Note that no lower case letters are used in any \-ms internal name.
.TS
 expand;
c s s  s s s  s s s  s s
l l l  l l l  l l l  l l.
Number registers used in \-ms
:	DW	GW	HM	IQ	LL	NA	OJ	PO	T.	TV
#T	EF	H1	HT	IR	LT	NC	PD	PQ	TB	VS
\&.T	FC	H2	IF	IT	MF	ND	PE	PS	TC	WF
1T	FL	H3	IK	KI	MM	NF	PF	PX	TD	YE
AV	FM	H4	IM	L1	MN	NS	PI	RO	TN	YY
CW	FP	H5	IP	LE	MO	OI	PN	ST	TQ	ZN
.TE
.sp
.TS
expand;
c s s  s s s  s s s  s s
l l l  l l l  l l l  l l.
String registers used in \-ms
\(fm	A5	CB	DW	EZ	I	KF	MR	R1	RT	TL
\(ga	AB	CC	DY	FA	I1	KQ	ND	R2	S0	TM
^	AE	CD	E1	FE	I2	KS	NH	R3	S1	TQ
~	AI	CF	E2	FJ	I3	LB	NL	R4	S2	TS
:	AU	CH	E3	FK	I4	LD	NP	R5	SG	TT
,	B	CM	E4	FN	I5	LG	OD	RC	SH	UL
1C	BG	CS	E5	FO	ID	LP	OK	RE	SM	WB
2C	BT	CT	EE	FQ	IE	ME	PP	RF	SN	WH
A1	C	D	EL	FS	IM	MF	PT	RH	SY	WT
A2	C1	DA	EM	FV	IP	MH	PY	RP	TA	XD
A3	C2	DE	EN	FY	IZ	MN	QF	RQ	TE	XF
A4	CA	DS	EQ	HO	KE	MO	R	RS	TH	XK
.TE
.\" .(z
.\".so fig1.pic
.ce 2
Figure 1:\ \ Order of Commands in Input
.ce 0
.\" .)z