1557 lines
27 KiB
Groff
1557 lines
27 KiB
Groff
'\" t
|
|
.ig
|
|
Copyright (C) 1989-1995, 2001, 2002, 2003, 2004, 2005
|
|
Free Software Foundation, Inc.
|
|
|
|
Permission is granted to make and distribute verbatim copies of
|
|
this manual provided the copyright notice and this permission notice
|
|
are preserved on all copies.
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided that the
|
|
entire resulting derived work is distributed under the terms of a
|
|
permission notice identical to this one.
|
|
|
|
Permission is granted to copy and distribute translations of this
|
|
manual into another language, under the above conditions for modified
|
|
versions, except that this permission notice may be included in
|
|
translations approved by the Free Software Foundation instead of in
|
|
the original English.
|
|
..
|
|
.
|
|
.do nr groff_ms_C \n[.C]
|
|
.cp 0
|
|
.
|
|
.TH GROFF_MS @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
|
|
.
|
|
.
|
|
.
|
|
.SH NAME
|
|
.
|
|
groff_ms \- groff ms macros
|
|
.
|
|
.
|
|
.
|
|
.SH SYNOPSIS
|
|
.
|
|
.B groff
|
|
.B \-ms
|
|
[
|
|
.IR options .\|.\|.\&
|
|
]
|
|
[
|
|
.IR files .\|.\|.\&
|
|
]
|
|
.br
|
|
.B groff
|
|
.B \-m\ ms
|
|
[
|
|
.IR options .\|.\|.\&
|
|
]
|
|
[
|
|
.IR files .\|.\|.\&
|
|
]
|
|
.
|
|
.
|
|
.
|
|
.SH DESCRIPTION
|
|
.
|
|
This manual page describes the GNU version of the
|
|
.I ms
|
|
macros,
|
|
part of the
|
|
.I groff
|
|
typesetting system.
|
|
The
|
|
.I ms
|
|
macros are mostly compatible with the
|
|
documented behavior of the 4.3
|
|
.SM BSD
|
|
Unix
|
|
.I ms
|
|
macros (see
|
|
.I Differences from troff ms
|
|
below for details).
|
|
The
|
|
.I ms
|
|
macros are suitable for reports, letters, books, and
|
|
technical documentation.
|
|
.
|
|
.
|
|
.
|
|
.SH USAGE
|
|
.
|
|
The
|
|
.I ms
|
|
macro package expects files to have
|
|
a certain amount of structure.
|
|
The simplest documents can begin with a paragraph macro
|
|
and consist of text separated by paragraph macros
|
|
or even blank lines.
|
|
Longer documents have a structure as follows:
|
|
.
|
|
.TP
|
|
.B "Document type"
|
|
If you use the
|
|
.B RP
|
|
(report) macro at the beginning of the document,
|
|
.I groff
|
|
prints the cover page information on its own page;
|
|
otherwise it prints the information on the
|
|
first page with your document text immediately following.
|
|
Other document formats found in AT&T
|
|
.I troff
|
|
are specific to AT&T
|
|
or Berkeley, and are not supported in
|
|
.IR "groff ms" .
|
|
.
|
|
.TP
|
|
.B "Format and layout"
|
|
By setting number registers,
|
|
you can change your document's type (font and size),
|
|
margins, spacing, headers and footers, and footnotes.
|
|
See
|
|
.I "Document control registers"
|
|
below for more details.
|
|
.
|
|
.TP
|
|
.B "Cover page"
|
|
A cover page consists of a title,
|
|
and optionally the author's name and institution,
|
|
an abstract, and the date.
|
|
See
|
|
.I "Cover page macros"
|
|
below for more details.
|
|
.
|
|
.TP
|
|
.B "Body"
|
|
Following the cover page is your document.
|
|
It consists of paragraphs, headings, and lists.
|
|
.
|
|
.TP
|
|
.B "Table of contents"
|
|
Longer documents usually include a table of contents,
|
|
which you can add by placing the
|
|
.B TC
|
|
macro at the end of your document.
|
|
.
|
|
.
|
|
.SS "Document control registers"
|
|
.
|
|
The following table lists the document control
|
|
number registers.
|
|
For the sake of consistency,
|
|
set registers related to margins at the beginning of your document,
|
|
or just after the
|
|
.B RP
|
|
macro.
|
|
.
|
|
.LP
|
|
.ne 12
|
|
.B Margin settings
|
|
.RS
|
|
.na
|
|
.TS
|
|
cb s cb s s cb s cb s
|
|
afCW s l s s l s l s.
|
|
Reg. Definition Effective Default
|
|
_
|
|
PO T{
|
|
Page offset (left margin)
|
|
T} T{
|
|
next page
|
|
T} 1i
|
|
LL T{
|
|
Line length
|
|
T} next para. 6i
|
|
LT T{
|
|
Header/footer length
|
|
T} next para. 6i
|
|
HM T{
|
|
Top (header) margin
|
|
T} next page 1i
|
|
FM T{
|
|
Bottom (footer) margin
|
|
T} next page 1i
|
|
_
|
|
.TE
|
|
.RE
|
|
.
|
|
.LP
|
|
.ne 12
|
|
.B Text settings
|
|
.RS
|
|
.TS
|
|
cb s cb s s cb s cb s
|
|
afCW s l s s l s l s.
|
|
Reg. Definition Effective Default
|
|
_
|
|
PS T{
|
|
Point size
|
|
T} next para. 10p
|
|
VS T{
|
|
Line spacing (leading)
|
|
T} next para. 12p
|
|
PSINCR T{
|
|
Point size increment
|
|
for section headings of
|
|
increasing importance
|
|
T} next heading 1p
|
|
GROWPS T{
|
|
Heading level
|
|
beyond which PSINCR
|
|
is ignored
|
|
T} next heading 0
|
|
_
|
|
.TE
|
|
.RE
|
|
.
|
|
.LP
|
|
.ne 11
|
|
.B Paragraph settings
|
|
.RS
|
|
.TS
|
|
cb cb s cb cb
|
|
afCW l s l l .
|
|
Reg. Definition Effective Default
|
|
_
|
|
PI T{
|
|
Initial indent
|
|
T} next para. 5n
|
|
PD T{
|
|
Space between paragraphs
|
|
T} next para. 0.3v
|
|
QI T{
|
|
Quoted paragraph indent
|
|
T} next para. 5n
|
|
PORPHANS T{
|
|
Number of initial lines
|
|
to be kept together
|
|
T} next para. 1
|
|
HORPHANS T{
|
|
Number of initial lines
|
|
to be kept with heading
|
|
T} next heading 1
|
|
_
|
|
.TE
|
|
.RE
|
|
.
|
|
.LP
|
|
.ne 7
|
|
.B Footnote settings
|
|
.RS
|
|
.TS
|
|
cb cb cb cb
|
|
afCW l l l .
|
|
Reg. Definition Effective Default
|
|
_
|
|
FL Footnote length next footnote \[rs]n[LL]*5/6
|
|
FI Footnote indent next footnote 2n
|
|
FF Footnote format next footnote 0
|
|
FPS Point size next footnote \[rs]n[PS]-2
|
|
FVS Vert. spacing next footnote \[rs]n[FPS]+2
|
|
FPD Para. spacing next footnote \[rs]n[PD]/2
|
|
_
|
|
.TE
|
|
.RE
|
|
.
|
|
.LP
|
|
.ne 6
|
|
.B Other settings
|
|
.RS
|
|
.TS
|
|
cb s cb s s cb s cb s
|
|
afCW s l s s l s l s.
|
|
Reg. Definition Effective Default
|
|
_
|
|
MINGW T{
|
|
Minimum width between columns
|
|
T} next page 2n
|
|
_
|
|
.TE
|
|
.ad
|
|
.RE
|
|
.
|
|
.
|
|
.SS "Cover page macros"
|
|
.
|
|
Use the following macros to create a cover page for your document
|
|
in the order shown.
|
|
.
|
|
.TP
|
|
.B .RP [no]
|
|
Specifies the report format for your document.
|
|
The report format creates a separate cover page.
|
|
With no
|
|
.B RP
|
|
macro,
|
|
.I groff
|
|
prints a subset of the
|
|
cover page on page\~1 of your document.
|
|
.
|
|
.IP
|
|
If you use the optional
|
|
.B no
|
|
argument,
|
|
.I groff
|
|
prints a title page but
|
|
does not repeat any of the title page information
|
|
(title, author, abstract, etc.\&)
|
|
on page\~1 of the document.
|
|
.
|
|
.TP
|
|
.B .P1
|
|
(P-one) Prints the header on page\~1.
|
|
The default is to suppress the header.
|
|
.
|
|
.TP
|
|
.BI ".DA [" xxx ]
|
|
(optional) Print the current date,
|
|
or the arguments to the macro if any,
|
|
on the title page (if specified)
|
|
and in the footers.
|
|
This is the default for
|
|
.IR nroff .
|
|
.
|
|
.TP
|
|
.BI ".ND [" xxx ]
|
|
(optional) Print the current date,
|
|
or the arguments to the macro if any,
|
|
on the title page (if specified)
|
|
but not in the footers.
|
|
This is the default for
|
|
.IR troff .
|
|
.
|
|
.TP
|
|
.B .TL
|
|
Specifies the document title.
|
|
.I Groff
|
|
collects text following the
|
|
.B TL
|
|
macro into the title, until reaching the author name or abstract.
|
|
.
|
|
.TP
|
|
.B .AU
|
|
Specifies the author's name.
|
|
You can specify multiple authors by using an
|
|
.B AU
|
|
macro for each author.
|
|
.
|
|
.TP
|
|
.B .AI
|
|
Specifies the author's institution.
|
|
You can specify multiple institutions.
|
|
.
|
|
.TP
|
|
.B .AB [no]
|
|
Begins the abstract.
|
|
The default is to print the word
|
|
.BR ABSTRACT ,
|
|
centered and in italics, above the text of the abstract.
|
|
The option
|
|
.B no
|
|
suppresses this heading.
|
|
.
|
|
.TP
|
|
.B .AE
|
|
End the abstract.
|
|
.
|
|
.
|
|
.SS Paragraphs
|
|
.
|
|
Use the
|
|
.B PP
|
|
macro to create indented paragraphs,
|
|
and the
|
|
.B LP
|
|
macro to create paragraphs with no initial indent.
|
|
.
|
|
.PP
|
|
The
|
|
.B QP
|
|
macro indents all text at both left and right margins.
|
|
The effect is identical to the HTML
|
|
.B <BLOCKQUOTE>
|
|
element.
|
|
The next paragraph or heading
|
|
returns margins to normal.
|
|
.
|
|
.PP
|
|
The
|
|
.B XP
|
|
macro produces an exdented paragraph.
|
|
The first line of the paragraph begins at
|
|
the left margin,
|
|
and subsequent lines are indented
|
|
(the opposite of
|
|
.BR PP ).
|
|
.
|
|
.PP
|
|
For each of the above paragraph types,
|
|
and also for any list entry introduced by the
|
|
.B IP
|
|
macro
|
|
(described later),
|
|
the document control register
|
|
.BR PORPHANS ,
|
|
sets the
|
|
.I minimum
|
|
number of lines which must be printed,
|
|
after the start of the paragraph,
|
|
and before any page break occurs.
|
|
If there is insufficient space remaining on the current page
|
|
to accommodate this number of lines,
|
|
then a page break is forced
|
|
.I before
|
|
the first line of the paragraph is printed.
|
|
.
|
|
.PP
|
|
Similarly,
|
|
when a section heading
|
|
(see subsection
|
|
.I Headings
|
|
below)
|
|
preceeds any of these paragraph types,
|
|
the
|
|
.B HORPHANS
|
|
document control register specifies the
|
|
.I minimum
|
|
number of lines of the paragraph
|
|
which 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,
|
|
then a page break is forced
|
|
.I before
|
|
the heading is printed.
|
|
.
|
|
.
|
|
.SS Headings
|
|
.
|
|
Use headings to create a hierarchical structure
|
|
for your document.
|
|
By default,
|
|
the
|
|
.I ms
|
|
macros print headings in
|
|
.B bold
|
|
using the same font family and point size as the body text.
|
|
For output devices which support scalable fonts,
|
|
this behaviour may be modified,
|
|
by defining the document control registers,
|
|
.B GROWPS
|
|
and
|
|
.BR PSINCR .
|
|
.
|
|
.PP
|
|
The following heading macros are available:
|
|
.
|
|
.TP
|
|
.BI .NH\ xx
|
|
Numbered heading.
|
|
The argument
|
|
.I xx
|
|
is either a numeric argument to indicate the
|
|
level of the heading, or
|
|
.I S\ xx\ xx\ \c
|
|
".\|.\|."
|
|
to set the section number explicitly.
|
|
If you specify heading levels out of sequence,
|
|
such as invoking
|
|
.B ".NH\ 3"
|
|
after
|
|
.BR ".NH\ 1" ,
|
|
.I groff
|
|
prints a warning on standard error.
|
|
.
|
|
.IP
|
|
If the
|
|
.B GROWPS
|
|
register is set to a value
|
|
greater than the level of the heading,
|
|
then the point size of the heading will be increased by
|
|
.B PSINCR
|
|
units over the text size specified by the
|
|
.B PS
|
|
register,
|
|
for each level by which the heading level is less than
|
|
the value of
|
|
.BR GROWPS .
|
|
For example,
|
|
the sequence:
|
|
.
|
|
.RS
|
|
.ne 12
|
|
.nf
|
|
.IP
|
|
\&.nr PS 10
|
|
\&.nr GROWPS 3
|
|
\&.nr PSINCR 1.5p
|
|
\&.
|
|
\&.NH 1
|
|
Top Level Heading
|
|
\&.
|
|
\&.NH 2
|
|
Second Level Heading
|
|
\&.
|
|
\&.NH 3
|
|
Third Level Heading
|
|
.fi
|
|
.RE
|
|
.
|
|
.IP
|
|
will cause
|
|
.RI \*(lq 1.\ Top\ Level\ Heading \*(rq
|
|
to be printed in 13pt
|
|
.B bold
|
|
text, followed by
|
|
.RI \*(lq 1.1.\ Second\ Level\ Heading \*(rq
|
|
in 11.5pt
|
|
.B bold
|
|
text, while
|
|
.RI \*(lq 1.1.1.\ Third\ Level\ Heading \*(rq,
|
|
and all more deeply nested heading levels,
|
|
will remain in the 10pt
|
|
.B bold
|
|
text which is specified by the
|
|
.B PS
|
|
register.
|
|
.
|
|
.IP
|
|
Note that the value stored in
|
|
.B PSINCR
|
|
is interpreted in
|
|
.I groff
|
|
basic units;
|
|
the
|
|
.I p
|
|
scaling factor should be employed,
|
|
when assigning a value specified in points.
|
|
.
|
|
.IP
|
|
After invoking
|
|
.BR .NH ,
|
|
the assigned heading number is available in the strings
|
|
.B SN-DOT
|
|
(exactly as it appears in the formatted heading),
|
|
and
|
|
.B SN-NO-DOT
|
|
(with its final period omitted).
|
|
The string
|
|
.B SN
|
|
is also defined,
|
|
as an alias for
|
|
.BR SN-DOT ;
|
|
if preferred,
|
|
the user may redefine it as an alias for
|
|
.BR SN-NO-DOT ,
|
|
'ne 10
|
|
by including the initialisation:
|
|
.
|
|
.RS
|
|
.nf
|
|
.IP
|
|
\&.ds SN-NO-DOT
|
|
\&.als SN SN-NO-DOT
|
|
.fi
|
|
.RE
|
|
.
|
|
.IP
|
|
.I before
|
|
the first use of
|
|
.BR .NH ,
|
|
or simply:
|
|
.
|
|
.RS
|
|
.nf
|
|
.IP
|
|
\&.als SN SN-NO-DOT
|
|
.fi
|
|
.RE
|
|
.
|
|
.IP
|
|
.I after
|
|
the first use of
|
|
.BR .NH .
|
|
.
|
|
.TP
|
|
.BI .SH\ [ xx ]
|
|
Unnumbered subheading.
|
|
The use of the optional
|
|
.I xx
|
|
argument is a GNU extension,
|
|
which adjusts the point size of the unnumbered subheading
|
|
to match that of a numbered heading,
|
|
introduced using
|
|
.BI .NH\ xx
|
|
with the same value of
|
|
.IR xx .
|
|
For example,
|
|
given the same settings for
|
|
.BR PS ,
|
|
.B GROWPS
|
|
and
|
|
.BR PSINCR ,
|
|
as used in the preceeding
|
|
.B .NH
|
|
example,
|
|
the sequence:
|
|
.
|
|
.RS
|
|
.ne
|
|
.nf
|
|
.IP
|
|
\&.SH 2
|
|
An Unnumbered Subheading
|
|
.fi
|
|
.RE
|
|
.
|
|
.IP
|
|
will print
|
|
.RI \*(lq "An Unnumbered Subheading" \*(rq
|
|
in 11.5pt
|
|
.B bold
|
|
text.
|
|
.
|
|
.
|
|
.SS Highlighting
|
|
.
|
|
The
|
|
.I ms
|
|
macros provide a variety of methods to highlight
|
|
or emphasize text:
|
|
.
|
|
.TP
|
|
.B ".B [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
|
|
Sets its first argument in
|
|
.BR "bold type" .
|
|
If you specify a second argument,
|
|
.I groff
|
|
prints it in the previous font after
|
|
the bold text, with no intervening space
|
|
(this allows you to set punctuation after
|
|
the highlighted text without highlighting
|
|
the punctuation).
|
|
Similarly, it prints the third argument (if any)
|
|
in the previous font
|
|
.B before
|
|
the first argument.
|
|
For example,
|
|
.RS
|
|
.
|
|
.IP
|
|
\&.B foo ) (
|
|
.RE
|
|
.
|
|
.IP
|
|
prints
|
|
.RB ( foo ).
|
|
.
|
|
.IP
|
|
If you give this macro no arguments,
|
|
.I groff
|
|
prints all text following in bold until
|
|
the next highlighting, paragraph, or heading macro.
|
|
.
|
|
.TP
|
|
.B ".R [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
|
|
Sets its first argument in
|
|
roman (or regular) type.
|
|
It operates similarly to the
|
|
.B B
|
|
macro otherwise.
|
|
.
|
|
.TP
|
|
.B ".I [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
|
|
Sets its first argument in
|
|
.IR "italic type" .
|
|
It operates similarly to the
|
|
.B B
|
|
macro otherwise.
|
|
.
|
|
.TP
|
|
.B ".CW [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
|
|
Sets its first argument in a constant width face.
|
|
It operates similarly to the
|
|
.B B
|
|
macro otherwise.
|
|
.
|
|
.TP
|
|
.B ".BI [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
|
|
Sets its first argument in bold italic type.
|
|
It operates similarly to the
|
|
.B B
|
|
macro otherwise.
|
|
.
|
|
.TP
|
|
.BI ".BX [" txt ]
|
|
Prints its argument and draws a box around it.
|
|
If you want to box a string that contains spaces,
|
|
use a digit-width space (\[rs]0).
|
|
.
|
|
.TP
|
|
.BI ".UL [" txt " [" post ]]
|
|
Prints its first argument with an underline.
|
|
If you specify a second argument,
|
|
.I groff
|
|
prints it in the previous font after
|
|
the underlined text, with no intervening space.
|
|
.
|
|
.TP
|
|
.B .LG
|
|
Prints all text following in larger type
|
|
(2\~points larger than the current point size) until
|
|
the next font size, highlighting, paragraph, or heading macro.
|
|
You can specify this macro multiple times
|
|
to enlarge the point size as needed.
|
|
.
|
|
.TP
|
|
.B .SM
|
|
Prints all text following in
|
|
smaller type
|
|
(2\~points smaller than the current point size) until
|
|
the next type size, highlighting, paragraph, or heading macro.
|
|
You can specify this macro multiple times
|
|
to reduce the point size as needed.
|
|
.
|
|
.TP
|
|
.B .NL
|
|
Prints all text following in
|
|
the normal point size
|
|
(that is, the value of the
|
|
.B PS
|
|
register).
|
|
.
|
|
.TP
|
|
.BI \[rs]*{ text \[rs]*}
|
|
Print the enclosed
|
|
.I text
|
|
as a superscript.
|
|
.
|
|
.
|
|
.SS Indents
|
|
.
|
|
You may need to indent sections of text.
|
|
A typical use for indents is to create nested lists and sublists.
|
|
.
|
|
.PP
|
|
Use the
|
|
.B RS
|
|
and
|
|
.B RE
|
|
macros to start and end a section of indented text, respectively.
|
|
The
|
|
.B PI
|
|
register controls the amount of indent.
|
|
.
|
|
.PP
|
|
You can nest indented sections as deeply as needed by
|
|
using multiple, nested pairs of
|
|
.B RS
|
|
and
|
|
.BR RE .
|
|
.
|
|
.
|
|
.SS Lists
|
|
.
|
|
The
|
|
.B IP
|
|
macro handles duties for all lists.
|
|
Its syntax is as follows:
|
|
.
|
|
.TP
|
|
.BI ".IP [" marker " [" width ]]
|
|
.
|
|
.IP
|
|
The
|
|
.I marker
|
|
is usually a bullet character
|
|
.B \[rs](bu
|
|
for unordered lists,
|
|
a number (or auto-incrementing number register) for numbered lists,
|
|
or a word or phrase for indented (glossary-style) lists.
|
|
.
|
|
.IP
|
|
The
|
|
.I width
|
|
specifies the indent for the body of each list item.
|
|
Once specified, the indent remains the same for all
|
|
list items in the document until specified again.
|
|
.\" -----
|
|
.br
|
|
.ne 15
|
|
.
|
|
.
|
|
.SS "Tab stops"
|
|
.
|
|
Use the
|
|
.B ta
|
|
request to set tab stops as needed.
|
|
Use the
|
|
.B TA
|
|
macro to reset tabs to the default (every 5n).
|
|
You can redefine the
|
|
.B TA
|
|
macro to create a different set of default tab stops.
|
|
.
|
|
.
|
|
.SS "Displays and keeps"
|
|
.
|
|
Use displays to show text-based examples or figures
|
|
(such as code listings).
|
|
Displays turn off filling, so lines of code can be
|
|
displayed as-is without inserting
|
|
.B br
|
|
requests in between each line.
|
|
Displays can be
|
|
.I kept
|
|
on a single page, or allowed to break across pages.
|
|
The following table shows the display types available.
|
|
.RS
|
|
.ne 11
|
|
.na
|
|
.TS
|
|
cb s s s cbt s s
|
|
cb s cb s ^ s s
|
|
lfCW s lfCW s l s s.
|
|
Display macro Type of display
|
|
With keep No keep
|
|
_
|
|
\&.DS L \&.LD Left-justified.
|
|
\&.DS I [\fIindent\fP] \&.ID T{
|
|
Indented (default indent in the \fBDI\fP register).
|
|
T}
|
|
\&.DS B \&.BD T{
|
|
Block-centered (left-justified, longest line centered).
|
|
T}
|
|
\&.DS C \&.CD Centered.
|
|
\&.DS R \&.RD Right-justified.
|
|
_
|
|
.TE
|
|
.RE
|
|
.ad
|
|
.
|
|
.LP
|
|
Use the
|
|
.B DE
|
|
macro to end any display type.
|
|
The macros
|
|
.B Ds
|
|
and
|
|
.B De
|
|
were formerly provided as aliases for
|
|
.B DS
|
|
and
|
|
.BR DE ,
|
|
respectively, but they have been removed, and should no longer be used.
|
|
X11 documents which actually use
|
|
.B Ds
|
|
and
|
|
.B De
|
|
always load a specific macro file from the X11 distribution (macros.t)
|
|
which provides proper definitions for the two macros.
|
|
.PP
|
|
To
|
|
.I keep
|
|
text together on a page,
|
|
such as
|
|
a paragraph that refers to a table (or list, or other item)
|
|
immediately following, use the
|
|
.B KS
|
|
and
|
|
.B KE
|
|
macros.
|
|
The
|
|
.B KS
|
|
macro begins a block of text to be kept on a single page,
|
|
and the
|
|
.B KE
|
|
macro ends the block.
|
|
.
|
|
.PP
|
|
You can specify a
|
|
.I "floating keep"
|
|
using the
|
|
.B KF
|
|
and
|
|
.B KE
|
|
macros.
|
|
If the keep cannot fit on the current page,
|
|
.I groff
|
|
holds the contents of the keep and allows text following
|
|
the keep (in the source file) to fill in the remainder of
|
|
the current page.
|
|
When the page breaks,
|
|
whether by an explicit
|
|
.B bp
|
|
request or by reaching the end of the page,
|
|
.I groff
|
|
prints the floating keep at the top of the new page.
|
|
This is useful for printing large graphics or tables
|
|
that do not need to appear exactly where specified.
|
|
.
|
|
.PP
|
|
The macros
|
|
.B B1
|
|
and
|
|
.B B2
|
|
can be used to enclose a text within a box;
|
|
.B .B1
|
|
begins the box, and
|
|
.B .B2
|
|
ends it.
|
|
Text in the box is automatically placed in a diversion
|
|
(keep).
|
|
.
|
|
.
|
|
.SS "Tables, figures, equations, and references"
|
|
.
|
|
The
|
|
.I -ms
|
|
macros support the standard
|
|
.I groff
|
|
preprocessors:
|
|
.IR tbl ,
|
|
.IR pic ,
|
|
.IR eqn ,
|
|
and
|
|
.IR refer .
|
|
Mark text meant for preprocessors by enclosing it
|
|
in pairs of tags as follows:
|
|
.
|
|
.TP
|
|
.BR ".TS [H]" " and " .TE
|
|
Denotes a table, to be processed by the
|
|
.I tbl
|
|
preprocessor.
|
|
The optional
|
|
.BR H "\~argument"
|
|
instructs
|
|
.I groff
|
|
to create a running header with the information
|
|
up to the
|
|
.B TH
|
|
macro.
|
|
.I Groff
|
|
prints the header at the beginning of the table;
|
|
if the table runs onto another page,
|
|
.I groff
|
|
prints the header on the next page as well.
|
|
.
|
|
.TP
|
|
.BR .PS " and " .PE
|
|
Denotes a graphic, to be processed by the
|
|
.I pic
|
|
preprocessor.
|
|
You can create a
|
|
.I pic
|
|
file by hand, using the
|
|
AT&T
|
|
.I pic
|
|
manual available on the Web as a reference,
|
|
or by using a graphics program such as
|
|
.IR xfig .
|
|
.
|
|
.TP
|
|
.BR ".EQ [\fI\,align\/\fP]" " and " .EN
|
|
Denotes an equation, to be processed by the
|
|
.I eqn
|
|
preprocessor.
|
|
The optional
|
|
.I align
|
|
argument can be
|
|
.BR C ,
|
|
.BR L ,
|
|
or\~\c
|
|
.B I
|
|
to center (the default), left-justify, or indent
|
|
the equation.
|
|
.
|
|
.TP
|
|
.BR .[ " and " .]
|
|
Denotes a reference, to be processed by the
|
|
.I refer
|
|
preprocessor.
|
|
The GNU
|
|
.IR @g@refer (@MAN1EXT@)
|
|
manual page provides a comprehensive reference
|
|
to the preprocessor and the format of the
|
|
bibliographic database.
|
|
.
|
|
.
|
|
.SS Footnotes
|
|
.
|
|
The
|
|
.I ms
|
|
macros provide a flexible footnote system.
|
|
You can specify a numbered footnote by using the
|
|
.B \[rs]**
|
|
escape, followed by the text of the footnote
|
|
enclosed by
|
|
.B FS
|
|
and
|
|
.B FE
|
|
macros.
|
|
.
|
|
.PP
|
|
You can specify symbolic footnotes
|
|
by placing the mark character (such as
|
|
.B \[rs](dg
|
|
for the dagger character) in the body text,
|
|
followed by the text of the footnote
|
|
enclosed by
|
|
.B FS\ \[rs](dg
|
|
and
|
|
.B FE
|
|
macros.
|
|
.
|
|
.PP
|
|
You can control how
|
|
.I groff
|
|
prints footnote numbers by changing the value of the
|
|
.B FF
|
|
register as follows:
|
|
.RS
|
|
.ne 7
|
|
.
|
|
.TP
|
|
0
|
|
Prints the footnote number as a superscript; indents the footnote (default).
|
|
.
|
|
.TP
|
|
1
|
|
Prints the number followed by a period (like\~1.\&)
|
|
and indents the footnote.
|
|
.
|
|
.TP
|
|
2
|
|
Like\~1, without an indent.
|
|
.
|
|
.TP
|
|
3
|
|
Like\~1, but prints the footnote number as a hanging paragraph.
|
|
.
|
|
.LP
|
|
.RE
|
|
You can use footnotes safely within keeps and displays,
|
|
but avoid using numbered footnotes within floating keeps.
|
|
You can set a second
|
|
.B \[rs]**
|
|
between a
|
|
.B \[rs]**
|
|
and its corresponding
|
|
.BR .FS ;
|
|
as long as each
|
|
.B .FS
|
|
occurs
|
|
.I after
|
|
the corresponding
|
|
.B \[rs]**
|
|
and the occurrences of
|
|
.B .FS
|
|
are in the same order as the corresponding occurrences of
|
|
.BR \[rs]** .
|
|
.
|
|
.
|
|
.SS "Headers and footers"
|
|
.
|
|
There are two ways to define headers and footers:
|
|
.
|
|
.IP \(bu 3n
|
|
Use the strings
|
|
.BR LH ,
|
|
.BR CH ,
|
|
and
|
|
.B RH
|
|
to set the left, center, and right headers; use
|
|
.BR LF ,
|
|
.BR CF ,
|
|
and
|
|
.B RF
|
|
to set the left, center, and right footers.
|
|
This works best for documents that do not distinguish
|
|
between odd and even pages.
|
|
.
|
|
.IP \(bu
|
|
Use the
|
|
.B OH
|
|
and
|
|
.B EH
|
|
macros to define headers for the odd and even pages; and
|
|
.B OF
|
|
and
|
|
.B EF
|
|
macros to define footers for the odd and even pages.
|
|
This is more flexible than defining the individual strings.
|
|
The syntax for these macros is as follows:
|
|
.RS
|
|
.
|
|
.IP
|
|
.B ".OH '\fIleft\fP'\fIcenter\fP'\fIright\fP'"
|
|
.RE
|
|
.
|
|
.IP
|
|
You can replace the quote (') marks with any character not
|
|
appearing in the header or footer text.
|
|
.
|
|
.
|
|
.SS Margins
|
|
.
|
|
You control margins using a set of number registers.
|
|
The following table lists the register names and defaults:
|
|
.RS
|
|
.ne 8
|
|
.na
|
|
.TS
|
|
cb s cb s s cb s cb s
|
|
afCW s l s s l s l s.
|
|
Reg. Definition Effective Default
|
|
_
|
|
PO T{
|
|
Page offset (left margin)
|
|
T} next page 1i
|
|
LL T{
|
|
Line length
|
|
T} next para. 6i
|
|
LT T{
|
|
Header/footer length
|
|
T} next para. 6i
|
|
HM T{
|
|
Top (header) margin
|
|
T} next page 1i
|
|
FM T{
|
|
Bottom (footer) margin
|
|
T} next page 1i
|
|
_
|
|
.TE
|
|
.RE
|
|
.ad
|
|
.
|
|
.PP
|
|
Note that there is no right margin setting.
|
|
The combination of page offset and line length
|
|
provide the information necessary to
|
|
derive the right margin.
|
|
.
|
|
.
|
|
.SS "Multiple columns"
|
|
.
|
|
The
|
|
.I ms
|
|
macros can set text in as many columns as will reasonably
|
|
fit on the page.
|
|
The following macros are available.
|
|
All of them force a page break if a multi-column mode is already set.
|
|
However, if the current mode is single-column, starting a multi-column
|
|
mode does
|
|
.I not
|
|
force a page break.
|
|
.
|
|
.TP
|
|
.B .1C
|
|
Single-column mode.
|
|
.
|
|
.TP
|
|
.B .2C
|
|
Two-column mode.
|
|
.
|
|
.TP
|
|
.BI ".MC [" width " [" gutter ]]
|
|
Multi-column mode.
|
|
If you specify no arguments, it is equivalent to the
|
|
.B 2C
|
|
macro.
|
|
Otherwise,
|
|
.I width
|
|
is the width of each column and
|
|
.I gutter
|
|
is the space between columns.
|
|
The
|
|
.B MINGW
|
|
number register is the default gutter width.
|
|
.
|
|
.
|
|
.SS "Creating a table of contents"
|
|
.
|
|
Wrap text that you want to appear in the
|
|
table of contents in
|
|
.B XS
|
|
and
|
|
.B XE
|
|
macros.
|
|
Use the
|
|
.B TC
|
|
macro to print the table of contents at the end of the document,
|
|
resetting the page number to\~\c
|
|
.B i
|
|
(Roman numeral\~1).
|
|
.
|
|
.PP
|
|
You can manually create a table of contents
|
|
by specifying a page number as the first argument to
|
|
.BR XS .
|
|
Add subsequent entries using the
|
|
.B XA
|
|
macro.
|
|
For example:
|
|
.RS
|
|
.
|
|
.PP
|
|
.ne 8
|
|
.nf
|
|
\&.XS 1
|
|
Introduction
|
|
\&.XA 2
|
|
A Brief History of the Universe
|
|
\&.XA 729
|
|
Details of Galactic Formation
|
|
\&.\|.\|.
|
|
\&.XE
|
|
.fi
|
|
.RE
|
|
.
|
|
.LP
|
|
Use the
|
|
.B PX
|
|
macro to print a manually-generated table of contents
|
|
without resetting the page number.
|
|
.
|
|
.PP
|
|
If you give the argument
|
|
.B no
|
|
to either
|
|
.B PX
|
|
or
|
|
.BR TC ,
|
|
.I groff
|
|
suppresses printing the title
|
|
specified by the
|
|
.B \[rs]*[TOC]
|
|
string.
|
|
.
|
|
.
|
|
.SS "Fractional point sizes"
|
|
.
|
|
Traditionally, the
|
|
.I ms
|
|
macros only support integer values for the document's font size and
|
|
vertical spacing.
|
|
To overcome this restriction, values larger than or equal to 1000 are taken
|
|
as fractional values, multiplied by 1000.
|
|
For example, `.nr\~PS\~10250' sets the font size to 10.25 points.
|
|
.
|
|
.LP
|
|
The following four registers accept fractional point sizes:
|
|
.BR PS ,
|
|
.BR VS ,
|
|
.BR FPS ,
|
|
and
|
|
.BR FVS .
|
|
.
|
|
.LP
|
|
Due to backwards compatibility, the value of
|
|
.B VS
|
|
must be smaller than 40000 (this is 40.0 points).
|
|
.
|
|
.
|
|
.
|
|
.SH "DIFFERENCES FROM troff ms"
|
|
.
|
|
The
|
|
.I "groff ms"
|
|
macros are a complete re-implementation,
|
|
using no original AT&T code.
|
|
Since they take advantage of the extended features in
|
|
.IR groff ,
|
|
they cannot be used with AT&T
|
|
.IR troff .
|
|
Other differences include:
|
|
.
|
|
.IP \(bu 3n
|
|
The internals of
|
|
.I "groff ms"
|
|
differ from the internals of Unix
|
|
.IR ms .
|
|
Documents that depend upon implementation details of Unix
|
|
.I ms
|
|
may not format properly with
|
|
.IR "groff ms" .
|
|
.
|
|
.IP \(bu
|
|
The error-handling policy of
|
|
.I "groff ms"
|
|
is to detect and report errors,
|
|
rather than silently to ignore them.
|
|
.
|
|
.IP \(bu
|
|
Bell Labs localisms are not implemented.
|
|
.
|
|
.IP \(bu
|
|
Berkeley localisms, in particular the
|
|
.B TM
|
|
and
|
|
.B CT
|
|
macros,
|
|
are not implemented.
|
|
.
|
|
.IP \(bu
|
|
.I "Groff ms"
|
|
does not work in compatibility mode (e.g., with the
|
|
.B \-C
|
|
option).
|
|
.
|
|
.IP \(bu
|
|
There is no support for typewriter-like devices.
|
|
.
|
|
.IP \(bu
|
|
.I "Groff ms"
|
|
does not provide cut marks.
|
|
.
|
|
.IP \(bu
|
|
Multiple line spacing is not supported
|
|
(use a larger vertical spacing instead).
|
|
.
|
|
.IP \(bu
|
|
Some Unix
|
|
.I ms
|
|
documentation says that the
|
|
.B CW
|
|
and
|
|
.B GW
|
|
number registers can be used to control the column width and
|
|
gutter width, respectively.
|
|
These number registers are not used in
|
|
.IR "groff ms" .
|
|
.
|
|
.IP \(bu
|
|
Macros that cause a reset
|
|
(paragraphs, headings, etc.\&)
|
|
may change the indent.
|
|
Macros that change the indent do not increment or decrement
|
|
the indent, but rather set it absolutely.
|
|
This can cause problems for documents that define
|
|
additional macros of their own.
|
|
The solution is to use not the
|
|
.B in
|
|
request but instead the
|
|
.B RS
|
|
and
|
|
.B RE
|
|
macros.
|
|
.
|
|
.IP \(bu
|
|
The number register
|
|
.B GS
|
|
is set to\~1 by the
|
|
.I "groff ms"
|
|
macros,
|
|
but is not used by the Unix
|
|
.I ms
|
|
macros.
|
|
Documents that need to determine whether
|
|
they are being formatted with Unix
|
|
.I ms
|
|
or
|
|
.I "groff ms"
|
|
should use this number register.
|
|
.
|
|
.IP \(bu
|
|
To make
|
|
.I "groff ms"
|
|
use the default page offset (which also specifies the left margin),
|
|
the
|
|
.B PO
|
|
number register must stay undefined until the first
|
|
.B ms
|
|
macro is evaluated.
|
|
This implies that
|
|
.B PO
|
|
should not be used early in the document, unless it is changed also:
|
|
Remember that accessing an undefined register automatically defines it.
|
|
.br
|
|
.ne 23
|
|
.
|
|
.
|
|
.SS Strings
|
|
.
|
|
You can redefine the following strings to adapt the
|
|
.I "groff ms"
|
|
macros to languages other than English:
|
|
.TS
|
|
center;
|
|
cb cb
|
|
afCW l .
|
|
String Default Value
|
|
_
|
|
REFERENCES References
|
|
ABSTRACT ABSTRACT
|
|
TOC Table of Contents
|
|
MONTH1 January
|
|
MONTH2 February
|
|
MONTH3 March
|
|
MONTH4 April
|
|
MONTH5 May
|
|
MONTH6 June
|
|
MONTH7 July
|
|
MONTH8 August
|
|
MONTH9 September
|
|
MONTH10 October
|
|
MONTH11 November
|
|
MONTH12 December
|
|
_
|
|
.TE
|
|
.
|
|
.PP
|
|
The
|
|
.B \[rs]*-
|
|
string produces an em dash \[em] like this.
|
|
.
|
|
.PP
|
|
Use
|
|
.B \[rs]*Q
|
|
and
|
|
.B \[rs]*U
|
|
to get a left and right typographer's quote,
|
|
respectively, in
|
|
.I troff
|
|
(and plain quotes in
|
|
.IR nroff ).
|
|
|
|
.
|
|
.
|
|
.SS Text Settings
|
|
.
|
|
The
|
|
.B FAM
|
|
string sets the default font family.
|
|
If this string is undefined at initialization,
|
|
it is set to Times.
|
|
.
|
|
.LP
|
|
The point size, vertical spacing, and inter-paragraph spacing for footnotes
|
|
are controlled by the number registers
|
|
.BR FPS ,
|
|
.BR FVS ,
|
|
and
|
|
.BR FPD ;
|
|
at initialization these are set to
|
|
.BR \[rs]n(PS-2 ,
|
|
.BR \[rs]n[FPS]+2 ,
|
|
and
|
|
.BR \[rs]n(PD/2 ,
|
|
respectively.
|
|
If any of these registers are defined before initialization,
|
|
the initialization macro does not change them.
|
|
.
|
|
.LP
|
|
The hyphenation flags (as set by the
|
|
.B hy
|
|
request) are set from the
|
|
.B HY
|
|
register;
|
|
the default is\~14.
|
|
.
|
|
.PP
|
|
Improved accent marks
|
|
(as originally defined in Berkeley's
|
|
.I ms
|
|
version)
|
|
are available by specifying the
|
|
.B AM
|
|
macro at the beginning of your document.
|
|
You can place an accent over most characters
|
|
by specifying the string defining the accent
|
|
directly after the character.
|
|
For example,
|
|
.B n\[rs]*~
|
|
produces an n with a tilde over it.
|
|
.
|
|
.
|
|
.
|
|
.SH "NAMING CONVENTIONS"
|
|
.
|
|
.
|
|
.LP
|
|
The following conventions are used for names of macros, strings and
|
|
number registers.
|
|
External names available to documents that use the
|
|
.I "groff ms"
|
|
macros contain only uppercase letters and digits.
|
|
.
|
|
.LP
|
|
Internally the macros are divided into modules;
|
|
naming conventions are as follows:
|
|
.
|
|
.IP \(bu 3n
|
|
Names used only within one module are of the form
|
|
.IB \%module * name\fR.
|
|
.
|
|
.IP \(bu
|
|
Names used outside the module in which they are defined are of the form
|
|
.IB \%module @ name\fR.
|
|
.
|
|
.IP \(bu
|
|
Names associated with a particular environment are of the form
|
|
.IB \%environment : name\fR;
|
|
these are used only within the
|
|
.B par
|
|
module.
|
|
.
|
|
.IP \(bu
|
|
.I name
|
|
does not have a module prefix.
|
|
.
|
|
.IP \(bu
|
|
Constructed names used to implement arrays are of the form
|
|
.IB \%array ! index\fR.
|
|
.
|
|
.PP
|
|
Thus the groff ms macros reserve the following names:
|
|
.
|
|
.IP \(bu 3n
|
|
Names containing the characters
|
|
.BR * ,
|
|
.BR @ ,
|
|
and\~\c
|
|
.BR : .
|
|
.
|
|
.IP \(bu
|
|
Names containing only uppercase letters and digits.
|
|
.
|
|
.
|
|
.
|
|
.SH FILES
|
|
.
|
|
.B @MACRODIR@/ms.tmac
|
|
(a wrapper file for
|
|
.BR s.tmac )
|
|
.br
|
|
.B @MACRODIR@/s.tmac
|
|
.
|
|
.
|
|
.
|
|
.SH "SEE ALSO"
|
|
.
|
|
.BR groff (@MAN1EXT@),
|
|
.BR @g@troff (@MAN1EXT@),
|
|
.BR @g@tbl (@MAN1EXT@),
|
|
.BR @g@pic (@MAN1EXT@),
|
|
.BR @g@eqn (@MAN1EXT@),
|
|
.BR @g@refer (@MAN1EXT@),
|
|
.I Groff: The GNU Implementation of troff
|
|
by Trent Fisher and Werner Lemberg.
|
|
.
|
|
.
|
|
.
|
|
.SH AUTHOR
|
|
.
|
|
Original manual page by James Clark
|
|
.IR "et al" ;
|
|
rewritten by Larry Kollar
|
|
(\fIlkollar@despammed.com\fR).
|
|
.
|
|
.cp \n[groff_ms_C]
|
|
.
|
|
.\" Local Variables:
|
|
.\" mode: nroff
|
|
.\" End:
|