mirror of
https://https.git.savannah.gnu.org/git/groff.git
synced 2026-01-26 07:37:53 +00:00
4646 lines
76 KiB
Plaintext
4646 lines
76 KiB
Plaintext
.\" groff -ept -ms
|
|
.\" nroff -t -rLL=$(stty size | cut -f2 -d' ')n -ms
|
|
.\"
|
|
.\" Copyright 2001 Larry Kollar
|
|
.\" Copyright 2020-2025 G. Branden Robinson
|
|
.\"
|
|
.\" This file is part of groff, the GNU roff typesetting system.
|
|
.\"
|
|
.\" 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
|
|
. if \n[LL]<74n \{\
|
|
. tm \n[.F]: This document needs at least 74 columns to render.
|
|
. tm \n[.F]: Consult the comment header of the file for advice.
|
|
. ab
|
|
. \}
|
|
.\}
|
|
.\" This document doesn't require the minus sign (in Times) but we do
|
|
.\" want a copy- and-pastable hyphen-minus.
|
|
.char \- \N'45'
|
|
.\" A very limited output device might not have a dagger glyph.
|
|
.\" Pick a fallback that isn't confusable with an asterisk.
|
|
.fchar \[dg] +
|
|
.nr PS 11
|
|
.nr VS 13
|
|
.ds FR 1
|
|
.nr TC-MARGIN \w'00' \" expect 2-digit page numbers at most
|
|
.ds header-title Using \f[I]groff\f[] with the \f[I]ms\f[] macros\"
|
|
.ds date November 2025\"
|
|
.ND \*[date]
|
|
.ds CH \" empty
|
|
.ie t \{\
|
|
. nr PI 3.5n
|
|
. EH '%''\*[date]'
|
|
. OH '\*[header-title]''%'
|
|
.\}
|
|
.el \{\
|
|
. nr PI 4n
|
|
. ds LH \*[date]\"
|
|
. ds CH \*[header-title]\"
|
|
. ds RH \\n[%]\"
|
|
.\}
|
|
.ds CF groff @VERSION@\"
|
|
.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
|
|
Use the
|
|
.I ms
|
|
(\[lq]manuscript\[rq]) package to compose
|
|
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 consistently formatted bibliographic citations.
|
|
.
|
|
.I "groff ms"
|
|
is mostly compatible with the documented interface
|
|
and behavior of AT&T Unix Version\~7
|
|
.I ms .
|
|
.
|
|
It recreates most extensions from 4.2BSD (Berkeley)
|
|
.\" Few changes were made in 4.3, Tahoe, Reno, or 4.4.
|
|
and Research Tenth Edition Unix.
|
|
.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
|
|
.
|
|
Whereas
|
|
.I man
|
|
suits brief references,
|
|
.I ms
|
|
can handle long or complex works
|
|
intended for printing and possible publication.
|
|
.
|
|
.
|
|
.PP
|
|
In this document,
|
|
a right arrow (\[->]) indicates a tab character in the input.
|
|
.
|
|
Macro,
|
|
register,
|
|
and string descriptions frequently mention each other;
|
|
most references are to macros.
|
|
.
|
|
Where a register or string is referenced,
|
|
we annotate its type.
|
|
.
|
|
.I ms 's
|
|
identifiers use only capital letters,
|
|
numerals,
|
|
and
|
|
.CW \- \[rq]. \[lq]
|
|
.
|
|
.
|
|
.KS
|
|
.NH 2
|
|
Basic information
|
|
.XS
|
|
Basic information
|
|
.XE
|
|
.
|
|
.
|
|
.LP
|
|
Prepare an
|
|
.I ms
|
|
document with your preferred text editor.
|
|
.
|
|
Call an
|
|
.I ms
|
|
macro early in the document to initialize the package.
|
|
.
|
|
A
|
|
.I macro
|
|
is a formatting instruction to
|
|
.I ms.
|
|
.
|
|
Put a macro call on a line by itself with a dot before its name.
|
|
.
|
|
Use
|
|
.CW PP
|
|
if you want your paragraph's first line indented,
|
|
or
|
|
.CW LP
|
|
if you don't.
|
|
.
|
|
Then type text 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.
|
|
.KE
|
|
.
|
|
.
|
|
.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, nano, .\|.\|.
|
|
$ 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 inch (\[sd])
|
|
c centimeter
|
|
p point (1/72\[sd])
|
|
P pica (1/6\[sd])
|
|
v \[lq]vee\[rq]; current vertical spacing
|
|
m \[lq]em\[rq]; width of an \[lq]M\[rq] in the current font
|
|
n \[lq]en\[rq]; one-half em (same as \f[CR]m\f[] on terminals)
|
|
.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 almost anywhere,
|
|
.\" ...but not where GNU troff expects an escape function selector or
|
|
.\" delimiter.
|
|
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]n\f[I]r T{
|
|
abbreviation of
|
|
.CW \[rs]n[\f[I]r\f[]] ;
|
|
the name
|
|
.I r
|
|
must be only one character
|
|
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
|
|
Document structure
|
|
.XS
|
|
Document structure
|
|
.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.
|
|
.
|
|
Organize longer documents 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.
|
|
.
|
|
A macro call at the end of the document emits the collected entries.
|
|
.
|
|
This material necessarily follows the rest of the text since GNU
|
|
.I troff \" GNU
|
|
is a single-pass formatter;
|
|
it 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
|
|
We present the document parameters below
|
|
in the syntax used to interpolate their contents.
|
|
.
|
|
For any unsatisfactory default,
|
|
define its register,
|
|
string,
|
|
or special character before calling any
|
|
.I ms
|
|
macro other than
|
|
.CW RP .
|
|
.
|
|
.\" Improve a column heading if we have the elbow room.
|
|
.ds Next \" empty
|
|
.if t .ds Next " Next\|.\|.\|.\"
|
|
.if n .if \n[LL]>81n .ds Next " Next...\"
|
|
The \[lq]Effective\*[Next]\[rq] heading indicates
|
|
that changes to the parameter
|
|
take effect at the next element of the listed type
|
|
.I ms
|
|
processes.
|
|
.
|
|
For entries marked
|
|
.I special ,
|
|
see discussion in the applicable section.
|
|
.
|
|
.if t \{\
|
|
. nr saved-DD \n[DD]
|
|
. nr DD 0
|
|
. sp 0.5v
|
|
. vs -.095625v
|
|
.\}
|
|
.TS H
|
|
box;
|
|
Cb Cb Cb Cb
|
|
Cbp-1 S S S
|
|
Lf(CR)p-1 Lx L Lf(CR)p-1.
|
|
Parameter Definition Effective\*[Next] Default
|
|
_
|
|
.TH
|
|
Margins
|
|
\[rs]n[PO] Page offset (left margin) page\
|
|
1i \f[R](\f[]0\f[R])\*{*\*}
|
|
\[rs]n[LL] Line length paragraph\
|
|
6.5i \f[R](\f[]65n\f[R])\*{*\*}
|
|
\[rs]n[LT] Title line length paragraph\
|
|
6.5i \f[R](\f[]65n\f[R])\*{*\*}
|
|
\[rs]n[HM] Top (header) margin page 1i
|
|
\[rs]n[FM] Bottom (footer) margin page 1i
|
|
_
|
|
.T&
|
|
Cbp-1 S S S
|
|
Lf(CR)p-1 Lx L Lf(CR)p-1.
|
|
Titles (headers, footers)
|
|
\[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
|
|
_
|
|
.T&
|
|
Cbp-1 S S S
|
|
Lf(CR)p-1 Lx L Lf(CR)p-1.
|
|
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
|
|
_
|
|
.T&
|
|
Cbp-1 S S S
|
|
Lf(CR)p-1 Lx L Lf(CR)p-1.
|
|
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
|
|
_
|
|
.T&
|
|
Cbp-1 S S S
|
|
Lf(CR)p-1 Lx L Lf(CR)p-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]
|
|
_
|
|
.T&
|
|
Cbp-1 S S S
|
|
Lf(CR)p-1 Lx L Lf(CR)p-1.
|
|
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
|
|
_
|
|
.T&
|
|
Cbp-1 S S S
|
|
Lf(CR)p-1 Lx L Lf(CR)p-1.
|
|
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
|
|
_
|
|
.T&
|
|
Cbp-1 S S S
|
|
Lf(CR)p-1 Lx L Lf(CR)p-1.
|
|
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
|
|
.if t \{\
|
|
. rs
|
|
. nr DD \n[saved-DD]
|
|
. rr saved-DD
|
|
. vs
|
|
.\}
|
|
.rm Next
|
|
.
|
|
.
|
|
.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.
|
|
.
|
|
.
|
|
.\" ------------------------
|
|
.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.
|
|
.
|
|
.
|
|
.if n \{
|
|
. br
|
|
. ne 12v
|
|
.\}
|
|
.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.
|
|
.
|
|
.I ms
|
|
recognizes
|
|
.CW no
|
|
as a synonym of
|
|
.CW no\-\:\%repeat\-\:\%info
|
|
to maintain AT&T compatibility.
|
|
.
|
|
Options other than
|
|
.CW no
|
|
are GNU extensions.
|
|
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 institutional affiliation.
|
|
.
|
|
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 terminals.
|
|
.
|
|
Set these parameters before the first call of a heading,
|
|
paragraphing,
|
|
or (non-date) document description macro to apply 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\~
|
|
disables automatic hyphenation.
|
|
.
|
|
This is a Research Tenth Edition 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.
|
|
.
|
|
These calls insert 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 starts close to the bottom of a page,
|
|
and there is insufficient space to accommodate
|
|
.CW \[rs]n[PORPHANS]
|
|
lines before an automatic page break,
|
|
.I "groff ms"
|
|
forces a page break before formatting the paragraph.
|
|
.
|
|
This is a GNU extension.
|
|
.
|
|
.
|
|
.TS H
|
|
box;
|
|
lb lb
|
|
lf(CR) lx.
|
|
Macro Description
|
|
_
|
|
.TH
|
|
\&.LP T{
|
|
Set a paragraph without (additional) indentation.
|
|
T}
|
|
_
|
|
\&.PP T{
|
|
Set a paragraph with a first-line left indentation of
|
|
.CW \[rs]n[PI] .
|
|
T}
|
|
_
|
|
\&.IP \f[R][\f[I]mark\f[] [\f[I]width\f[]]] T{
|
|
Set a paragraph with a left indentation.
|
|
.
|
|
The optional
|
|
.I mark
|
|
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,
|
|
and
|
|
.CW SN\-STYLE ,
|
|
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 .
|
|
.
|
|
.CW GROWPS
|
|
and
|
|
.CW PSINCR
|
|
are GNU extensions.
|
|
.
|
|
.
|
|
The input
|
|
.
|
|
.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
|
|
causes \[lq]1. Carnivora\[rq] to be printed in 13-point type,
|
|
followed by \[lq]1.1. Felinae\[rq] in 11.5-point type,
|
|
while \[lq]1.1.1. Felis catus\[rq] and all more deeply nested headings
|
|
remain in the 10-point type specified by the
|
|
.CW PS
|
|
register.
|
|
.
|
|
\[lq]Machairodontinae\[rq] is printed at 11.5 points,
|
|
since it corresponds to heading depth\~2.
|
|
.
|
|
.
|
|
.PP
|
|
In
|
|
.I "groff ms,"
|
|
the
|
|
.CW NH
|
|
and
|
|
.CW SH
|
|
macros consult the
|
|
.CW HORPHANS
|
|
register to prevent the output 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,
|
|
.I "groff ms"
|
|
forces a page break before setting the heading.
|
|
.
|
|
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.
|
|
.
|
|
This is a GNU extension.
|
|
.
|
|
.
|
|
.\" 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 Sixth Edition 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 Research Tenth Edition 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 Research Tenth Edition 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 terminals,
|
|
reverse video or another means of highlighting is used instead.
|
|
.
|
|
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 .
|
|
.
|
|
On terminals,
|
|
.I text
|
|
is bracketed with underscores (\[lq]_\[rq]).
|
|
.
|
|
.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.
|
|
.
|
|
Call
|
|
.LG
|
|
the macro
|
|
.LG
|
|
multiple times
|
|
.NL
|
|
to enlarge the type size further.
|
|
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.
|
|
.
|
|
Call
|
|
.SM
|
|
the macro
|
|
.SM
|
|
multiple times
|
|
.NL
|
|
to reduce the type size further.
|
|
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
|
|
.
|
|
.
|
|
.NH 2
|
|
Lists
|
|
.XS
|
|
Lists
|
|
.XE
|
|
.
|
|
.
|
|
.LP
|
|
The
|
|
.I mark
|
|
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.
|
|
.
|
|
.
|
|
.\" We assume Times roman font metrics for these examples.
|
|
.if t .ds gwidth 0.4i
|
|
.if n .ds gwidth 0.5i
|
|
.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 \*[gwidth]
|
|
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 \*[gwidth]
|
|
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 created a register
|
|
.CW step
|
|
with the
|
|
.CW nr
|
|
request,
|
|
initializing it to zero and setting its auto-increment to 1.
|
|
.
|
|
Each time we use the escape sequence
|
|
.CW \[rs]n+[step]
|
|
(note the plus sign),
|
|
the formatter applies the increment just before interpolating the
|
|
register's value.
|
|
.
|
|
.
|
|
.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 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 mark with the
|
|
.CW \[rs]h
|
|
escape sequence;
|
|
using the same amount as the indentation ensures that the mark 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]\*[gwidth]\[aq]
|
|
Firearms,
|
|
.fi
|
|
T}
|
|
_
|
|
.T&
|
|
cb s s
|
|
l s s.
|
|
Result
|
|
_
|
|
T{
|
|
A glossary-style list:
|
|
.
|
|
.IP lawyers \*[gwidth]
|
|
Two or more attorneys.
|
|
.IP guns\h'\*[gwidth]' \*[gwidth]
|
|
Firearms,
|
|
preferably large-caliber.
|
|
.IP money
|
|
Gotta pay for those lawyers and guns!
|
|
T}
|
|
.TE
|
|
.
|
|
.
|
|
.PP
|
|
If you need a measurement more than once,
|
|
you can store the measured width of text in a register.
|
|
.
|
|
.
|
|
.TS
|
|
box center;
|
|
lf(CR).
|
|
\&.nr width \[rs]w\[aq]guns\[aq]
|
|
\&.IP guns\[rs]h\[aq]\[rs]n[width]\[aq]
|
|
.TE
|
|
.
|
|
.
|
|
.NH 2
|
|
Indented regions
|
|
.XS
|
|
Indented regions
|
|
.XE
|
|
.
|
|
.
|
|
.LP
|
|
You can indent a region of text while otherwise formatting it normally.
|
|
.
|
|
Such indented regions can be nested;
|
|
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 it,
|
|
allowing material following the keep
|
|
(in the source document)
|
|
to fill the remainder of the current page.
|
|
.
|
|
When the page breaks by reaching its bottom or by
|
|
.CW bp
|
|
request,
|
|
.I ms
|
|
puts the floating keep at the beginning of the next page.
|
|
.
|
|
Use floating keeps to house 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;
|
|
to box words within a line,
|
|
recall
|
|
.CW BX
|
|
in section \[lq]Typeface and decoration\[rq] above.
|
|
.
|
|
.I ms
|
|
draws box lines close to the text they enclose
|
|
so that they are usable within paragraphs.
|
|
.
|
|
When boxing entire paragraphs thus,
|
|
you may improve their appearance by calling
|
|
.CW B1
|
|
after the first paragraphing macro,
|
|
and invoking the
|
|
.CW sp
|
|
request 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,
|
|
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
|
|
.I "groff ms"
|
|
inserts the distance stored in
|
|
.CW \[rs]n[DD]
|
|
before and after each pair of display macros;
|
|
this is a Berkeley extension.
|
|
.
|
|
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.
|
|
.
|
|
.
|
|
.PP
|
|
The display distance applies even in footnotes
|
|
(discussed below),
|
|
which may cause a footnote with a display at its end to
|
|
\[lq]emptily\[rq] spill to the next page.
|
|
.
|
|
Consider the following tactic to compensate.
|
|
.
|
|
.
|
|
.TS
|
|
box center;
|
|
lf(CR).
|
|
\&.FS
|
|
Recall the ideal gas law.
|
|
\&.nr DD-saved \[rs]n[DD] \[rs]" stash display distance
|
|
\&.nr DD 0 \[rs]" eliminate automatic space around display
|
|
\&.sp \[rs]n[DD-saved]u \[rs]" manually put space before it
|
|
\&.EQ
|
|
P V = n R T
|
|
\&.EN
|
|
\&.FE
|
|
\&.nr DD \[rs]n[DD-saved] \[rs]" restore previous setting
|
|
.TE
|
|
.
|
|
.
|
|
.KS
|
|
.NH 2
|
|
Tables, figures, equations, and references
|
|
.XS
|
|
Tables, figures, equations, and references
|
|
.XE
|
|
.LP
|
|
.I ms
|
|
often sees use with the
|
|
.I tbl ,
|
|
.I pic ,
|
|
.I eqn ,
|
|
and
|
|
.I refer
|
|
preprocessors.
|
|
.
|
|
.I "groff ms"
|
|
applies the
|
|
.CW \[rs]n[DD]
|
|
distance 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.
|
|
.
|
|
Preprocessors match these tokens only at the start of an input line.
|
|
.
|
|
.I troff
|
|
interprets them as macro calls.
|
|
.
|
|
.
|
|
.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
|
|
.I "h v"
|
|
.br
|
|
\&.PE
|
|
.br
|
|
\&.PF
|
|
T} T{
|
|
.CW .PS
|
|
marks the start of a
|
|
.I pic (1)
|
|
preprocessor
|
|
diagram;
|
|
either of
|
|
.CW PE
|
|
or
|
|
.CW PF
|
|
ends it,
|
|
the latter with \[lq]flyback\[rq] to the vertical position at its top.
|
|
.
|
|
Create
|
|
.I pic
|
|
input manually or with a program such as
|
|
.I xfig (1).
|
|
.
|
|
.I h
|
|
and
|
|
.I v
|
|
are the horizontal and vertical dimensions of the picture;
|
|
.I pic
|
|
supplies them automatically.
|
|
T}
|
|
_
|
|
T{
|
|
\&.EQ
|
|
.R
|
|
.I align \~[\c [
|
|
.I label ]]
|
|
.CW
|
|
.br
|
|
\&.EN
|
|
T} T{
|
|
Demarcate mathematics to be processed by the
|
|
.I eqn
|
|
preprocessor.
|
|
.
|
|
.I ms
|
|
centers the equation 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.
|
|
.
|
|
.I ms
|
|
right-aligns any
|
|
.I label .
|
|
.
|
|
See
|
|
.I eqn (1).
|
|
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.
|
|
.
|
|
.
|
|
.ie t \{\
|
|
.EQ C (\*[SN-NO-DOT]a)
|
|
p ~ = ~ q sqrt { 1 + ~ ( x / q sup 2 ) }
|
|
.EN
|
|
.\}
|
|
.el \{
|
|
.ce
|
|
.B "[Equation not rendered on terminal output device.]"
|
|
.\}
|
|
.
|
|
.
|
|
.PP
|
|
Create diagrams with
|
|
.I pic .
|
|
.
|
|
.
|
|
.TS
|
|
box center;
|
|
Lf(CR).
|
|
\&.PS
|
|
circle "input";
|
|
arrow;
|
|
box width 1.5i "\[rs]f[CR]groff \-Rept \-ms\[rs]f[]";
|
|
arrow;
|
|
circle "output";
|
|
\&.PE
|
|
.TE
|
|
.
|
|
.
|
|
.ie t \{\
|
|
.PS
|
|
circle "input";
|
|
arrow;
|
|
box width 1.5i "\f[CR]groff \-Rept \-ms\f[]";
|
|
arrow;
|
|
circle "output";
|
|
.PE
|
|
.\}
|
|
.el \{
|
|
.ce
|
|
.B "[Picture not rendered on terminal output device.]"
|
|
.\}
|
|
.
|
|
.
|
|
.PP
|
|
.I groff
|
|
options
|
|
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 mark,
|
|
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 mark,
|
|
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]mark\f[]] T{
|
|
Begin a footnote.
|
|
.
|
|
The
|
|
.CW FS\-MARK
|
|
hook
|
|
(see below)
|
|
is called with any supplied
|
|
.I mark
|
|
argument,
|
|
which is then also placed at the beginning of the footnote text.
|
|
.
|
|
If
|
|
.I mark
|
|
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 mark 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 mark 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.
|
|
.
|
|
By default,
|
|
this macro has an empty definition.
|
|
.
|
|
.CW FS\-MARK
|
|
is a GNU extension.
|
|
.
|
|
.
|
|
.KS
|
|
.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 mark,
|
|
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
|
|
.KE
|
|
.
|
|
.
|
|
.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 mark
|
|
argument,
|
|
at the bottom of a column or page as follows.
|
|
.
|
|
This is a Berkeley extension.
|
|
.
|
|
.
|
|
.TS
|
|
box;
|
|
cb cb
|
|
lf(CR) lx .
|
|
\f[CB]FF\f[] value Description
|
|
_
|
|
0 T{
|
|
Set an automatic number as a superscript
|
|
(on typesetters)
|
|
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
|
|
.I mark
|
|
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
|
|
.I mark
|
|
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, ru, es, sv
|
|
Czech,
|
|
German,
|
|
French,
|
|
Italian,
|
|
Russian,
|
|
Spanish,
|
|
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.\**
|
|
.FS
|
|
.CW \[dq] ,
|
|
.CW # ,
|
|
and
|
|
.CW $
|
|
are also good choices because
|
|
.I groff
|
|
handles delimiters in other contexts
|
|
such as conditional and numeric expressions,
|
|
where digits
|
|
.CW 0 \[en]\c
|
|
.CW 9
|
|
and punctuation characters like
|
|
.CW + ,
|
|
.CW \- ,
|
|
.CW * ,
|
|
.CW / ,
|
|
.CW & ,
|
|
and
|
|
.CW :
|
|
are meaningful.
|
|
.FE
|
|
.
|
|
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
|
|
.CW pdfswitchtopage
|
|
macro,
|
|
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
|
|
.
|
|
.
|
|
.ne 8v
|
|
.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
|
|
.
|
|
.
|
|
.ne 8v
|
|
.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 historical
|
|
.BI ms
|
|
.XS
|
|
Differences from historical
|
|
.I ms
|
|
.XE
|
|
.LP
|
|
.I "groff ms"
|
|
was written without reusing AT&T or Berkeley code.
|
|
.
|
|
Since it takes advantage of
|
|
GNU
|
|
.I troff 's
|
|
extensions,
|
|
it cannot be used with AT&T
|
|
.I troff .
|
|
.
|
|
.I "groff ms"
|
|
supports features described above as Berkeley and
|
|
Research Tenth Edition Unix extensions,
|
|
and adds several of its own.
|
|
.
|
|
.
|
|
.PP
|
|
The internals of
|
|
.I "groff ms"
|
|
differ from those of AT&T and Berkeley
|
|
.I ms .
|
|
.
|
|
Documents that depend upon undocumented behavioral details of
|
|
those implementations
|
|
might not format as expected with
|
|
.I "groff ms" .
|
|
.
|
|
It therefore defines the register
|
|
.CW GS ,
|
|
which AT&T and Berkeley do not use,
|
|
to\~1.
|
|
.
|
|
A document can test its value to determine whether it is being formatted
|
|
with
|
|
.I "groff ms"
|
|
or another implementation.
|
|
.
|
|
.
|
|
.PP
|
|
The error-handling policy of
|
|
.I "groff ms"
|
|
is to detect and report errors,
|
|
rather than to ignore them silently.
|
|
.
|
|
.
|
|
.PP
|
|
Research Tenth Edition \" possibly 9th
|
|
Unix supported
|
|
.CW P1 /\c
|
|
.CW 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 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.
|
|
.\" Note to document maintainers:
|
|
.\"
|
|
.\" We use the scaling unit `p` instead of the typographical point `z`
|
|
.\" because this is a register assignment; the value gets converted to
|
|
.\" scaled points automatically.
|
|
.\" Observe:
|
|
.\" $ printf '.nr PS 10.5p\n.pnr PS\n' | groff # 1.24 or later
|
|
.\" PS 10500 +0 0
|
|
.\"
|
|
.\" groff ms users can thus remain innocent of the z unit if they like.
|
|
.
|
|
.
|
|
.PP
|
|
AT&T
|
|
.I ms 's
|
|
.CW AU
|
|
macro supported arguments
|
|
whose values were used with some
|
|
.CW RP "" non-
|
|
document types;
|
|
that of
|
|
.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
|
|
.CW PO
|
|
register must stay undefined until the first
|
|
.I ms
|
|
macro is called.
|
|
.
|
|
This implies that
|
|
.CW \[rs]n[PO]
|
|
should not be used early in the document,
|
|
unless it is changed also:
|
|
interpolating 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.
|
|
.
|
|
.
|
|
.\" 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:
|