man.7

.de mi
.BR mt ,
.BR mp ,
\\$1
.B mb
..
.TH MT 7
.SH NAME
mt, mp, mb \- macros for troff
.SH SYNOPSIS
.B troff
.B \-mt
.RI [ options ]
.IR file ...
.br
.B troff
.B \-mp
.RI [ options ]
.IR file ...
.br
.B troff
.B \-mb
.RI [ options ]
.IR file ...
.SH DESCRIPTION
.mi and
are troff macro packages that provides macros for formatting
technical papers,
slide presentations,
and books,
respectively.
.PP
The content of a document processed by troff with one of those macro packages
fits a paper which size depends on the macro package:
.TP
.B mt
ISO A4 paper.
.TP
.B mp
Landscape US letter paper.
.TP
.B mb
ISO B5 paper.
.PP
When using one of those macro packages,
options to set the page size must be passed to the post-processors that
convert the output of troff to postscript or pdf.
.PP
In a
.mi or
document, lines beginning with the control character '.' are called "macro lines".
It usually consists of two capital letters.
The words following the macro names are arguments to the macro.
.PP
When a document is processed with the
.mi or
macro package,
troff outputs to the standard error (stderr)
.B .IC
and
.B .IS
macro lines prefixed with "index:" to be used for creating the table of contents.
The standard error can be redirected to a file for further processing.
.SH MACROS
The
.mi and
macro packages use macros to format the document.
All macros that are exposed to the user consist of two uppercase letters.
.PP
Known macros are listed below.
.TP
.B .AE
End an abstract that was started by the
.B .AS
macro.
.TP
.B .AS \(dq\fIidentifier\fP\(dq
Begin the abstract.
If an argument is supplied, it is used to identify the abstract
(this string should be, in english documents, \(dqAbstract\(dq).
The abstract should be ended with the
.B .AE
macro.
The abstract should contain paragraphs (marked by the
.B .PP
macro).
The
.B .AS
macro should be used directly after a
.BR .TL ,
or
.B .AU
macros
.TP
.B .AU \(dq\fIauthor\fP\(dq [\(dq\fIinstitution\fP\(dq]
Specify an author of the document and the institution of this author.
The institution, if supplied, is printed in a line below the author.
More than one
.B .AU
macros can be used.
The
.B .AU
macros should be used directly after a
.BR .TL
macro.
.TP
\&\fB.AX\fR "\fIappendix\fR"
Begin an appendix.
An appendix is like a chapter but labeled with letters rather than numbers.
The argument is the appendix name.
This macro also sets the
.B cH
internal string to the chapter name;
and sets the
.B h0
internal number register to the chapter number.
.TP
\&\fB.B\fR ["\fImid\fR"] ["\fIend\fR"] ["\fIbeg\fR"]
If no argument is given, this macro sets the font to bold for the text that follows,
until the font be automatically reset in the next paragraph.
If a single argument is given, it is printed in bold font, without setting the font of the remaining text.
If two arguments are given, the first is printed in bold font, and the second one is printed after it.
If three arguments are given, the first is printed in bold font, the second one is printed after it, and the third one is printed before it.
.TP
.B .CE
End a code block started by
.BR .CS .
.TP
\&\fB.CH\fR "\fIchapter\fR"
Begin a chapter.
The argument is the chapter name.
This macro also sets the
.B cH
internal string to the chapter name;
and sets the
.B h0
internal number register to the chapter number.
.TP
.B .CS
Start a code block.
Text in a code block are printed in constant width font.
A code block must be ended with
.BR .CE .
.TP
\&\fB.CW\fR ["\fImid\fR"] ["\fIend\fR"] ["\fIbeg\fR"]
If no argument is given, this macro sets the font to constant width (monospace) for the text that follows,
until the font be automatically reset in the next paragraph.
If a single argument is given, it is printed in constant width font, without setting the font of the remaining text.
If two arguments are given, the first is printed in constant width font, and the second one is printed after it.
If three arguments are given, the first is printed in constant width font, the second one is printed after it, and the third one is printed before it.
.TP
.B .FC \(dq\fIcaption\fP\(dq [\fItype\fP]
Specify the caption of a figure and its type.
Two types of captions are known:
.B f
(for regular figures)
and
.B t
(for tables).
When this macro is used, the internal counter that counts figures
(or the internal counter that counts tables)
is incremented.
Then the string
.B Figure N: CAPTION
(or
.BR "Table N: CAPTION" )
is printed, where
.B N
is the value of the counter of figures (or tables),
and
.B CAPTION
is the provided caption.
The strings \(dqFigure\(dq and \(dqTable\(dq
are actually the values of the strings
.B F
and
.B T
respectively.
.TP
.B .FE
End a figure started by
.BR .FS .
.TP
.B .FS
Start a figure.
A figure must be ended with the
.B .FS
macro.
A figure caption macro
.B .FC
can be used between the
.B .FS
and
.B .FE
macros.
.TP
\fB.HL\fR "\fIURI\fR" "\fItext\fR"
Format
.I text
as a hyperlink to
.IR URI .
.TP
\&\fB.I\fR ["\fImid\fR"] ["\fIend\fR"] ["\fIbeg\fR"]
If no argument is given, this macro sets the font to italic for the text that follows,
until the font be automatically reset in the next paragraph.
If a single argument is given, it is printed in italic font, without setting the font of the remaining text.
If two arguments are given, the first is printed in italic font, and the second one is printed after it.
If three arguments are given, the first is printed in italic font, the second one is printed after it, and the third one is printed before it.
.TP
\&\fB.IC\fR \fIpage\fR \fInumber\fR \fIname\fR
Create entry for a chapter in the table of contents.
The first argument is the page in which the chapter begins.
The second argument is the number of the chapter.
The third argument is the name of the chapter.
.TP
\&\fB.IS\fR \fIpage\fR \fIlevel\fR \fIname\fR
Create entry for a section heading in the table of contents.
The first argument is the page in which the section begins.
The second argument is the level of the section
(such as "1.2.3" for the third subsection of the second section of the first chapter).
The third argument is the name of the section.
.TP
.B .LE
End a list started with the
.B .LS
macro.
.TP
.B .LI
Begin a list item.
What follows is the list item.
.TP
.B .LS [\(dq\fItype\fP\(dq]
Start a list.
A list started with
.B .LS
must be ended with the
.B .LE
macro.
The
.I type
argument can be
.B \(dqb\(dq
for a bulleted list (the default),
.B \(dq1\(dq
for a numbered list,
.B \(dqi\(dq
for an ordered list with lowercase roman numerals,
.B \(dqI\(dq
for an ordered list with uppercase roman numerals,
.B \(dqa\(dq
for an ordered list with lowercase letters,
.B \(dqA\(dq
for an ordered list with uppercase letters.
.TP
.B .NE
End a footnote started by
.BR .NS .
.TP
.B .NS
Start a footnote.
That macro should be called right after the place in the main text that the footnote references.
The line before that macro should end in
.B \ec
(this is a requirement for the footnote reference to not be spaced after the text before it).
Everything that follows that macro is the footnote.
A footnote must be ended with
.BR .NE .
.TP
.B .PP \(dq\fItitle\fP\(dq
Begin a paragraph.
If an argument is provided,
it is used as the title of the paragraph and is printed in bold before the first line of the paragraph.
The number registers
.BR SP ,
.BR PN ,
and
.B PT
change how paragraphs are printed.
.TP
.B .QE
End a block quote started by
.BR .QS .
.TP
.B .QS
Start a block quote.
A block quote must be ended with
.BR .QE .
A block quote is indented to the right and begins with a open quotation mark in bold face.
When using the
.B mp
macro package for slide presentations,
each paragraph is printed in a different page (slide).
.TP
\&\fB.R\fR ["\fImid\fR"] ["\fIend\fR"] ["\fIbeg\fR"]
If no argument is given, this macro sets the font to roman (regular) for the text that follows,
until the font be automatically reset in the next paragraph.
If a single argument is given, it is printed in roman font, without setting the font of the remaining text.
If two arguments are given, the first is printed in roman font, and the second one is printed after it.
If three arguments are given, the first is printed in roman font, the second one is printed after it, and the third one is printed before it.
.TP
\&\fB.SB\fR "\fImid\fR" ["\fIend\fR"] ["\fIbeg\fR"]
The first is printed as a subscript,
the second one is printed after it,
and the third one is printed before it.
The second and third arguments are optional.
.TP
.B .SH level \(dq\fIheading\fP\(dq
Specify a section heading and its level.
The first argument defines the level of the section heading.
The second argument is the heading itself.
The section heading is printed in bold and two points larger than the regular paragraph size.
If the level is less or equal than the number register
.BR SS ,
then the section heading is prefixed with a string containing the number of the section.
.TP
\&\fB.SP\fR "\fImid\fR" ["\fIend\fR"] ["\fIbeg\fR"]
The first is printed as a superscript,
the second one is printed after it,
and the third one is printed before it.
The second and third arguments are optional.
.TP
.B .SZ
Begin a stanza (a paragraph of non-filled text).
.TP
.B .TC
Begin table of contents.
The table of contents is indicated by the string
.B J
("Contents" by default).
It must be followed by the macros
.B .IC
and
.BR .IS .
.TP
.B .TL \(dq\fItitle\fP\(dq
Specify the document title.
This macro also sets the
.B .tL
internal string to the title.
The title is printed centered, in bold and four points larger than the regular paragraph size.
If more than one argument is provided (up to five),
each argument is printed in a different line on the title page.
.PP
There are also some macros that are used internaly,
and therefore should not be overwritten.
Internal macros are listed below.
.TP
.B .bG
Called at the beginning of the document by some macros.
.TP
.B .bM
Called at the end of every page via a trap to set the bottom margin of the page.
.TP
.B .bY
Called at the beginning of the document body by paragraph and section macros.
.TP
.B .fC
Diversion used for figure captions.
.TP
.B .fG
Diversion used for figures.
.TP
.BR .hD
Called at the beginning of a chapter or appendix
.TP
.BR .nN ", " .nX ", " .nY ", " .nZ
Those macros are used internally to implement footnotes.
.TP
.B .pB
Called at the beginning of every paragraph to set vertical space.
.TP
.B .rT
Called at the beginning of every paragraph to reset the text formatting.
.TP
.B .sS
Called at the beginning of every section to set the section point size.
.TP
.B .tT
Called at the beginning of every page via a trap to print the top title (header).
.TP
.B .tM
Called at the beginning of every page via a trap to set the top and left margins of the page.
.SH NUMBER REGISTERS
The
.mi and
macro packages use number registers to control the formatting of the document.
Number registers can be set at the top of a document using the
.B .nr
troff request.
All number registers that are exposed for the user to set consist of two uppercase letters.
.TP
.B FD
Figure spacing (distance).
.TP
.B LL
Line length (default 16cm).
.TP
.B MB
Bottom margin for both odd and even pages (default: 2cm).
.TP
.B ME
Left margin for even pages (default: 2.5cm).
.TP
.B MO
Left margin for odd pages (default: 2.5cm).
.TP
.B MT
Top margin for both odd and even pages (default: 3cm).
.TP
.B PD
Paragraph spacing (distance).
.TP
.B PH
Page height (default: 29.7cm).
.TP
.B PI
Paragraph indent.
.TP
.B PN
If set to non-zero, paragraphs are numbered.
.TP
.B PS
Point size (default 10 points).
.TP
.B PT
If set to a given value and unit,
if a paragraph has a title,
the content of the paragraph is indented to the right of the title by this given amount of units.
.TP
.B SP
Paragraph indentation style:
0 for no indent,
1 for indent on all paragraphs,
2 for smart indent (indent on all paragraphs except after figures).
(default 1).
.TP
.B SS
Section style:
0 for no numbering,
1 for numbering only for the first level heading.
2 for numbering until the second level heading.
3 for numbering until the third level heading.
4 for numbering until the fourth level heading.
5 for numbering until the fifth level heading.
Five is the maximum level of section heading.
(default 4).
.TP
.B VS
Vertical line spacing.
.PP
There are also some number registers that are used internaly,
and therefore should not be overwritten.
Internal number registers are listed below.
.TP
.B bG
Set to 1 when the macro
.B .bG
is run.
.TP
.B bY
Set to 1 when the macro
.B .bY
is run.
.TP
.B fC
Figure level counter.
When a figure begins, this number register is incremented.
When a figure ends, this number register is decremented.
.TP
.B fI
Set to 1 at the end of a figure; reset at the beginning of a paragraph.
.TP
.B fN
Figure counter.
Each time the figure caption macro
.RB ( .FC )
is called with the argument of
.B f
(or with no argument), this counter is incremented.
.TP
.B h0
The number of the current chapter.
.TP
.BR h1 " to " h5
The number of the current sections of level 1 to 5.
.TP
.B iN
The current indent level.
.TP
.B i1 " to " i9
The previous saved indentation for each indent level.
.TP
.B lN
List level counter.
Each time the list start macro
.RB ( .LS )
is called, this counter is incremented.
Each time the list end macro
.RB ( .LE )
is called, this counter is decremented.
.TP
.B mT
Set to 0 on title page, set to 1 otherwise.
This number register is used to avoid printing header titles and footer titles on the page.
.TP
.BR nI ", " nC ", " nJ ", " nP ", " n? ", " iS ", " vS
Those numer registers are used internally to implement footnotes.
.TP
.B pC
Paragraph counter (used when the
.B PN
number register is set to non-zero).
.TP
.B sI
Set to 1 when a section is processed;
reset at the beginning of a paragraph.
.TP
.B sL
The current section level counter.
.TP
.B tN
Table counter.
Each time the figure caption macro
.RB ( .FC )
is called with the argument of 
.BR t ,
this counter is incremented.
.SH STRINGS
The
.mi and
macro packages use some strings as constants.
These strings are by default in the English language,
and should be redefined to match the document language.
Strings can be set at the top of a document using the
.B .ds
troff request.
.PP
Known strings are listed below.
.TP
.B C
If set, is used as the default chapter prefix.
.TP
.B J
Contents (used for the table of contents).
.TP
.B F
Figure
.TP
.B T
Table
.TP
.B X
Appendix
.PP
There are also some strings that are used internaly,
and therefore should not be overwritten.
Internal strings are listed below.
.TP
.B cH
This string contains the name of the current chapter.
It is used in the header of the page.
.TP
.B sH
This string contains the name of the last numbered section heading.
It is used in the header of the page.
.TP
.B sN
This string contains the number prefix of the section heading.
.SH SEE ALSO
.IR troff (1)