path: root/doc/ms.ms

.\" This file is part of groff.
.\"
.\" groff is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" groff is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
.
.\" Handle font requests with families, for instance in tbl(1) tables.
.if n \{\
.  ftr CR B \" for a visible distinction from roman
.  ftr CB B
.  ftr CI I
.  ftr CBI BI
.  \" Redefine CW to use bold instead for a visible font change.
.  als CW B
.  \" The "document control settings" table imposes this minimum width.
.  nr LL 87n
.\}
.\" This document doesn't require the minus sign (in Times) but we do
.\" want a copy- and-pastable hyphen-minus.
.ie '\*[.T]'cp1047' .char \- \N'96'
.el                 .char \- \N'45'
.\" A very limited output device might not have a dagger glyph.
.fchar \[dg] *
.nr PS 11
.nr VS 13
.ds FR 1
.nr TC-MARGIN \w'00' \" expect 2-digit page numbers at most
.ie t .nr PI 3.5n
.el   .nr PI 4n
.ND May 2023
.EH '%''May 2023'
.EF ''''
.OH 'Using \f[I]groff\f[] with the \f[I]ms\f[] macros''%'
.OF ''''
.TL
Using
.BI groff
with the
.BI ms
Macro Package
.AU
Larry Kollar
.AI
kollar@alltel.net
.AU
G.\& Branden Robinson
.AI
g.branden.robinson@gmail.com
.AB no
The
.I ms
(\[lq]manuscript\[rq]) package is suitable for the composition of
letters,
memoranda,
reports,
and books.
.
These
.I groff
macros feature cover page and table of contents generation,
automatically numbered headings,
several paragraph styles,
a variety of text styling options,
footnotes,
and multi-column page layouts.
.
.I ms
supports the
.I tbl ,
.I eqn ,
.I pic ,
and
.I refer
preprocessors for inclusion of tables,
mathematical equations,
diagrams,
and standardized bibliographic citations.
.
This implementation is mostly compatible with the documented interface
and behavior of AT&T Unix Version\~7
.I ms .
.
Many extensions from 4.2BSD (Berkeley)
.\" Few changes were made in 4.3, Tahoe, Reno, or 4.4.
and Tenth Edition Research Unix have been recreated.
.AE
.
.
.\" ------------------------- End of cover page ------------------------
.NH 1
Introduction
.XS
Introduction
.XE
.
.
.LP
The
.I ms
macros are the oldest surviving package for
.I roff
systems.\**
.
.FS
While manual
.I pages
are older,
early ones used macros supplanted by the
.I man
package of Seventh Edition Unix (1979).
.
.I ms
shipped with Sixth Edition (1975) and was documented by Mike Lesk in a
Bell Labs internal memorandum.
.FE
.
While the
.I man
package was designed for brief reference documents,
the
.I ms
macros are also suitable for longer works intended for printing and
possible publication.
.
.
.PP
In this document,
a right arrow (\[->]) is used to indicate a tab character in the input.
.
.
.KS
.NH 2
Basic information
.XS
	Basic information
.XE
.
.
.LP
.I ms
documents are plain text files;
prepare them with your preferred text editor.
.
If you're in a hurry to start,
know that
.I ms
needs one of its macros called at the beginning of a document so that it
can initialize.
.
A
.I macro
is a formatting instruction to
.I ms.
.
Put a macro call on a line by itself.
.
Use
.CW .PP
if you want your paragraph's first line to be indented,
or
.CW .LP
if you don't.
.KE
.
.
.PP
After that,
start typing normally.
.
It is a good practice to start each sentence on a new line,
or to put two spaces after sentence-ending punctuation,
so that the formatter knows where the sentence boundaries are.
.
You can separate paragraphs with further paragraphing macro calls,
or with blank lines,
and you can indent with tabs.
.
When you need one of the features mentioned earlier,
return to this manual.
.
.
.PP
Format the document with the
.I groff (1)
command.
.
.I nroff (1)
can be useful for previewing.
.
.
.if n .ftr TI I
.TS
box center;
Lf(CR)1 Lf(CB).
$	editor radical.ms \f[TI]# vim, emacs, .\|.\|.
$	nroff -ww -z -ms radical.ms \f[TI]# check for errors
$	nroff \-ms radical.ms | less \-R
$	groff \-T pdf \-ms radical.ms > radical.pdf
$	see radical.pdf \f[TI]# or your favorite PDF viewer
.TE
.if n .ftr TI
.
.
.PP
Our
.CW radical.ms
document might look like this.
.
.
.TS
box center;
Lf(CR).
\&.LP
Radical novelties are so disturbing that they tend to be
suppressed or ignored, to the extent that even the
possibility of their existence in general is more often
denied than admitted.
.sp
\[->]That\[aq]s what Dijkstra said, anyway.
.TE
.
.
.LP
.I ms
exposes many aspects of document layout to user control via
.I groff 's
.I registers
and
.I strings,
which store numbers and text,
respectively.
.
Measurements in
.I groff
are expressed with a suffix called a
.I "scaling unit."
.
.
.TS
box center;
cb cb
cf(CR) l .
Scaling unit	Description
_
i	inches (\[sd])
c	centimeters
p	points (1/72\[sd])
P	picas (1/6\[sd])
v	\[lq]vees\[rq]; current vertical spacing
m	\[lq]ems\[rq]; width of an \[lq]M\[rq] in the current font
n	\[lq]ens\[rq]; one-half em
.TE
.
.
.PP
Set registers with the
.CW nr
request
and strings with the
.CW ds
request.
.
.I Requests
are like macro calls;
they go on lines by themselves and start with the
.I "control character,"
a dot
.CW . ). (
.
The difference is that they directly instruct the formatter program,
rather than the macro package.
.
We'll discuss a few as applicable.
.
It is wise to specify a scaling unit when setting any register that
represents a length,
size,
or distance.
.
.
.TS
box center;
lf(CR).
\&.nr PS 10.5p \[rs]" Use 10.5\-point type.
\&.ds FAM P    \[rs]" Use Palatino font family.
.TE
.
.
.LP
In the foregoing,
we see that
.CW \[rs]"
begins a comment.
.
This is an example of an
.I "escape sequence,"
the other kind of formatting instruction.
.
Escape sequences can appear anywhere.
.
They begin with the escape character
.CW \[rs] ) (
and are followed by at least one more character.
.
.I ms
documents like this one tend to use only a few of
.I groff 's
many requests and escape sequences;
see the
.I groff (7)
man page for complete lists.
.
.
.TS
box center;
Cb Cb
Lf(CR) Lx .
Escape sequence	Description
_
\[rs]"	Begin comment; ignore remainder of line.
\[rs]n[\f[I]reg\f[]]	T{
Interpolate value of register
.I reg .
T}
\[rs]*[\f[I]str\f[]]	T{
Interpolate contents of string
.I str .
T}
\[rs]*\f[I]s	T{
abbreviation of
.CW \[rs]*[\f[I]s\f[]] ;
the name
.I s
must be only one character
T}
\[rs][\f[I]char\f[]]	T{
Interpolate glyph of special character named
.I char .
T}
\[rs]&	non-printing, zero-width dummy character
\[rs]\[ti]	T{
Insert an unbreakable space of adjustable width like a normal space.
T}
\[rs]|	T{
Move horizontally by one-sixth em
(\[lq]thin space\[rq]).
T}
.TE
.
.
.PP
Prefix any words that start with a dot
.CW .\& ) (
or neutral apostrophe
.CW \[aq] ) (
with
.CW \[rs]&
if they are at the beginning of an input line
(or might become that way in editing)
to prevent them from being interpreted as macro calls or requests.
.
Suffix
.CW . ,
.CW ? ,
and
.CW !\&
with
.CW \[rs]&
when needed to cancel end-of-sentence detection.
.
.
.TS
box center;
lf(CR).
My exposure was \[rs]&.5 to \[rs]&.6 Sv of neutrons, said Dr.\[rs]&
Wallace after the criticality incident.
.TE
.
.
.\" ------------------------
.if t \{\
.  br
.  bp
.\}
.NH 1
General structure of an
.BI ms
document
.XS
General structure of an
.I ms
document
.XE
.
.
.LP
The
.I ms
macro package expects a certain amount of structure:
a well-formed document contains at least one paragraphing or heading
macro call.
.
Longer documents have a structure as follows.
.
.
.IP "\fBDocument type\fP"
Calling the
.CW RP
macro at the beginning of your document puts the document description
(see below)
on a cover page.
.
Otherwise,
.I ms
places this information
(if any)
on the first page,
followed immediately by the body text.
.
Some document types found in other
.I ms
implementations are specific to AT&T or Berkeley,
and are not supported by
.I "groff ms" .
.
.
.IP "\fBFormat and layout\fP"
By setting registers and strings,
you can configure your document's typeface,
margins,
spacing,
headers and footers,
and footnote arrangement.
.
See section \[lq]Document control settings\[rq] below.
.
.
.IP "\fBDocument description\fP"
A document description consists of any of:
a title,
one or more authors' names and affiliated institutions,
an abstract,
and a date or other identifier.
.
See section \[lq]Document description macros\[rq] below.
.
.
.IP "\fBBody text\fP"
The main matter of your document follows its description
(if any).
.
.I ms
supports highly structured text consisting of paragraphs interspersed
with multi-level headings
(chapters,
sections,
subsections,
and so forth)
and augmented by lists,
footnotes,
tables,
diagrams,
and similar material.
.
See section \[lq]Body text\[rq] below.
.
.
.IP "\fBTables of contents\fP"
Macros enable the collection of entries for a table of contents
(or index)
as the material they discuss appears in the document.
.
You then call a macro to emit the table of contents at the end of
your document.
.
The table of contents must necessarily follow the rest of the text since
GNU
.I troff
is a single-pass formatter;
it thus cannot determine the page number of a division of the text until
it has been set and output.
.
Since
.I ms
output was designed for the production of hard copy,
the traditional procedure was to manually relocate the pages containing
the table of contents between the cover page and the body text.
.
Today,
page resequencing is more often done in the digital domain.
.
An index works similarly,
but because it typically needs to be sorted after collection,
its preparation requires separate processing.
.
.
.\" ------------------------
.if t \{\
.  br
.  bp
.\}
.NH 1
Document control settings
.XS
Document control settings
.XE
.
.
.LP
The document parameters below are presented in the syntax
used to interpolate their values.
.
For any unsatisfactory default,
define its register,
string,
or special character before calling any
.I ms
macro other than
.CW RP .
.
The \[lq]Next\[rq] heading indicates that changes to the parameter are
effective as of the next new element processed of the listed type.
.
For entries marked
.I special ,
see the discussion in the applicable section.
.
.
.TS H
box;
cb | cb cb cb cb
l | lf(CR)p-1 lx l lf(CR)p-1.
Type	Parameter	Definition	Next	Default
_
.TH
Margins	\[rs]n[PO]	Page offset (left margin)	page\
	1i (0)\*{*\*}
\^	\[rs]n[LL]	Line length	paragraph	\
6.5i (65n)\*{*\*}
\^	\[rs]n[LT]	Title line length	paragraph	\
6.5i (65n)\*{*\*}
\^	\[rs]n[HM]	Top (header) margin	page	1i
\^	\[rs]n[FM]	Bottom (footer) margin	page	1i
_
T{
Titles
.br
(headers,
.br
footers)
T}	\[rs]*[LH]	Left header text	header	\f[I]empty
\^	\[rs]*[CH]	Center header text	header	\-\[rs]n[%]\-
\^	\[rs]*[RH]	Right header text	header	\f[I]empty
\^	\[rs]*[LF]	Left footer text	footer	\f[I]empty
\^	\[rs]*[CF]	Center footer text	footer	\f[I]empty
\^	\[rs]*[RF]	Right footer text	footer	\f[I]empty
_
Text	\[rs]n[PS]	Type (point) size	paragraph	10p
\^	\[rs]n[VS]	Vertical spacing	paragraph	12p
\^	\[rs]n[HY]	Hyphenation mode	paragraph	6
\^	\[rs]*[FAM]	Font family	paragraph	T
_
Paragraphs	\[rs]n[PI]	Indentation	paragraph	5n
\^	\[rs]n[PD]	Paragraph distance (spacing)	paragraph\
	0.3v \f[R](\f[]1v\f[R])\*{\[dg]\*}
\^	\[rs]n[QI]	Quotation indentation	paragraph	5n
\^	\[rs]n[PORPHANS]	# of initial lines kept	paragraph\
	1
_
Headings	\[rs]n[PSINCR]	Type (point) size increment\
	heading	1p
\^	\[rs]n[GROWPS]	Size increase depth limit	heading	0
\^	\[rs]n[HORPHANS]	# of following lines kept\
	heading	1
\^	\[rs]*[SN\-STYLE]	Numbering style (alias)	heading\
	\[rs]*[SN\-DOT]
_
Footnotes	\[rs]n[FI]	Indentation	footnote	2n
\^	\[rs]n[FF]	Format	footnote	0
\^	\[rs]n[FPS]	Type (point) size	footnote\
	\[rs]n[PS]\-2p
\^	\[rs]n[FVS]	Vertical spacing	footnote\
	\[rs]n[FPS]+2p
\^	\[rs]n[FPD]	Paragraph distance (spacing)	footnote\
	\[rs]n[PD]/2
\^	\[rs]*[FR]	Line length ratio	\f[I]special	11/12
_
Displays	\[rs]n[DD]	Display distance (spacing)\
	\f[I]special	0.5v \f[R](\f[]1v\f[R])\*{\[dg]\*}
\^	\[rs]n[DI]	Display indentation	\f[I]special	0.5i
_
Other	\[rs]n[MINGW]	Minimum gutter width	page	2n
\^	\[rs]n[TC\-MARGIN]	TOC page number margin width\
	\f[CR]PX\f[] call	\[rs]w\[aq]000\[aq]
\^	\[rs][TC\-LEADER]	TOC leader character\
	\f[CR]PX\f[] call	.\[rs]h\[aq]1m\[aq]
.TE
.
.
.IP \*{*\*}
Defaults vary by output device and paper format;
the values shown are for typesetters using U.S.\& letter paper,
and then terminals.
.
See section \[lq]Paper format\[rq] of the
.I groff (1)
man page.
.
.
.IP \*{\[dg]\*}
The
.CW PD
and
.CW DD
registers use the larger value if the vertical motion quantum of the
output device is too coarse for the smaller one;
usually,
this is the case only for output to terminals and emulators thereof.
.
.
.\" ------------------------
.if t \{\
.  br
.  bp
.\}
.NH 1
Document description macros
.XS
Document description macros
.XE
.
.
.LP
Only the simplest document lacks a title.\**
.
.FS
Distinguish a document title from \[lq]titles\[rq],
which are what
.I roff
systems call headers and footers collectively.
.FE
.
As its level of sophistication
(or complexity)
increases,
it tends to acquire a date of revision,
explicitly identified authors,
sponsoring institutions for authors,
and,
at the rarefied heights,
an abstract of its content.
.
By default,
.I ms
arranges most of the document description
(the title,
author names and institutions,
and abstract,
but not the date)
at the top of the first page.
.
.
.PP
Define these data by calling the macros below in the order shown;
.CW .DA
or
.CW .ND
can be called to set the document date
(or other identifier)
at any time before (a) the abstract,
if present,
or (b) its information is required in a header or footer.
.
Use of these macros is optional,
except that
.CW .TL
is mandatory if any of
.CW .RP ,
.CW .AU ,
.CW .AI ,
or
.CW .AB
is called,
and
.CW .AE
is mandatory if
.CW .AB
is called.
.
.
.TS H
box;
lb lb
lf(CR) lx.
Macro	Description
_
.TH
\&.RP \f[R][\f[I]option\f[] .\|.\|.]	T{
Use the \[lq]report\[rq]
(AT&T: \[lq]released paper\[rq])
format for your document,
creating a separate cover page.
.
If the optional
.CW no\-\:\%repeat\-\:\%info
argument is given,
.I ms
produces a cover page but does not repeat any of its information
subsequently
(but see the
.CW DA
macro below regarding the date).
.
Normally,
.CW .RP
sets the page number following the cover page to\~1.
.
Specifying the optional
.CW no\-\:\%renumber
argument suppresses this alteration.
.
Optional arguments can occur in any order.
.
.CW no
is recognized as a synonym of
.CW no\-\:\%repeat\-\:\%info
for AT&T compatibility.
T}
_
\&.TL	T{
Specify the document title.
.
.I ms
collects text on input lines following this call into the title
until reaching
.CW .AU ,
.CW .AB ,
or a heading or paragraphing macro call.
T}
_
\&.AU	T{
Specify an author's name.
.
.I ms
collects text on input lines following this call into the author's name
until reaching
.CW .AI ,
.CW .AB ,
another
.CW .AU ,
or a heading or paragraphing macro call.
.
Call it repeatedly to specify multiple authors.
T}
_
\&.AI	T{
Specify the preceding author's institution.
.
An
.CW .AU
call is usefully followed by at most one
.CW .AI
call;
if there are more,
the last
.CW .AI
call controls.
.
.I ms
collects text on input lines following this call into the author's
institution until reaching
.CW .AU ,
.CW .AB ,
or a heading or paragraphing macro call.
T}
_
\&.DA \f[R][\f[I]x\f[] .\|.\|.\&]	T{
Typeset the current date,
or any
.I x , arguments\~
in the center footer,
and,
if
.CW .RP
is also called,
left-aligned at the end of the document description on the cover page.
T}
_
\&.ND \f[R][\f[I]x\f[] .\|.\|.\&]	T{
Typeset the current date,
or any
.I x , arguments\~
if
.CW .RP
is also called,
left-aligned at the end of the document description on the cover page.
.
This is
.I "groff ms" 's
default.
T}
_
\&.AB \f[R][\f[]no\f[R]]	T{
Begin the abstract.
.
.I ms
collects text on input lines following this call into the abstract
until reaching an
.CW .AE
call.
.
By default,
.I ms
places the word \[lq]ABSTRACT\[rq] centered and in italics above the
text of the abstract.
.
The optional argument
.CW no
suppresses this heading.
T}
_
\&.AE	End the abstract.
.TE
.
.
.KS
.LP
An example document description,
using a cover page,
follows.
.
.
.\" Wrap lines in the code example below at 64 columns.
.TS
box center;
l.
T{
.nf
.CW
\&.RP
\&.TL
The Inevitability of Code Bloat in Commercial and Free Software
\&.AU
J.\[rs]& Random Luser
\&.AI
University of West Bumblefuzz
\&.AB
This report examines the long-term growth of the code bases in
two large,
popular software packages;
the free Emacs and the commercial Microsoft Word.
While differences appear in the type or order of features added,
due to the different methodologies used,
the results are the same in the end.
\&.PP
The free software approach is shown to be superior in that while
free software can become as bloated as commercial offerings,
free software tends to have fewer serious bugs and the added
features are more in line with user demand.
\&.AE
.R
\&.\|.\|.\|the rest of the paper\|.\|.\|.
.fi
T}
.TE
.KE
.
.
.\" ------------------------
.if t \{\
.  br
.  bp
.\}
.NH 1
Body text
.XS
Body text
.XE
.
.
.LP
A variety of macros,
registers,
and strings can be used to structure and style the body of your
document.
.
They organize your text into
paragraphs,
headings,
footnotes,
and inclusions of material such as tables and figures.
.
.
.KS
.NH 2
Text settings
.XS
	Text settings
.XE
.
.
.LP
The
.CW FAM
string,
a GNU extension,
sets the font family for body text;
the default is
.CW T \[rq]. \[lq]
.
The
.CW PS
and
.CW VS
registers set the type size and vertical spacing
(distance between text baselines),
respectively.
.
The font family and type size are ignored on terminal devices.
.
Setting these parameters before the first call of a heading,
paragraphing,
or (non-date) document description macro also applies them to headers,
footers,
and
(for
.CW FAM )
footnotes.
.
.
.PP
Which font families are available depends on the output device;
as a convention,
.CW T
selects a serif family (\[lq]Times\[rq]),
.CW H
a sans-serif family (\[lq]Helvetica\[rq]),
and
.CW C
a monospaced family (\[lq]Courier\[rq]).
.
The man page for the output driver documents its font repertoire.
.
Consult the
.I groff (1)
man page for lists of available output devices and their drivers.
.
.
.PP
The
.CW HY
register defines the automatic hyphenation mode used with the
.CW hy
request.
.
Setting
.CW \[rs]n[HY]
.CW 0 "" to\~
is equivalent to using the
.CW nh
request.
.
This is a Tenth Edition Research Unix extension.
.KE
.
.
.KS
.NH 2
Typographical symbols
.XS
	Typographical symbols
.XE
.
.
.LP
.I ms
provides a few strings to obtain typographical symbols not easily
entered with the keyboard.
.
These and many others are available as special character escape
sequences\*[-]see
the
.I groff_char (7)
man page.
.
.TS
box center;
cb lb
Lf(CR) Lx.
String	Description
_
\[rs]*[\-]	Interpolate an em dash.
_
\[rs]*[Q]	T{
Interpolate typographer's quotation marks where available,
and neutral double quotes otherwise.
.
.CW \[rs]*[Q]
is the left quote and
.CW \[rs]*[U]
the right.
T}
\[rs]*[U]	\^
.TE
.KE
.
.
.KS
.NH 2
Paragraphs
.XS
	Paragraphs
.XE
.
.
.LP
Paragraphing macros
.I break ,
or terminate,
any pending output line so that a new paragraph can begin.
.
Several paragraph types are available,
differing in how indentation
applies to them:
to left,
right,
or both margins;
to the first output line of the paragraph,
all output lines,
or all but the first.
.
All paragraphing macro calls cause the insertion of vertical space in
the amount stored in the
.CW PD
register,
except at page or column breaks.
.
Alternatively,
a blank input line breaks the output line and vertically spaces by one
vee.
.KE
.
.
.PP
The
.CW PORPHANS
register defines the minimum number of initial lines of any paragraph
that must be kept together to avoid isolated lines at the bottom of a
page.
.
If a new paragraph is started close to the bottom of a page,
and there is insufficient space to accommodate
.CW \[rs]n[PORPHANS]
lines before an automatic page break,
then a page break is forced before the start of the paragraph.
.
This is a GNU extension.
.
.
.TS H
box;
lb lb
lf(CR) lx.
Macro	Description
_
.TH
\&.LP	Set a paragraph without any (additional) indentation.
_
\&.PP	T{
Set a paragraph with a first-line left indentation of
.CW \[rs]n[PI] .
T}
_
\&.IP \f[R][\f[I]marker\f[] [\f[I]width\f[]]]	T{
Set a paragraph with a left indentation.
.
The optional
.I marker
is not indented and is empty by default.
.
It has several applications;
see subsection \[lq]Lists\[rq] below.
.
.I width
overrides the indentation amount in
.CW \[rs]n[PI] ;
its default unit is
.CW n \[rq]. \[lq]
.
Once specified,
.I width
applies to further
.CW .IP
calls until specified again or a heading or different paragraphing macro
is called.
T}
_
\&.QP	T{
Set a paragraph indented from both left and right margins by
.CW \[rs]n[QI] .
T}
_
T{
\&.QS
.br
\&.QE
T}	T{
Begin
.CW QS ) (
and end
.CW QE ) (
a region where each paragraph is indented from both margins by
.CW \[rs]n[QI] .
.
The text between
.CW .QS
and
.CW .QE
can be structured further by use of other paragraphing macros.
T}
_
\&.XP	T{
Set an \[lq]exdented\[rq] paragraph\[em]one with a left indentation of
.CW \[rs]n[PI]
on every line
.I except
the first
(also known as a hanging indent).
.
This is a Berkeley extension.
T}
.TE
.
.
.KS
.PP
The following example illustrates the use of paragraphing macros.
.
.
.TS
box center;
l.
T{
.nf
.CW
\&.NH 2
Cases used in the 2001 study
\&.LP
Two software releases were considered for this report.
\&.PP
The first is commercial software;
the second is free.
\&.IP \[rs][bu]
Microsoft Word for Windows,
starting with version 1.0 through the current version
(Word 2000).
\&.IP \[rs][bu]
GNU Emacs,
from its first appearance as a standalone editor through the
current version (v20).
See [Bloggs 2002] for details.
\&.QP
Franklin\[aq]s Law applied to software:
software expands to outgrow both RAM and disk space over time.
\&.SH
Bibliography
\&.XP
Bloggs, Joseph R.,
\&.I "Everyone\[aq]s a Critic" ,
Underground Press, March 2002.
A definitive work that answers all questions and criticisms
about the quality and usability of free software.
.R
.fi
T}
.TE
.KE
.
.
.KS
.NH 2
Headings
.XS
	Headings
.XE
.
.
.LP
Use headings to create a hierarchical structure for your document.
.
The
.I ms
macros print headings in
.B bold
using the same font family and,
by default,
type size as the body text.
.
Headings are available with and without automatic numbering.
.
Text on input lines following the macro call becomes the heading's
title.
.
Call a paragraphing macro to end the heading text and start the
section's content.
.
.
.TS
box;
cb cb
lf(CR) lx .
Macro	Description
_
\&.NH [\f[I]depth\f[]]	T{
Set an automatically numbered heading.
.
.I ms
produces a numbered heading in the form
.CW
.I a .\c
.I b .\c
.R
.I c .\|.\|.,
to any level desired,
with the numbering of each depth increasing automatically and being
reset to zero when a more significant depth increases.
.
\[lq]1\[rq]\~is the most significant or coarsest division of the
document.
.
Only non-zero values are output.
.
If
.I depth
is omitted,
it is taken to be
.CW 1 .
.
If you specify
.I depth
such that an ascending gap occurs relative to the previous
.CW NH
call\[em]that is,
you \[lq]skip a depth\[rq],
as by
.CW ".NH\~1" \[rq] \[lq]
and then
.CW ".NH\~3" \[rq]\c \[lq]
.I "groff ms" "" \[em]
emits a warning on the standard error stream.
T}
\&.NH S \f[I]heading-depth-index\f[]\f[R] .\|.\|.\f[]	T{
Alternatively,
you can give
.CW NH
a first argument
.CW S , of\~
followed by integers to number the heading depths explicitly.
.
Further automatic numbering,
if used,
resumes using the specified indices as their predecessors.
.
.\" Although undocumented in Tuthill's 4.2BSD ms.diffs paper...
This feature is a Berkeley extension.
T}
.TE
.KE
.
.
.PP
An example may be illustrative.
.
.
.TS
box center;
cb | cb
lf(CR) | lB.
Input	Result
_
T{
.nf
\&.NH 1
Animalia
\&.NH 2
Arthropoda
\&.NH 3
Crustacea
\&.NH 2
Chordata
\&.NH S 6 6 6
Daimonia
\&.NH 1
Plantae
.fi
T}	T{
.nf
1.  Animalia
.sp
1.1.  Arthropoda
.sp
1.1.1.  Crustacea
.sp
1.2.  Chordata
.sp
6.6.6.  Daimonia
.sp
7.  Plantae
.fi
T}
.TE
.
.
.PP
After
.CW .NH
is called,
the assigned number is made available in the strings
.CW SN\-DOT
(as it appears in a printed heading with default formatting,
followed by a terminating period)
and
.CW SN\-NO\-DOT
(with the terminating period omitted).
.
These are GNU extensions.
.
.
.PP
You can control the style used to print numbered headings by defining an
appropriate alias for the string
.CW SN\-STYLE .
.
By default,
.CW \[rs]*[SN\-STYLE]
is aliased to
.CW \[rs]*[SN\-DOT] .
.
If you prefer to omit the terminating period from numbers appearing in
numbered headings,
you may define the alias as follows.
.
.
.TS
box center;
lf(CR).
\&.als SN\-STYLE SN\-NO\-DOT
.TE
.
.
.LP
Any such change in numbering style becomes effective from the next use
of
.CW .NH
following redefinition of the alias for
.CW \[rs]*[SN\-STYLE] .
.
The formatted number of the current heading is available in
.CW \[rs]*[SN]
(a feature first documented by Berkeley),
which facilitates its inclusion in,
for example,
table captions,
equation labels,
and
.CW .XS /\c
.CW .XA /\c
.CW .XE
table of contents entries.
.
.
.TS
box;
cb cb
lf(CR) lx .
Macro	Description
_
\&.SH [\f[I]depth\f[]]	T{
Set an unnumbered heading.
.
The optional
.I depth
argument is a GNU extension indicating the heading depth corresponding
to the
.I depth
argument of
.CW .NH .
.
It matches the type size at which the heading is set to that of a
numbered heading at the same depth when the
.CW \[rs]n[GROWPS]
and
.CW \[rs]n[PSINCR]
heading size adjustment mechanism is in effect.
T}
.TE
.
.
.PP
The
.CW PSINCR
register defines an increment in type size to be applied to a heading at
a lesser depth than that specified in
.CW \[rs]n[GROWPS] .
.
The value of
.CW \[rs]n[PSINCR]
should be specified in points with the
.CW p
scaling unit and may include a fractional component;
for example,
.
.
.TS
box center;
lf(CR).
\&.nr PSINCR 1.5p
.TE
.
.
.LP
sets a type size increment of 1.5 points.
.
.
.PP
The
.CW GROWPS
register defines the heading depth above which the type size increment
set by
.CW \[rs]n[PSINCR]
becomes effective.
.
For each heading depth less than the value of
.CW \[rs]n[GROWPS] ,
the type size is increased by
.CW \[rs]n[PSINCR] .
.
Setting
.CW \[rs]n[GROWPS]
to a value less than\~2 disables the incremental heading size feature.
.
.
.PP
In other words,
if the value of
.CW GROWPS
register is greater than the
.I depth
argument to a
.CW .NH
or
.CW .SH
call,
the type size of a heading produced by these macros increases by
.CW \[rs]n[PSINCR]
units over
.CW \[rs]n[PS]
multiplied by the difference of
.CW \[rs]n[GROWPS]
and
.I depth .
.
.
For example,
the sequence
.
.TS
box center;
lf(CR).
\&.nr PS 10
\&.nr GROWPS 3
\&.nr PSINCR 1.5p
\&.NH 1
Carnivora
\&.NH 2
Felinae
\&.NH 3
Felis catus
\&.SH 2
Machairodontinae
.TE
.
.
.LP
will cause \[lq]1. Carnivora\[rq] to be printed in 13-point text,
followed by \[lq]1.1. Felinae\[rq] in 11.5-point text,
while \[lq]1.1.1. Felis catus\[rq] and all more deeply nested headings
will remain in the 10-point text specified by the
.CW PS
register.
.
\[lq]Machairodontinae\[rq] is printed at 11.5 points,
since it corresponds to heading depth\~2.
.
.
.PP
The
.CW \[rs]n[HORPHANS]
register operates in conjunction with the
.CW NH
and
.CW SH
macros to inhibit the printing of isolated headings at the bottom of a
page;
it specifies the minimum number of lines of the subsequent paragraph
that must be kept on the same page as the heading.
.
If insufficient space remains on the current page to accommodate the
heading and this number of lines of paragraph text,
a page break is forced before the heading is printed.
.
Any display macro call or
.I tbl ,
.I pic ,
or
.I eqn
region
(see subsequent sections)
between the heading and the subsequent paragraph suppresses this
grouping.
.
.
.\" The next table is huge and we need a lot of room for it, but we
.\" can't use a keep because it's a boxed repeated-heading table.  Flush
.\" the pending output line and demand half a page.
.br
.ne (\n[.p]u / 2u)
.NH 2
Typeface and decoration
.XS
	Typeface and decoration
.XE
.
.
.LP
The
.I ms
macros provide a variety of ways to style text.
.
Attend closely to the ordering of arguments labeled
.I pre
and
.I post,
which is not intuitive.
.
Support for
.I pre
arguments is a GNU extension.\**
.FS
This idiosyncrasy arose through feature accretion;
for example,
the
.CW B
macro in Version\~6 Unix
.I ms
(1975) accepted only one argument,
the text to be set in boldface.
.
By Version\~7 (1979) it recognized a second argument;
in 1990,
.I "groff ms"
added a \*[Q]pre\*[U] argument,
placing it third to avoid breaking support for older documents.
.FE
.
.
.TS H
box;
lb lb
lf(CR) lx.
Macro	Description
_
.TH
\&.B \f[R][\f[I]text\f[] [\f[I]post\f[] [\f[I]pre\f[]]]]	T{
Style
.I text
in
.B bold ,
followed by
.I post
in the previous font style without intervening space,
and preceded by
.I pre
similarly.
.
Without arguments,
.I ms
styles subsequent text in bold
until the next
paragraphing,
heading,
or no-argument typeface macro call.
T}
_
\&.R \f[R][\f[I]text\f[] [\f[I]post\f[] [\f[I]pre\f[]]]]	T{
As
.CW .B ,
but use the roman style
(upright text of normal weight)
instead of bold.
.
Argument recognition is a GNU extension.
T}
_
\&.I \f[R][\f[I]text\f[] [\f[I]post\f[] [\f[I]pre\f[]]]]	T{
As
.CW .B ,
but use an
.I italic
or oblique style instead of bold.
T}
_
\&.BI \f[R][\f[I]text\f[] [\f[I]post\f[] [\f[I]pre\f[]]]]	T{
As
.CW .B ,
but use a
.BI "bold italic"
or bold oblique style instead of upright bold.
.
This is a Tenth Edition Research Unix extension.
.\" possibly 9th, but definitely not Berkeley
T}
_
\&.CW \f[R][\f[I]text\f[] [\f[I]post\f[] [\f[I]pre\f[]]]]	T{
As
.CW .B ,
but use a
.CW constant-width
(monospaced) roman typeface instead of bold.
.
This is a Tenth Edition Research Unix extension.
.\" possibly 9th, but definitely not Berkeley
T}
_
\&.BX \f[R][\f[I]text\f[]]	T{
Typeset
.I text
and draw a
.BX box
around it.
.
On terminal devices,
reverse video is used instead
(see the implementation note below).
.
If you want
.I text
to contain space,
use unbreakable space or horizontal motion escape sequences
.CW \[rs]\[ti] , (
.CW \[rs]\c
.I space ,
.CW \[rs]\[ha] ,
.CW \[rs]| ,
.CW \[rs]0 ,
or
.CW \[rs]h ).
T}
_
\&.UL \f[R][\f[I]text\f[] [\f[I]post\f[]]]	T{
Typeset
.I text
with an
.UL underline .
.
.I post,
if present,
is set after
.I text
with no intervening space.
T}
_
\&.LG	T{
Set subsequent text in
.LG
larger type
.NL
(2\~points larger than the current size)
until the next
type size,
paragraphing,
or heading macro call.
.
You can
.LG
specify this macro
.LG
multiple times
.NL
to enlarge the type size as needed.
T}
_
\&.SM	T{
Set subsequent text in
.SM
smaller type
.NL
(2\~points smaller than the current size)
until the next
type size,
paragraphing,
or heading macro call.
.
You can
.SM
specify this macro
.SM
multiple times
.NL
to reduce the type size as needed.
T}
_
\&.NL	T{
Set subsequent text at the normal type size
.CW \[rs]n[PS] ). (
T}
.TE
.
.
.PP
.I pre
and
.I post
arguments
are typically used to simplify the attachment of punctuation to styled
words.
When
.I pre
is used,
a hyphenation control escape sequence
.CW \[rs]%
that would ordinarily start
.I text
must start
.I pre
instead to have the desired effect.
.
.TS
box center;
Cb Cb
Lf(CR) L.
Input	Result
T{
.na
.nh
The CS course\[aq]s students found one C language keyword
.br
\&.CW static ) \[rs]%(
.br
most troublesome.
T}	T{
The CS course's students found one C language keyword
.CW static ) \%(
most troublesome.
T}
.TE
.
.KS
You can use the output line continuation escape sequence
.CW \[rs]c
to achieve the same result.
.
It is also portable to some older
.I ms
implementations. \" DWB 3.3 ms: no; Heirloom Doctools ms: yes
.
.TS
box center;
Cb Cb
Lf(CR) L.
Input	Result
T{
.na
.nh
The CS course\[aq]s students found one C language keyword
.br
\[rs]%(\[rs]c
.br
\&.CW static )
.br
most troublesome.
T}	T{
The CS course's students found one C language keyword
\%(\c
.CW static )
most troublesome.
T}
.TE
.KE
.
.
.PP
Rather than calling the
.CW CW
macro,
in
.I "groff ms"
you might prefer to change the font family to Courier by setting
.CW \[rs]*[FAM]
to
.CW C \[rq]. \[lq]
.
You can then use all four style macros above,
returning to the default family (Times) with
.CW ".ds FAM T" \[rq]. \[lq]
.
Because changes to
.CW \[rs]*[FAM]
take effect only at the next paragraph,
this document uses
.CW .CW
to \[lq]inline\[rq] a change to the font family,
marking syntactical elements of
.I ms
and
.I groff .
.
.
.KS
.PP
.I "groff ms"
also offers strings to begin and end super- and subscripting.
.
These are GNU extensions.
.
.
.TS
box;
lb lb
lf(CR) lx.
String	Description
_
\[rs]*{	Begin superscripting.
\[rs]*}	End superscripting.
_
\[rs]*<	Begin subscripting.
\[rs]*>	End subscripting.
.TE
.KE
.
.
.nr PS -2
.nr VS -2
.LP
.B1
.hy 0
.I "Implementation note:"
In
.CW nroff
mode,
the
.CW BX
macro \[lq]boxes\[rq] its argument by bracketing it with
.I groff
extension escape sequences to set the foreground color to black and the
background to white and then reset them to their previous values;
the terminal output driver,
.I grotty (1),
converts these to ISO\~6429 color escape sequences,
which may be ignored or mishandled by some terminals,
or may be disabled by
.I grotty 's
.CW \-c
option.
.
Further,
if the terminal is set up to use these colors in those roles already,
.CW .BX
will cause no visible effect in the output.
.
Surmounting these challenges would require adding features to
.I grotty ,
for instance to provide a mechanism to request ISO\~6429's
\[lq]standout\[rq] mode \" That's "smso" and "rmso" in terminfo.
(often supported on monochrome terminals),
or to replace the presumed support of the terminal for ISO\~6429 escape
sequences with the use of a library that can query the capabilities of
the terminal and adapt the output sent to the device accordingly.
.
(Practically,
this likely means adding a dependency on
.CW libtinfo .)
.
Contact the
.I groff
development mailing list if you'd like to contribute.
.sp \n[PD]/2
.B2
.nr PS +2
.nr VS +2
.
.
.NH 2
Lists
.XS
	Lists
.XE
.
.
.LP
The
.I marker
argument to the
.CW IP
macro can be employed to present a variety of lists;
for instance,
you can use a bullet glyph
.CW \[rs][bu] ) (
for unordered lists,
a number
(or auto-incrementing register)
for numbered lists,
or a word or phrase for glossary-style or definition lists.
.
If you set the paragraph indentation register
.CW PI
before calling
.CW IP ,
you can later reorder the items in the list without having to ensure
that a
.I width
argument remains affixed to the first call.
.
.
.TS H
box center;
cb cb
lf(CR) l .
Input	Result
_
.TH
T{
.nf
\&.nr PI 2n
A bulleted list:
\&.IP \[rs][bu]
lawyers
\&.IP \[rs][bu]
guns
\&.IP \[rs][bu]
money
.fi
T}	T{
.nr PI 2n
A bulleted list:
.IP \[bu]
lawyers
.IP \[bu]
guns
.IP \[bu]
money
T}
_
T{
.nf
\&.nr step 0 1
\&.nr PI 3n
A numbered list:
\&.IP \[rs]n+[step].
lawyers
\&.IP \[rs]n+[step].
guns
\&.IP \[rs]n+[step].
money
.fi
T}	T{
.nr step 0 1
.nr PI 3n
A numbered list:
.IP \n+[step].
lawyers
.IP \n+[step].
guns
.IP \n+[step].
money
T}
_
T{
.nf
A glossary-style list:
\&.IP lawyers 0.4i
Two or more attorneys.
\&.IP guns
Firearms,
preferably large-caliber.
\&.IP money
Gotta pay for those
lawyers and guns!
.fi
T}	T{
A glossary-style list:
.
.IP lawyers 0.4i
Two or more attorneys.
.IP guns
Firearms,
preferably large-caliber.
.IP money
Gotta pay for those lawyers and guns!
T}
.TE
.
.
.PP
In the enumerated list example,
we employed the
.CW nr
request to create a register of our own,
.CW step .
.
We initialized it to zero and assigned it an auto-increment of 1.
.
Each time we use the escape sequence
.CW \[rs]n+[PI]
(note the plus sign),
the formatter applies the increment just before interpolating the
register's value.
.
Preparing the
.CW PI
register as well enables us to rearrange the list without the tedium of
updating macro calls.
.
.
.PP
In the glossary example,
observe how the
.CW IP
macro places the definition on the same line as the term if it has
enough space.
.
If this is not what you want,
there are a few workarounds we will illustrate by modifying the example.
.
First,
you can use a
.CW br
request to force a break after printing the term or label.
.
Second,
you could apply the
.CW \[rs]p
escape sequence to force a break.
.
The space following the escape sequence is important;
if you omit it,
.I groff
prints the first word of the paragraph text on the same line as the term
or label
(if it fits)
.I then
breaks the line.
.
Finally,
you may append a horizontal motion to the marker with the
.CW \[rs]h
escape sequence;
using the same amount as the indentation will ensure that the marker is
too wide for
.I groff
to treat it as \[lq]fitting\[rq] on the same line as the paragraph text.
.
.
.TS
box center;
cb | cb | cb
lf(CR) | lf(CR)  | lf(CR).
Approach #1	Approach #2	Approach #3
_
T{
.nf
\&.IP guns
\&.br
Firearms,
.fi
T}	T{
.nf
\&.IP guns
\[rs]p Firearms,
.fi
T}	T{
.nf
\&.IP guns\[rs]h\[aq]0.4i\[aq]
Firearms,
.fi
T}
_
.T&
cb s s
l s s.
Result
_
T{
A glossary-style list:
.
.IP lawyers 0.4i
Two or more attorneys.
.IP guns\h\[aq]0.4i\[aq] 0.4i
Firearms,
preferably large-caliber.
.IP money
Gotta pay for those lawyers and guns!
T}
.TE
.
.
.NH 2
Indented regions
.XS
	Indented regions
.XE
.
.
.LP
You may need to indent a region of text while otherwise formatting it
normally.
.
Indented regions can be nested;
you can change
.CW \[rs]n[PI]
before each call to vary the amount of inset.
.
.
.TS
box;
cb cb
lf(CR) lx .
Macro	Description
_
\&.RS	T{
Begin a region where headings,
paragraphs,
and displays are indented (further) by
.CW \[rs]n[PI] .
T}
\&.RE	T{
End the (next) most recent indented region.
T}
.TE
.
.
.PP
This feature enables you to easily line up text under hanging and
indented paragraphs.
.
For example,
you may wish to structure lists hierarchically.
.
.
.KS
.TS
box center;
cb cb
lf(CR)8 l .
Input	Result
_
T{
.nf
.CW
\&.IP \[rs][bu] 2
Lawyers:
\&.RS
\&.IP \[rs][bu]
Dewey,
\&.IP \[rs][bu]
Cheatham,
and
\&.IP \[rs][bu]
Howe.
\&.RE
\&.IP \[rs][bu]
Guns
.R
\&.\|.\|.
.fi
T}	T{
.IP \[bu] 2
Lawyers:
.RS
.IP \[bu]
Dewey,
.IP \[bu]
Cheatham,
and
.IP \[bu]
Howe.
.RE
.IP \[bu]
Guns
\&.\|.\|.
T}
.TE
.KE
.
.
.NH 2
Keeps, boxed keeps, and displays
.XS
	Keeps, boxed keeps, and displays
.XE
.
.
.LP
On occasion,
you may want to
.I keep
several lines of text,
or a region of a document,
together on a single page,
preventing an automatic page break within certain boundaries.
.
This can cause a page break to occur earlier than it normally would.
.
For example,
you may want to keep two paragraphs together,
or a paragraph that refers to a table,
list,
or figure adjacent to the item it discusses.
.
.I ms
provides the
.CW KS
and
.CW KE
macros for this purpose.
.
.
.PP
You can alternatively specify a
.I "floating keep:"
if a keep cannot fit on the current page,
.I ms
holds its contents and allows material following the keep
(in the source document)
to fill the remainder of the current page.
.
When the page breaks,
whether by reaching the end or
.CW bp
request,
.I ms
puts the floating keep at the beginning of the next page.
.
This is useful for placing large graphics or tables that do not need to
appear exactly where they occur in the source document.
.
.
.TS
box;
cb cb
lf(CR) lx .
Macro	Description
_
\&.KS	Begin a keep.
\&.KF	Begin a floating keep.
_
\&.KE	End (floating) keep.
.TE
.
.
.PP
As an alternative to the keep mechanism,
the
.CW ne
request forces a page break if there is not at least the amount of
vertical space specified in its argument remaining on the page.
.
One application of
.CW ne
is to reserve space on the page for a figure or illustration to be
included later.
.
.
.KS
.PP
A
.I "boxed keep"
has a frame drawn around it.
.
.
.TS
box;
cb cb
lf(CR) lx .
Macro	Description
_
\&.B1	Begin a keep with a box drawn around it.
\&.B2	End boxed keep.
.TE
.KE
.
.
.KS
.LP
Boxed keep macros cause breaks;
if you need to box a word or phrase within a line,
see the
.CW BX
macro in section \[lq]Typeface and decoration\[rq] above.
.
Box lines are drawn as close as possible to the text they enclose so
that they are usable within paragraphs.
.
If you wish to place one or more paragraphs in a boxed keep,
you may improve their appearance by calling
.CW .B1
after the first paragraphing macro,
and by adding a small amount of vertical space before calling
.CW .B2 .
.
.
.TS
box center;
lf(CR).
\&.LP
\&.B1
\&.I Warning:
Happy Fun Ball may suddenly accelerate to dangerous speeds.
\&.sp \[rs]n[PD]/2 \[rs]" space by half the inter-paragraph distance
\&.B2
.TE
.KE
.
.
.LP
If you want a boxed keep to float,
you will need to enclose the
.CW .B1
and
.CW .B2
calls within a pair of
.CW .KF
and
.CW .KE
calls.
.
.
.PP
.I Displays
turn off filling;
lines of verse or program code are shown with their lines broken as in
the source document without requiring
.CW br
requests between lines.
.
Displays can be kept on a single page or allowed to break across pages.
.
The
.CW DS
macro begins a kept display of the layout specified in its first
argument;
non-kept displays are begun with dedicated macros corresponding to their
layout.
.
.
.TS
box;
cb s | cb
cb cb | ^
lf(CR) lf(CR) | lx .
Display macro	Description
With keep	Without keep
_
\&.DS L	\&.LD	Begin left-aligned display.
\&.DS \f[R][\f[]I\f[R] [\,\f[I]indent\/\f[]]]	\
\&.ID \f[R][\,\f[I]indent\/\f[]]	T{
Begin display indented by
.I indent
if given,
.CW \[rs]n[DI]
otherwise.
T}
\&.DS B	\&.BD	T{
Begin block display
(left-aligned with longest line centered).
T}
\&.DS C	\&.CD	Begin centered display.
\&.DS R	\&.RD	T{
Begin right-aligned display.
This is a GNU extension.
T}
_
.T&
cf(CR) s | lx .
\&.DE	End any display.
.TE
.
.
.PP
The distance stored in
.CW \[rs]n[DD]
is inserted before and after each pair of display macros;
this is a Berkeley extension.
.
In
.I "groff ms" ,
this distance replaces any adjacent inter-paragraph distance
or subsequent spacing prior to a section heading.
.
The
.CW DI
register is a GNU extension;
its value is an indentation applied to displays created with
.CW .DS
and
.CW .ID
without arguments,
to
.CW .DS\~I \[rq] \[lq]
without an indentation argument,
and to equations set with
.CW .EQ\~I \[rq]. \[lq]
.
Changes to either register take effect at the next display boundary.
.
.
.KS
.NH 2
Tables, figures, equations, and references
.XS
	Tables, figures, equations, and references
.XE
.LP
The
.I ms
package is often used with the
.I tbl ,
.I pic ,
.I eqn ,
and
.I refer
preprocessors.
.
The
.CW \[rs]n[DD]
distance is also applied to regions of the document preprocessed with
.I tbl ,
.I pic ,
and
.I eqn .
.
Mark text meant for preprocessors by enclosing it in pairs of tokens as
follows,
with nothing between the dot and the macro name.
.
The preprocessors match these tokens only at the start of an input line.
.
.
.TS
box;
cb cb
lf(CR) lx .
Tag pair	Description
_
T{
\&.TS
.R
.CW H ] [
.CW
.br
\&.TE
T}	T{
Demarcate a table to be processed by the
.I tbl
preprocessor.
.
The optional
.CW H
argument to
.CW .TS
instructs
.I ms
to repeat table rows
(often column headings)
at the top of each new page the table spans,
if applicable;
calling the
.CW TH
macro marks the end of such rows.
.
The GNU
.I tbl (1)
man page provides a comprehensive reference to the preprocessor and
offers examples of its use.
T}
_
T{
\&.PS
.br
\&.PE
.br
\&.PF
T}	T{
.CW .PS
begins a picture to be processed by the
.I pic
preprocessor;
either of
.CW .PE
or
.CW .PF
ends it,
the latter with \[lq]flyback\[rq] to the vertical position at its top.
.
You can create
.I pic
input manually or with a program such as
.I xfig (1).
T}
_
T{
\&.EQ
.R
.I align \~[\c [
.I label ]]
.CW
.br
\&.EN
T}	T{
Demarcate an equation to be processed by the
.I eqn
preprocessor.
.
The equation is centered by default;
.I align
can be
.CW C ,
.CW L ,
or
.CW I
to (explicitly) center,
left-align,
or indent it by
.CW \[rs]n[DI] ,
respectively.
.
If specified,
.I label
is set right-aligned.
T}
_
T{
\&.[
.br
\&.]
T}	T{
Demarcate a bibliographic citation to be processed by the
.I refer
preprocessor.
.
The GNU
.I refer (1)
man page provides a comprehensive reference to the preprocessor and the
format of its bibliographic database.
T}
.TE
.KE
.
.
.PP
When
.I refer
emits collected references
(as might be done on a \[lq]Works Cited\[rq] page),
it interpolates the string
.CW \[rs]*[REFERENCES]
as an unnumbered heading
.CW .SH ). (
.
.
.KS
.PP
The following is an example of how to set up a table that may print
across two or more pages.
.
.
.TS
box center;
l .
T{
.nf
.CW
\&.TS H
allbox;
Cb | Cb .
Part\[->]Description
_
\&.TH
\&.T&
L | Lx .
GH-1978\[->]Fribulating gonkulator
.R
\&.\|.\|.\|the rest of the table follows\|.\|.\|.
.CW
\&.TE
.R
.fi
T}
.TE
.
.
Attempting to place a multi-page table inside a keep can lead to
unpleasant results,
particularly if the
.I tbl
.CW allbox
option is used.
.KE
.
.
.PP
Mathematics can be typeset using the language of the
.I eqn
preprocessor.
.
.
.TS
box center;
Lf(CR).
\&.EQ C (\[rs]*[SN\-NO\-DOT]a)
p \[ti] = \[ti] q sqrt { 1 + \[ti] ( x / q sup 2 ) }
\&.EN
.TE
.
.
This input formats a labelled equation.
.
We used the
.CW SN\-NO\-DOT
string to base the equation label on the current heading number,
giving us more flexibility to reorganize the document.
.
.
.EQ C (\*[SN-NO-DOT]a)
p ~ = ~ q sqrt { 1 + ~ ( x / q sup 2 ) }
.EN
.
Use
.I groff
options
to run preprocessors on the input:
.CW \-e
for
.I eqn ,
.CW \-p
for
.I pic ,
.CW \-R
for
.I refer ,
and
.CW \-t
for
.I tbl.
.
.
.KS
.NH 2
Footnotes
.XS
	Footnotes
.XE
.
.
.LP
.\" The following sentence is used below as an example as well.  Keep it
.\" in sync.
A footnote is typically anchored to a place in the text with a
.I marker,
which is a small integer,\**
.FS
like this numeric footnote
.FE
a symbol,\*{\[dg]\*}
.FS \[dg]
like this symbolic footnote
.FE
or arbitrary user-specified text.
.
.
.TS
box;
lb lb
lf(CR) lx.
String	Description
_
\[rs]**	T{
Place an
.I "automatic number,"
an automatically updated numeric footnote marker,
in the text.
.
Each time this string is interpolated,
the number it produces increments by one.
.
Automatic numbers start at 1.
.
This is a Berkeley extension.
T}
.TE
.KE
.
.
.PP
Enclose the footnote text in
.CW FS
and
.CW FE
macro calls to set it at the nearest available \[lq]foot\[rq],
or bottom,
of a text column or page.
.
.
.TS
box;
cb cb
lfCR lx .
Macro	Description
_
\&.FS \f[R][\f[I]marker\f[]]	T{
Begin a footnote.
.
The
.CW FS\-MARK
hook
(see below)
is called with any supplied
.I marker
argument,
which is then also placed at the beginning of the footnote text.
.
If
.I marker
is omitted,
the next pending automatic number enqueued by interpolation of the
.CW *
string is used,
and if none exists,
nothing is prefixed.
.
T}
_
\&.FE	End footnote text.
.TE
.
.
.PP
You may not desire automatically numbered footnotes in spite of their
convenience.
.
You can indicate a footnote with a symbol or other text by specifying
its marker at the appropriate place
(for example,
by using
.CW \[rs][dg]
for the dagger glyph)
.I and
as an argument to the
.CW FS
macro.
.
Such manual marks should be repeated as arguments to
.CW .FS
or as part of the footnote text to disambiguate their correspondence.
.
You may wish to use
.CW \[rs]*{
and
.CW \[rs]*}
to superscript the marker at the anchor point,
in the footnote text,
or both.
.
.
.PP
.I "groff ms"
provides a hook macro,
.CW FS\-MARK ,
for user-determined operations to be performed when the
.CW FS
macro is called.
.
It is passed the same arguments as
.CW FS
itself.
.
An application of
.CW FS\-MARK
is anchor placement for a hyperlink reference,
so that a footnote can link back to its referential context.\**
.
.FS
\[lq]Portable Document Format Publishing with GNU Troff\[rq],
.I pdfmark.ms
in the
.I groff
distribution,
uses this technique.
.FE
.
By default,
this macro has an empty definition.
.
.CW FS\-MARK
is a GNU extension.
.
.
.PP
The following input was used to produce the first sentence in this
section.
.
.
.TS
box center;
lfCR.
A footnote is anchored to a place in the text with a
\&.I marker,
which is a small integer,\[rs]**
\&.FS
like this numeric footnote
\&.FE
a symbol,\[rs]*{\[rs][dg]\[rs]*}
\&.FS \[rs][dg]
like this symbolic footnote
\&.FE
or arbitrary user-specified text.
.TE
.
.
.PP
Footnotes can be safely used within keeps and displays,
but you should avoid using automatically numbered footnotes within
floating keeps.
.
You can place a second
.CW \[rs]**
interpolation between a
.CW \[rs]**
and its corresponding
.CW .FS
call as long as each
.CW .FS
call occurs
.I after
the corresponding
.CW \[rs]**
and occurrences of
.CW .FS
are in the same order as corresponding occurrences of
.CW \[rs]** .
.
.
.PP
Footnote text is formatted as paragraphs are,
using analogous parameters.
.
The registers
.CW FI ,
.CW FPD ,
.CW FPS ,
and
.CW FVS
correspond to
.CW PI ,
.CW PD ,
.CW PS ,
and
.CW VS ,
respectively;
.CW FPD ,
.CW FPS ,
and
.CW FVS
are GNU extensions.
.
.
.KS
.PP
The
.CW FF
register controls the formatting of automatically numbered footnote
paragraphs,
and those for which
.CW .FS
is given a
.I marker
argument,
at the bottom of a column or page as follows.
.
.
.TS
box;
cb cb
lf(CR) lx .
\f[CB]FF\f[] value	Description
_
0	T{
Set an automatic number as a superscript
(on typesetter devices)
or surrounded by square brackets
(on terminals).
.
The footnote paragraph is indented as with
.CW .PP
if there is an
.CW .FS
argument or an automatic number,
and as with
.CW .LP
otherwise.
.
This is the default.
T}
1	T{
As
.CW 0 ,
but set the marker as regular text,
and follow an automatic number with a period.
T}
2	T{
As
.CW 1 ,
but without indentation
(like
.CW .LP ).
T}
3	T{
As
.CW 1 ,
but set the footnote paragraph with the marker hanging
(like
.CW .IP ).
T}
.TE
.KE
.
.
.PP
The default footnote line length is 11/12ths of the normal line length
for compatibility with the expectations of historical
.I ms
documents;
you may wish to set
.CW \[rs]*[FR]
to
.CW 1
to align with contemporary typesetting practices.
.
In the past,\**
.FS
Unix
Version\~7
.I ms ,
its descendants,
and
.I "groff ms"
prior to version 1.23.0
.FE
an
.CW FL
register was used for the line length in footnotes;
however,
setting this register at document initialization time had no effect on
the footnote line length in multi-column arrangements.\**
.
.FS
You could reset it after each call to
.CW .1C ,
.CW .2C ,
or
.CW .MC .
.FE
.
.
.PP
.CW \[rs]*[FR]
should be used in preference to
.CW \[rs]n[FL]
in contemporary documents.
.
The footnote line length is effectively computed as
.I column-width "" \[lq]
.CW "\~*\~\[rs]*[FR]" \[rq].
.
If an absolute footnote line length is required,
recall that arithmetic expressions in the
.I roff
language are evaluated strictly from left to right,
with no operator precedence
(parentheses are honored).
.
.
.TS
box center;
lf(CR).
\&.ds FR 0+3i \[rs]" Set footnote line length to 3 inches.
.TE
.
.
.LP \" continuing previous paragraph
Changes to the footnote length ratio
.CW \[rs]*[FR]
take effect with the next footnote written in single-column
arrangements,
but on the next page in multiple-column contexts.
.
.
.KS
.NH 2
Language and localization
.XS
	Language and localization
.XE
.
.
.LP
.I "groff ms"
provides several strings that you can customize for your own purposes,
or redefine to adapt the macro package to languages other than English.
.
It is already localized for
.\" cs, de, fr, it, sv
Czech,
German,
French,
Italian,
and
Swedish.
.
Load the desired localization macro package after
.I ms ;
see the
.I groff_tmac (5)
man page.
.
.
.TS
box center;
lf(CR).
$ \f[CB]groff \-ms \-mfr bienvenue.ms
.TE
.
.
.PP
The following strings are available.
.
.TS
box center;
cb lb
lf(CR) lf(CR) .
String	Default
_
\[rs]*[REFERENCES]	References
\[rs]*[ABSTRACT]	\[rs]f[I]ABSTRACT\[rs]f[]
\[rs]*[TOC]	Table of Contents
\[rs]*[MONTH1]	January
\[rs]*[MONTH2]	February
\[rs]*[MONTH3]	March
\[rs]*[MONTH4]	April
\[rs]*[MONTH5]	May
\[rs]*[MONTH6]	June
\[rs]*[MONTH7]	July
\[rs]*[MONTH8]	August
\[rs]*[MONTH9]	September
\[rs]*[MONTH10]	October
\[rs]*[MONTH11]	November
\[rs]*[MONTH12]	December
.TE
.
.
.PP
The default for
.CW \[rs]*[ABSTRACT]
includes font selection escape sequences to set the word in italics.
.KE
.
.
.KS
.NH 2
Glyphs for special characters
.XS
	Glyphs for special characters
.XE
.
.
.LP
Some of the special character escape sequences used in this document
are listed below.
.
The minus sign glyph can also be accessed by the shorthand
.CW \[rs]\[mi] .
.
These and many others are documented in the
.I groff_char (7)
man page.
.
.
.TS
box center;
Cb Lb Lb
Lf(CR) L L .
Input	Appearance	Description
_
\[rs][\-]	\[mi]	minus sign
\[rs][\->]	\[->]	right arrow
\[rs][aq]	\[aq]	neutral apostrophe
\[rs][bu]	\[bu]	bullet
\[rs][dq]	\[dq]	neutral double quote
\[rs][dg]	\[dg]	dagger
\[rs][em]	\[em]	em dash
\[rs][ha]	\[ha]	circumflex accent (caret, hat)
\[rs][lg]	\[lq]	left double quotation mark
\[rs][rq]	\[rq]	right double quotation mark
\[rs][rs]	\[rs]	reverse solidus (backslash)
\[rs][sd]	\[sd]	seconds (double prime) mark
\[rs][ti]	\[ti]	tilde
.TE
.KE
.
.\" ------------------------
.if t \{\
.  br
.  bp
.\}
.NH 1
Page layout
.XS
Page layout
.XE
.LP
.I ms 's
default page layout arranges text
in a single column
with the page number
between hyphens
centered in a header
on each page
except the first,
and produces no footers.
.
You can customize this arrangement.
.
.
.NH 2
Headers and footers
.XS
	Headers and footers
.XE
.
.
.LP
There are multiple ways to produce headers and footers.
.
One is to define the strings
.CW LH ,
.CW CH ,
and
.CW RH
to set the left,
center,
and right headers,
respectively;
and
.CW LF ,
.CW CF ,
and
.CW RF
to set the left,
center,
and right footers.
.
This approach suffices for documents that do not distinguish odd- and
even-numbered pages.
.
.
.PP
Another method is to call macros that set headers or footers for odd- or
even-numbered pages.
.
Each such macro takes a delimited argument separating the left,
center,
and right header or footer texts from each other.
.
You can replace the neutral apostrophes (\[aq]) shown below with any
character not appearing in the header or footer text.
.
These macros are Berkeley extensions.
.
.
.TS
box;
lb lb
lf(CR) lx.
Macro	Description
_
\&.OH \[aq]\f[I]left\f[]\[aq]\f[I]center\f[]\[aq]\f[I]right\f[]\[aq]\
	T{
Set the left, center, and right headers on odd-numbered (recto) pages.
T}
\&.OF \[aq]\f[I]left\f[]\[aq]\f[I]center\f[]\[aq]\f[I]right\f[]\[aq]\
	T{
Set the left, center, and right footers on odd-numbered (recto) pages.
T}
\&.EH \[aq]\f[I]left\f[]\[aq]\f[I]center\f[]\[aq]\f[I]right\f[]\[aq]\
	T{
Set the left, center, and right headers on even-numbered (verso) pages.
T}
\&.EF \[aq]\f[I]left\f[]\[aq]\f[I]center\f[]\[aq]\f[I]right\f[]\[aq]\
	T{
Set the left, center, and right footers on even-numbered (verso) pages.
T}
.TE
.
.
.PP
With either method,
a percent sign
.B %
in header or footer text is replaced by the current page number.
.
By default,
.I ms
places no header on a page numbered \[lq]1\[rq]
(regardless of its number format).
.
.
.TS
box;
lb lb
lf(CR) lx.
Macro	Description
_
\&.P1	T{
Typeset the header even on page\~1.
.
To be effective,
this macro must be called before the header trap is sprung on any page
numbered \[lq]1\[rq];
in practice,
unless your page numbering is unusual,
this means that you should call it early,
before
.CW .TL
or any heading or paragraphing macro.
.
This is a Berkeley extension.
T}
.TE
.
.
.PP
For even greater flexibility,
.I ms
is designed to permit the redefinition of the macros that are called
when the
.I groff
traps that ordinarily cause the headers and footers to be output are
sprung.
.
.CW PT
(\[lq]page trap\[rq])
is called by
.I ms
when the header is to be written,
and
.CW BT
(\[lq]bottom trap\[rq])
when the footer is to be.
.
The
.I groff
page location trap that
.I ms
sets up to format the header also calls the
(normally undefined)
.CW HD
macro after
.CW .PT ;
you can define
.CW .HD
if you need additional processing after setting the header
(for example,
to draw a line below it).
.
.\" Although undocumented in Tuthill's 4.2BSD ms.diffs paper...
The
.CW HD
hook is a Berkeley extension.
.
Any such macros you (re)define must implement any desired specialization
for odd-,
even-,
or first numbered pages.
.
.
.KS
.NH 2
Tab stops
.XS
	Tab stops
.XE
.
.
.LP
Use the
.CW ta
request to set tab stops as needed.
.
.
.TS
box;
lb lb
lf(CR) lx.
Macro	Description
_
\&.TA	T{
Reset the tab stops to the
.I ms
default
(every 5 ens).
.
Redefine this macro to create a different set of default tab stops.
T}
.TE
.KE
.
.
.KS
.NH 2
Margins
.XS
	Margins
.XE
.
.
.LP
Control margins using the registers summarized in the \[lq]Margins\[rq]
portion of the table in section \[lq]Document control settings\[rq]
above.
.
There is no setting for the right margin;
the combination of page offset
.CW \[rs]n[PO]
and line length
.CW \[rs]n[LL]
determines it.
.KE
.
.
.KS
.NH 2
Multiple columns
.XS
	Multiple columns
.XE
.
.
.LP
.I ms
can set text in as many columns as reasonably fit on the page.
.
The following macros force a page break if a multi-column layout is
active when they are called.
.
.CW \[rs]n[MINGW]
is the default minimum gutter width;
it is a GNU extension.
.
When multiple columns are in use,
keeps
and the
.CW \%HORPHANS
and
.CW \%PORPHANS
registers
work with respect to column breaks instead of page breaks.
.
.
.TS
box;
cb cb
lf(CR) lx .
Macro	Description
_
\&.1C	T{
Arrange page text in a single column (the default).
T}
_
\&.2C	T{
Arrange page text in two columns.
T}
_
\&.MC \f[R][\f[I]column-width\f[] [\f[I]gutter-width\f[]]]	T{
Arrange page text in multiple columns.
.
If you specify no arguments,
it is equivalent to the
.CW 2C
macro.
.
Otherwise,
.I column-width
is the width of each column and
.I gutter-width
is the minimum distance between columns.
T}
.TE
.KE
.
.
.\" ------------------------
.NH 2
Creating a table of contents
.XS
	Creating a table of contents
.XE
.LP
Because
.I roff
formatters process their input in a single pass,
material on page 50,
for example,
cannot influence what appears on page\~1\[em]this poses a challenge for
a table of contents at its traditional location in front matter,
if you wish to avoid manually maintaining it.
.
.I ms
enables the collection of material to be presented in the table of
contents as it appears,
saving its page number along with it,
and then emitting the collected contents on demand toward the end of the
document.
.
The table of contents can then be resequenced to its desired location
by physically rearranging the pages of a printed document,
or as part of post-processing\[em]with a
.I sed (1)
script to reorder the pages in
.I troff 's
output,
with
.I pdfjam (1),
or with
.I gropdf (1)'s
.B .pdfswitchtopage
feature,
for example.
.
.
.PP
Define an entry to appear in the table of contents by bracketing its
text between calls to the
.CW XS
and
.CW XE
macros.
.
A typical application is to call them immediately after
.CW NH
or
.CW SH
and repeat the heading text within them.
.
The
.CW XA
macro,
used within
.CW .XS /\c
.CW .XE
pairs,
supplements an entry\[em]for instance,
when it requires multiple output lines,
whether because a heading is too long to fit or because style dictates
that page numbers not be repeated.
.
You may wish to indent the text thus wrapped to correspond to its
heading depth;
this can be done in the entry text by prefixing it with tabs or
horizontal motion escape sequences,
or by providing a second argument to the
.CW XA
macro.
.
.CW .XS
and
.CW .XA
automatically associate the page number where they are called with the
text following them,
but they accept arguments to override this behavior.
.
At the end of the document,
call
.CW TC
or
.CW PX
to emit the table of contents;
.CW .TC
resets the page number
.B i "" to\~
(Roman numeral one),
and then calls
.CW PX .
.
All of these macros are Berkeley extensions.
.
.TS
box;
cb cb
lf(CR) lx .
Macro	Description
_
\&.XS \f[R][\f[I]page-number\f[]]	T{
Begin,
supplement,
and end a table of contents entry.
.
Each entry is associated with
.I page-number
(otherwise the current page number);
a
.I page-number
of
.CW no
prevents a leader and page number from being emitted for that entry.
.
Use of
.CW .XA
within
.CW .XS /\c
.CW .XE
is optional;
it can be repeated.
.
If
.I indentation
is present,
a supplemental entry is indented by that amount;
ens are assumed if no unit is indicated.
.
Text on input lines between
.CW .XS
and
.CW .XE
is stored for later recall by
.CW .PX .
T}
\&.XA \f[R][\f[I]page-number\f[] [\f[I]indentation\f[]]]	\^
\&.XE	\^
_
\&.PX \f[R][\f[]no\f[R]]	T{
Switch to single-column layout.
.
Unless
.CW no
is specified,
center and interpolate
.CW \[rs]*[TOC]
in bold and two points larger than the body text.
.
Emit the table of contents entries.
T}
_
\&.TC \f[R][\f[]no\f[R]]	T{
Set the page number to\~1,
the page number format to lowercase Roman numerals,
and call
.CW PX
(with a
.CW no
argument,
if present).
T}
.TE
.
.
.KS
.PP
Here's an example of typical
.I ms
table of contents preparation and
its result.
.
We employ horizontal escape sequences
.CW \[rs]h
to indent the entries by sectioning depth.
.
.TS
box center;
L.
T{
.nf
.CW
\&.NH 1
Introduction
\&.XS
Introduction
\&.XE
.R
\&.\|.\|.
.CW
\&.NH 2
Methodology
\&.XS
\[rs]h\[aq]2n\[aq]Methodology
\&.XA no
\[rs]h\[aq]4n\[aq]Fassbinder\[aq]s Approach
\&.XA no
\[rs]h\[aq]4n\[aq]Kahiu\[aq]s Approach
\&.XE
.R
\&.\|.\|.
.CW
\&.NH 1
Findings
\&.XS
Findings
\&.XE
.R
\&.\|.\|.
.CW
\&.TC
.fi
T}
.TE
.KE
.
.nr SavedPageNumber \n%
.nr SavedH1 \n[H1] \" groff ms internal name
.nr SavedH2 \n[H2] \" groff ms internal name
.nr % 1
.rr H1
.rr H2
.als SavedTOC toc*div \" groff ms internal name
.rm toc*div
.di ThrowAway
.NH 1
Introduction
.XS
Introduction
.XE
.nr % 2
.NH 2
Methodology
.XS
\h'2n'Methodology
.XA no
\h'4n'Fassbinder's Approach
.XA no
\h'4n'Kahiu's Approach
.XE
.nr % 5
.NH 1
Findings
.XS
Findings
.XE
.br
.di
.\" We can't emit the TOC inside a B1/B2 box, so use lines instead.
.R
\l'\n[.l]u'
.PX
\l'\n[.l]u'
.als toc*div SavedTOC
.rm SavedTOC
.nr % \n[SavedPageNumber]
.nr H1 \n[SavedH1]
.nr H2 \n[SavedH2]
.rr SavedPageNumber
.rr SavedH1
.rr SavedH2
.
.
.PP
The remaining features in this subsection are GNU extensions.
.
.I "groff ms"
obviates the need to repeat heading text after
.CW XS
calls.
.
Call
.CW XN
and
.CW XH
after
.CW NH
and
.CW SH ,
respectively.
.
.
.TS
box;
cb cb
lf(CR) lx .
Macro	Description
_
\&.XN \f[I]heading-text	T{
Format
.I heading-text
and create a corresponding table of contents entry;
the indentation is computed from the depth of the preceding
.CW NH
call.
T}
\&.XH \f[I]depth heading-text	T{
As
.CW .XN ,
but use
.I depth
to determine the indentation.
T}
.TE
.
.
.KS
.PP
.I "groff ms"
encourages customization of table of contents entry production.
.
.
.TS
box;
cb cb
lf(CR) lx .
Macro	Description
_
\&.XN\-REPLACEMENT \f[I]heading-text	T{
These hook macros implement
.CW .XN
and
.CW .XH ,
respectively.
.
They call
.CW \%XN\-INIT
and
pass their
.I heading-text
arguments to
.CW .\%XH\-UPDATE\-TOC .
T}
\&.XH\-REPLACEMENT \f[I]depth heading-text	\^
\&.XH\-INIT	T{
This hook macro does nothing by default.
T}
\&.XH\-UPDATE\-TOC\~ \f[I]depth heading-text	T{
Bracket
.I heading-text
with
.CW XS
and
.CW XE
calls,
indenting it by 2 ens per level of
.I depth
beyond the first.
T}
.TE
.KE
.
.
.LP
.TS
box center;
L.
T{
.nf
.CW
\&.NH 1
\&.XN Introduction
.R
\&.\|.\|.
.CW
\&.NH 2
\&.XN Methodology
\&.XH 3 \[dq]Fassbinder\[aq]s Approach\[dq]
\&.XH 3 \[dq]Kahiu\[aq]s Approach\[dq]
.R
\&.\|.\|.
.CW
\&.NH 1
\&.XN Findings
.R
\&.\|.\|.
.CW
\&.TC
.fi
T}
.TE
.
.nr SavedPageNumber \n%
.nr SavedH1 \n[H1] \" groff ms internal name
.nr SavedH2 \n[H2] \" groff ms internal name
.nr % 1
.rr H1
.rr H2
.als SavedTOC toc*div \" groff ms internal name
.rm toc*div
.di ThrowAway
.NH 1
.XN Introduction
.nr % 2
.NH 2
.XN Methodology
.XH 3 "Fassbinder's Approach"
.XH 3 "Kahiu's Approach"
.nr % 5
.NH 1
.XN Findings
.br
.di
.\" We can't emit the TOC inside a B1/B2 box, so use lines instead.
.R
\l'\n[.l]u'
.PX
\l'\n[.l]u'
.als toc*div SavedTOC
.rm SavedTOC
.nr % \n[SavedPageNumber]
.nr H1 \n[SavedH1]
.nr H2 \n[SavedH2]
.rr SavedPageNumber
.rr SavedH1
.rr SavedH2
.
.
.PP
To get the section number of the numbered headings into the table of
contents entries,
we might define
.CW \%XN\-REPLACEMENT
as follows.
.
(We obtain the heading depth from
.I "groff ms" 's
internal register
.CW nh*hl .)
.
.
.LP
.TS
box center;
L.
T{
.nf
.CW
\&.de XN\-REPLACEMENT
\&.XN\-INIT
\&.XH\-UPDATE\-TOC \[rs]\[rs]n[nh*hl] \[rs]\[rs]$@
\&\[rs]&\[rs]\[rs]*[SN] \[rs]\[rs]$*
\&..
T}
.TE
.
.
.PP
You can change the style of the leader that bridges each table of
contents entry with its page number;
define the
.CW TC\-LEADER
special character by using the
.CW char
request.
.
A typical leader combines the dot glyph
.CW .\& \[rq] \[lq]
with a horizontal motion escape sequence to spread the dots.
.
The width of the page number field is stored in the
.CW TC\-MARGIN
register.
.
.
.\" ------------------------
.if t \{\
.  br
.  bp
.\}
.NH 1
Differences from AT&T
.BI ms
.XS
Differences from AT&T
.I ms
.XE
.LP
The
.I "groff ms"
macros are an independent reimplementation,
using no AT&T code.
.
Since they take advantage of the extended features of
.I groff ,
they cannot be used with AT&T
.I troff .
.
.I "groff ms"
supports features described above as Berkeley and Tenth Edition Research
Unix extensions,
and adds several of its own.
.
.
.PP
The internals of
.I "groff ms"
differ from those of AT&T
.I ms .
.
Documents that depend upon implementation details of AT&T
.I ms
may not format properly with
.I "groff ms" .
.
Such details include macros whose function was not documented in the
AT&T
.I ms
manual [Lesk 1978].
.\" TODO: Use refer(1).
.\" XXX: We support RT anyway; maybe we should stop?
.
.
.PP
The error-handling policy of
.I "groff ms"
is to detect and report errors,
rather than to ignore them silently.
.
.
.PP
Tenth Edition \" possibly 9th
Research Unix supported
.B P1 /
.B P2
macros to bracket code examples;
.I "groff ms"
does not.
.
.
.PP
.I "groff ms"
does not work in GNU
.I troff 's \" GNU
AT&T compatibility mode.
.
If loaded when that mode is enabled,
it aborts processing with a diagnostic message.
.
.
.PP
Multiple line spacing is not supported.
.
Use a larger vertical spacing instead.
.
.
.PP
.I "groff ms"
uses the same header and footer defaults in both
.CW nroff
and
.CW troff
modes
as AT&T
.I ms
does in
.CW troff
mode;
AT&T's default in
.CW nroff
mode is to put the date,
in U.S.\& traditional format
(e.g.,
\[lq]January 1, 2021\[rq]),
in the center footer
(the
.CW CF
string).
.
.
.PP
Many
.I "groff ms"
macros,
including those for paragraphs,
headings,
and displays,
cause a reset of formatting parameters,
and may change the indentation;
they do so not by incrementing or decrementing it,
but by setting it absolutely.
.
This can cause problems for documents that define additional macros of
their own that try to manipulate indentation.
.
Use
.CW .RS
and
.CW .RE
instead of the
.CW in
request.
.
.
.PP
AT&T
.I ms
interpreted the values of the registers
.CW PS
and
.CW VS
in points,
and did not support the use of scaling units with them.
.
.I "groff ms"
interprets values of the registers
.CW PS ,
.CW VS ,
.CW FPS ,
and
.CW FVS
equal to or larger than\~1,000
(one thousand)
as decimal fractions multiplied by\~1,000.\**
.FS
Register values are converted to and stored as basic units.
.
See \[lq]Measurements\[rq] in the
.I groff
Texinfo manual or in
.I groff (7).
.FE
.
This threshold makes use of a scaling unit with these parameters
practical for high-resolution devices while preserving backward
compatibility.
.
It also permits expression of non-integral type sizes.
.
For example,
.CW "groff \-rPS=10.5p" \[rq] \[lq]
at the shell prompt is equivalent to placing
.CW ".nr PS 10.5p" \[rq] \[lq]
at the beginning of the document.
.
.
.PP
AT&T
.I ms 's
.CW AU
macro supported arguments used with some document types;
.I "groff ms"
does not.
.
.
.PP
Right-aligned displays are available.
.
The AT&T
.I ms
manual observes that \[lq]it is tempting to assume that
.CW ".DS R"
will right adjust lines,
but it doesn't work\[rq].
.
In
.I "groff ms" ,
it does.
.
.
.PP
To make
.I "groff ms"
use the default page offset
(which also specifies the left margin),
the
.B PO
register must stay undefined until the first
.I ms
macro is called.
.
This implies that
.B \[rs]n[PO]
should not be used early in the document,
unless it is changed also:
accessing an undefined register automatically defines it.
.
.
.PP
.I "groff ms"
supports the
.CW PN
register,
but it is not necessary;
you can access the page number via the usual
.CW %
register and invoke the
.CW af
request to assign a different format to it if desired.\**
.FS
If you redefine the
.I ms
.CW PT
macro \" I wouldn't mention that, but Lesk 1978 encourages doing so. :-/
and desire special treatment of certain page numbers
(like
.CW 1 \[rq]), \[lq]
you may need to handle a non-Arabic page number format,
as
.I "groff ms" 's
.CW .PT
does;
see the macro package source.
.
.I "groff ms"
aliases the
.CW PN
register to
.CW % .
.FE
.
.
.PP
The AT&T
.I ms
manual documents registers
.CW CW
and
.CW GW
as setting the default column width and \[lq]intercolumn gap\[rq],
respectively,
and which applied when
.CW .MC
was called with fewer than two arguments.
.
.I "groff ms"
instead treats
.CW .MC
without arguments as synonymous with
.CW .2C ;
there is thus no occasion for a default column width register.
.
Further,
the
.CW MINGW
register
and the second argument to
.CW .MC
specify a
.I minimum
space between columns,
not the fixed gutter width of AT&T
.I ms .
.
.
.PP
The AT&T
.I ms
manual did not document the
.CW QI
register;
Berkeley and
.I "groff ms"
do.
.
.
.PP
The register
.CW GS
is set to\~1 by the
.I "groff ms"
macros,
but is not used by the AT&T
.I ms
package.
.
Documents that need to determine whether they are being formatted with
.I "groff ms"
or another implementation should test this register.
.
.
.\" XXX: We can't use a keep here because the wrong page number will be
.\" recorded in the table of contents; see Savannah #63159.
.\"KS
.br
.ne 6v
.NH 2
Unix Version\~7
.BI ms
macros not implemented by
.BI "groff ms"
.XS
	Unix Version 7
.I ms
macros not implemented by
.I "groff ms"
.XE
.LP
Several macros described in the Unix Version\~7
.I ms
documentation are unimplemented by
.I "groff ms"
because they are specific to the requirements of documents produced
internally by Bell Laboratories,
some of which also require a glyph for the Bell System logo that
.I groff
does not support.
.
These macros implemented several document type formats
(\c
.CW EG , \" engineer's notes
.CW IM , \" internal memorandum
.CW MF , \" memorandum for file
.CW MR , \" memorandum for record
.CW TM , \" technical memorandum
.CW TR ), \" technical report
were meaningful only in conjunction with the use of certain document
types
(\c
.CW AT , \" attachments
.CW CS , \" cover sheet info for `TM` documents
.CW CT , \" copies to
.CW OK , \" "other keywords" for `TM` documents
.CW SG ), \" signatures for `TM` documents
stored the postal addresses of Bell Labs sites
(\c
.CW HO , \" Holmdel
.CW IH , \" Naperville
.CW MH , \" Murray Hill
.CW PY , \" Piscataway
.CW WH ), \" Whippany
or lacked a stable definition over time
(\c
.CW UX ). \" Unix; on 1st use, add footnote identifying trademark owner
.
To compatibly render historical
.I ms
documents using these macros,
we advise your documents to invoke the
.CW rm
request to remove any such macros it uses and then define replacements
with an authentically typeset original at hand.\**
.FS
The removal beforehand is necessary because
.I "groff ms"
aliases these macros to a diagnostic macro,
and you want to redefine the aliased name,
not its target.
.FE
.
For informal purposes,
a simple definition of
.CW UX
should maintain the readability of the document's substance.
.
.
.TS
box center;
lf(CR).
\&.rm UX
\&.ds UX Unix\[rs]"
.TE
.rs \" XXX: Work around Savannah #64005.
.\"KE
.
.
.\" ------------------------
.if t \{\
.  br
.  bp
.\}
.NH 1
Legacy features
.XS
Legacy features
.XE
.
.
.LP
.I "groff ms"
retains some legacy features solely to support formatting of historical
documents;
contemporary ones should not use them because they can render poorly.
.
See
.I groff_char (7)
instead.
.
.
.KS
.NH 2
AT&T
.I ms
accent mark strings
.XS
	AT&T
.I ms
accent mark strings
.XE
.LP
AT&T
.I ms
defined
accent mark strings as follows.
.
.
.TS
box center;
Cb Lb
Lf(CR) Lx.
String	Description
_
\[rs]*[\[aq]]	Apply acute accent to subsequent glyph.
\[rs]*[\[ga]]	Apply grave accent to subsequent glyph.
\[rs]*[:]	Apply dieresis (umlaut) to subsequent glyph.
\[rs]*[\[ha]]	Apply circumflex accent to subsequent glyph.
\[rs]*[\[ti]]	Apply tilde accent to subsequent glyph.
\[rs]*[C]	Apply caron to subsequent glyph.
.\" \*v was an undocumented (in Lesk 1978-11-13) synonym for \*C.
\[rs]*[,]	Apply cedilla to subsequent glyph.
.TE
.KE
.
.
.NH 2
Berkeley
.I ms
accent mark and glyph strings
.XS
	Berkeley
.I ms
accent mark and glyph strings
.XE
.LP
Berkeley
.I ms
offered an
.CW AM
macro;
calling it redefined the AT&T accent mark strings
(except for
.CW \[rs]*C ),
applied them to the
.I preceding
glyph,
and defined additional strings,
some for spacing glyphs.
.
.
.TS
box;
cb cb
lf(CR) lx .
Macro	Description
_
\&.AM	Enable alternative accent mark and glyph-producing strings.
.TE
.
.
.TS
box center;
Cb Lb
Lf(CR) Lx.
String	Description
_
\[rs]*[\[aq]]	Apply acute accent to preceding glyph.
\[rs]*[\[ga]]	Apply grave accent to preceding glyph.
\[rs]*[:]	Apply dieresis (umlaut) to preceding glyph.
\[rs]*[\[ha]]	Apply circumflex accent to preceding glyph.
\[rs]*[\[ti]]	Apply tilde accent to preceding glyph.
\[rs]*[,]	Apply cedilla to preceding glyph.
\[rs]*[/]	Apply stroke (slash) to preceding glyph.
\[rs]*[v]	Apply caron to preceding glyph.
\[rs]*[_]	Apply macron to preceding glyph.
\[rs]*[.]	Apply underdot to preceding glyph.
\[rs]*[o]	Apply ring accent to preceding glyph.
_
\[rs]*[?]	Interpolate inverted question mark.
\[rs]*[!]	Interpolate inverted exclamation mark.
\[rs]*[8]	Interpolate small letter sharp s.
\[rs]*[q]	Interpolate small letter o with hook accent (ogonek).
\[rs]*[3]	Interpolate small letter yogh.
\[rs]*[d-]	Interpolate small letter eth.
\[rs]*[D-]	Interpolate capital letter eth.
\[rs]*[th]	Interpolate small letter thorn.
\[rs]*[TH]	Interpolate capital letter thorn.
\[rs]*[ae]	Interpolate small ae ligature.
\[rs]*[AE]	Interpolate capital ae ligature.
\[rs]*[oe]	Interpolate small oe ligature.
\[rs]*[OE]	Interpolate capital oe ligature.
.TE
.rs \" XXX: Work around Savannah #64005.
.
.
.\" ------------------------
.if t \{\
.  br
.  bp
.\}
.NH 1
Further reading
.XS
Further reading
.XE
.
.
.XP
\[lq]Typing Documents on the Unix System:
Using the \-ms Macros with Troff and Nroff\[rq];
M.\& E.\& Lesk;
November 13, 1978.
.
This document describes the
.I ms
supplied with AT&T Unix Version\~7.
.
.
.XP
\[lq]A Revised Version of \-ms\[rq];
Bill Tuthill;
August 1983.
.
The 4.2BSD release featured several extensions to
.I ms ,
most of which are recreated in
.I "groff ms" .
.
(The exceptions are the
.CW TM
and
.CW CT
macros for setting a doctoral thesis in the format required by the
contemporaneous degree-granting authorities of the University of
California at Berkeley.)
.
.
.XP
\[lq]Using PDF boxes with
.I groff
and the
.I ms
macros\[rq];
Deri James;
March 2021.
.
.CW BOXSTART
and
.CW BOXSTOP
macros are available via the
.I sboxes
extension package,
enabling colored,
bordered boxes when the
.CW pdf
output device is used.
.
This document is distributed with
.I groff
as the file
.I msboxes.pdf .
.
.
.LP
This manual was composed using
.I "groff ms" ;
the curious may consult its source in the file
.I ms.ms
to see how its formatting was achieved.
.\" ------------------------
.TC
.
.
.\" Local Variables:
.\" fill-column: 72
.\" mode: nroff
.\" End:
.\" vim: set filetype=groff textwidth=72: