NAME¶
mdoc —
quick reference guide for the
-mdoc macro package
SYNOPSIS¶
DESCRIPTION¶
The
-mdoc package is a set of content-based and domain-based
macros used to format the
BSD man pages. The macro
names and their meanings are listed below for quick reference; for a detailed
explanation on using the package, see the tutorial sampler
mdoc.samples(7).
Note that this is not the usual macro package for Linux documentation, although
it is used for documentation of several widely-used programs; see
man(7).
The macros are described in two groups, the first includes the structural and
physical page layout macros. The second contains the manual and general text
domain macros which differentiate the
-oc package from other
troff formatting packages.
PAGE STRUCTURE DOMAIN¶
Title Macros¶
To create a valid manual page, these three macros, in this order, are required:
.Dd
Month day, year
- Document date.
.Dt
DOCUMENT_TITLE [section] [volume]
- Title, in upper case.
.Os
OPERATING_SYSTEM [version/release]
- Operating system (BSD).
Page Layout Macros¶
Section headers, paragraph breaks, lists and displays.
.Sh
- Section Headers. Valid headers, in the order of
presentation:
- NAME
- Name section, should include the
‘
.Nm
’ or
‘.Fn
’ and the
‘.Nd
’ macros.
- SYNOPSIS
- Usage.
- DESCRIPTION
- General description, should include options and
parameters.
- RETURN
VALUES
- Sections two and three function calls.
- ENVIRONMENT
- Describe environment variables.
- FILES
- Files associated with the subject.
- EXAMPLES
- Examples and suggestions.
- DIAGNOSTICS
- Normally used for section four device interface
diagnostics.
- ERRORS
- Sections two and three error and signal handling.
- SEE
ALSO
- Cross references and citations.
- STANDARDS
- Conformance to standards if applicable.
- HISTORY
- If a standard is not applicable, the history of the
subject should be given.
- BUGS
- Gotchas and caveats.
- other
- Customized headers may be added at the authors
discretion.
.Ss
- Subsection Headers.
.Pp
- Paragraph Break. Vertical space (one line).
.D1
- (D-one) Display-one Indent and display one text line.
.Dl
- (D-ell) Display-one literal. Indent and display one line of
literal text.
.Bd
- Begin-display block. Display options:
- -ragged
- Unjustified (ragged edges).
- -filled
- Justified.
- -literal
- Literal text or code.
- -file
name
- Read in named file and
display.
- -offset
string
- Offset display. Acceptable string
values:
- left
- Align block on left (default).
- center
- Approximate center margin.
- indent
- Six constant width spaces (a tab).
- indent-two
- Two tabs.
- right
- Left aligns block 2 inches from right.
- xxn
- Where xx is a number from
4n to
99n.
- Aa
- Where Aa is a callable macro
name.
- string
- The width of string is
used.
.Ed
- End-display (matches .Bd).
.Bl
- Begin-list. Create lists or columns. Options:
- List-types
-
-bullet |
Bullet Item
List |
-item |
Unlabeled
List |
-enum |
Enumerated
List |
-tag |
Tag Labeled
List |
-diag |
Diagnostic
List |
-hang |
Hanging Labeled
List |
-ohang |
Overhanging
Labeled List |
-inset |
Inset or Run-on
Labeled List |
- List-parameters
-
- -offset
- (All lists.) See
‘
.Bd
’ begin-display
above.
- -width
- (-tag and -hang
lists only.) See ‘
.Bd
’.
- -compact
- (All lists.) Suppresses blank lines.
.El
- End-list.
.It
- List item.
MANUAL AND GENERAL
TEXT DOMAIN MACROS¶
The manual and general text domain macros are special in that most of them are
parsed for callable macros for example:
.Op Fl s Ar
file
- Produces [-s
file]
In this example, the option enclosure macro
‘
.Op
’ is parsed, and calls the callable
content macro ‘
Fl
’ which operates on the
argument ‘
s
’ and then calls the callable
content macro ‘
Ar
’ which operates on the
argument ‘
file
’. Some macros may be
callable, but are not parsed and vice versa. These macros are indicated in the
parsed and
callable columns below.
Unless stated, manual domain macros share a common syntax:
.Va argument
[ . , ; : ( ) [ ] argument
... ]
Note: Opening and closing punctuation characters are only
recognized as such if they are presented one at a time. The string
‘
),
’ is not recognized as punctuation and
will be output with a leading white space and in what ever font the calling
macro uses. The argument list ‘
] ) ,
’ is
recognized as three sequential closing punctuation characters and a leading
white space is not output between the characters and the previous argument (if
any). The special meaning of a punctuation character may be escaped with the
string ‘
\&
’. For example the following
string,
.Ar
file1 , file2 , file3 ) .
- Produces file1,
file2, file3).
Manual Domain Macros¶
Name |
Parsed |
Callable |
Description |
Ad |
Yes |
Yes |
Address. (This macro may
be deprecated.) |
An |
Yes |
Yes |
Author name. |
Ar |
Yes |
Yes |
Command line
argument. |
Cd |
No |
No |
Configuration declaration
(section four only). |
Cm |
Yes |
Yes |
Command line argument
modifier. |
Dv |
Yes |
Yes |
Defined variable (source
code). |
Er |
Yes |
Yes |
Error number (source
code). |
Ev |
Yes |
Yes |
Environment variable. |
Fa |
Yes |
Yes |
Function argument. |
Fd |
Yes |
Yes |
Function declaration. |
Fn |
Yes |
Yes |
Function call (also .Fo
and .Fc). |
Ic |
Yes |
Yes |
Interactive command. |
Li |
Yes |
Yes |
Literal text. |
Nm |
Yes |
Yes |
Command name. |
Op |
Yes |
Yes |
Option (also .Oo and
.Oc). |
Ot |
Yes |
Yes |
Old style function type
(Fortran only). |
Pa |
Yes |
Yes |
Pathname or file
name. |
St |
Yes |
Yes |
Standards (-p1003.2,
-p1003.1 or -ansiC) |
Va |
Yes |
Yes |
Variable name. |
Vt |
Yes |
Yes |
Variable type (Fortran
only). |
Xr |
Yes |
Yes |
Manual Page Cross
Reference. |
General Text Domain Macros¶
Name |
Parsed |
Callable |
Description |
%A |
Yes |
No |
Reference author. |
%B |
Yes |
Yes |
Reference book title. |
%C |
No |
No |
Reference place of
publishing (city). |
%D |
No |
No |
Reference date. |
%J |
Yes |
Yes |
Reference journal
title. |
%N |
No |
No |
Reference issue
number. |
%O |
No |
No |
Reference optional
information. |
%P |
No |
No |
Reference page
number(s). |
%R |
No |
No |
Reference report
Name. |
%T |
Yes |
Yes |
Reference article
title. |
%V |
No |
No |
Reference volume. |
Ac |
Yes |
Yes |
Angle close quote. |
Ao |
Yes |
Yes |
Angle open quote. |
Ap |
Yes |
Yes |
Apostrophe. |
Aq |
Yes |
Yes |
Angle quote. |
At |
No |
No |
AT&T UNIX |
Bc |
Yes |
Yes |
Bracket close quote. |
Bf |
No |
No |
Begin font mode. |
Bo |
Yes |
Yes |
Bracket open quote. |
Bq |
Yes |
Yes |
Bracket quote. |
Bx |
Yes |
Yes |
BSD. |
|
Li Db |
No |
No |
Debug (default is
\*qoff\*q) |
Dc |
Yes |
Yes |
Double close quote. |
Do |
Yes |
Yes |
Double open quote. |
Dq |
Yes |
Yes |
Double quote. |
Ec |
Yes |
Yes |
Enclose string close
quote. |
Ef |
No |
No |
End font mode. |
Em |
Yes |
Yes |
Emphasis (traditional
English). |
Eo |
Yes |
Yes |
Enclose string open
quote. |
Fx |
No |
No |
FreeBSD operating
system |
No |
Yes |
Yes |
Normal text (no-op). |
Ns |
Yes |
Yes |
No space. |
Pc |
Yes |
Yes |
Parenthesis close
quote. |
Pf |
Yes |
No |
Prefix string. |
Po |
Yes |
Yes |
Parenthesis open
quote. |
Pq |
Yes |
Yes |
Parentheses quote. |
Qc |
Yes |
Yes |
Straight Double close
quote. |
Ql |
Yes |
Yes |
Quoted literal. |
Qo |
Yes |
Yes |
Straight Double open
quote. |
Qq |
Yes |
Yes |
Straight Double
quote. |
Re |
No |
No |
Reference end. |
Rs |
No |
No |
Reference start. |
Rv |
No |
No |
Return values (sections
two and three only). |
Sc |
Yes |
Yes |
Single close quote. |
So |
Yes |
Yes |
Single open quote. |
Sq |
Yes |
Yes |
Single quote. |
Sm |
No |
No |
Space mode (default is
\*qon\*q) |
Sx |
Yes |
Yes |
Section Cross
Reference. |
Sy |
Yes |
Yes |
Symbolic (traditional
English). |
Tn |
Yes |
Yes |
Trade or type name (small
Caps). |
Ux |
Yes |
Yes |
UNIX |
Xc |
Yes |
Yes |
Extend argument list
close. |
Xo |
Yes |
Yes |
Extend argument list
open. |
Macro names ending in ‘
q
’ quote remaining
items on the argument list. Macro names ending in
‘
o
’ begin a quote which may span more than
one line of input and are close quoted with the matching macro name ending in
‘
c
’. Enclosure macros may be nested and
are limited to eight arguments.
Note: the extended argument list macros
(‘
.Xo
’,
‘
.Xc
’) and the function enclosure macros
(‘
.Fo
’,
‘
.Fc
’) are irregular. The extended list
macros are used when the number of macro arguments would exceed the
troff limitation of nine arguments.
The macros UR (starting a URI/URL hypertext reference), UE (ending one), and UN
(identifying a target for a reference) are also available. See
man(7) for more information on these macros.
CONFIGURATION¶
For site specific configuration of the macro package, see the file
/usr/src/share/tmac/README.
FILES¶
- tmac.doc
- Manual and general text domain macros.
- tmac.doc-common
- Common structural macros and definitions.
- tmac.doc-nroff
- Site dependent nroff style file.
- tmac.doc-ditroff
- Site dependent troff style file.
- tmac.doc-syms
- Special defines (such as the standards macro).
SEE ALSO¶
mdoc.samples(7),
man(7)