.\"	$OpenBSD: mdoc.7,v 1.39 2007/05/31 22:10:19 jmc Exp $
.\"
.\" Copyright (c) 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)mdoc.7	8.2 (Berkeley) 12/30/93
.\"
.Dd $Mdocdate: May 31 2007 $
.Dt MDOC 7
.Os
.Sh NAME
.Nm mdoc
.Nd quick reference guide for the
.Nm \-mdoc
macro package
.Sh SYNOPSIS
.Nm nroff
.Fl T Ns Ar Name
.Fl mandoc
.Ar file
.Sh DESCRIPTION
The
.Nm \-mdoc
package is a set of content-based and domain-based macros
used to format the
.Bx
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
.Xr mdoc.samples 7 .
.Pp
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
.Nm -\mdoc
package from other
.Xr troff 1
formatting packages.
.Sh PAGE STRUCTURE DOMAIN
.Ss Title Macros
To create a valid manual page, these three macros, in this order,
are required:
.Bl -tag -width "xxxx.Os OPERATINGxSYSTEM [version/release]" -compact
.Pp
.It Li "\&.Dd   $\&Mdocdate$"
Expands to document date.
.It Li "\&.Dt  " Ar "DOCUMENT_TITLE [section] [volume]"
Title, in upper case.
.It Li "\&.Os  " Ar "OPERATING_SYSTEM [version/release]"
Operating system
.Pq Tn BSD .
.El
.Ss Page Layout Macros
Section headers, paragraph breaks, lists and displays.
.Bl -tag -width flag -compact
.It Li \&.Sh
Section Headers.
Valid headers, in the order of presentation:
.Bl -tag -width "RETURN VALUES" -compact
.It Ar NAME
Name section.
Should include the
.Ql \&.Nm
or
.Ql \&.Fn
and the
.Ql \&.Nd
macros.
.It Ar SYNOPSIS
Usage.
All
.Ql \&.Nm
macros must be given an argument.
.It Ar DESCRIPTION
General description, including any options, operands, or other parameters.
.It Ar RETURN VALUES
Sections two, three, and nine function calls.
.It Ar ENVIRONMENT
Describe environment variables.
.It Ar FILES
Files associated with the subject, with short descriptions.
.It Ar EXAMPLES
Examples and suggestions.
.It Ar DIAGNOSTICS
Sections one, four, six, and eight diagnostics.
.It Ar ERRORS
Sections two, three, and nine error and signal handling.
.It Ar SEE ALSO
Cross references and citations.
.It Ar STANDARDS
Conformance to standards if applicable.
.It Ar HISTORY
A brief history of the subject, including where support first appeared.
.It Ar AUTHORS
Credit to the person or persons who wrote the code and/or documentation.
.It Ar CAVEATS
Explanations of common misuses, i.e., security considerations for certain
library functions.
.It Ar BUGS
Gotchas and caveats.
.It Ar other
Customized headers may be added at the author's discretion.
.El
.It Li \&.Ss
Subsection Headers.
.It Li \&.Pp
Paragraph Break.
Vertical space (one line).
.It Li \&.D1
(D-one) Display-one.
Indent and display one text line.
.It Li \&.Dl
(D-ell) Display-one literal.
Indent and display one line of literal text.
.It Li \&.Bd
Begin-display block.
Display options:
.Bl -tag -width "xoffset string " -compact
.It Fl ragged
Unjustified (ragged edges).
.It Fl unfilled
Unfilled, unjustified.
.It Fl filled
Filled, and if
.Xr troff 1 ,
also justified.
.It Fl literal
Literal text or code.
.It Fl file Ar name
Read in named
.Ar file
and display.
.It Fl offset Ar string
Offset display.
Acceptable
.Ar string
values:
.Bl -tag -width indent-two -compact
.It Ar left
Align block on left (default).
.It Ar center
Approximate center margin.
.It Ar indent
Six constant width spaces (a tab).
.It Ar indent-two
Two tabs.
.It Ar right
Left aligns block 2 inches from
right.
.It Ar xx Ns Cm n
Where
.Ar xx
is a number from
.No \&4 Ns Cm n
to
.No \&9\&9 Ns Cm n .
.It Ar Aa
Where
.Ar Aa
is a callable macro name.
.It Ar string
The width of
.Ar string
is used.
.El
.El
.It Li \&.Ed
End-display (matches \&.Bd).
.It Li \&.Bl
Begin-list.
Create lists or columns.
Options:
.Bl -tag -width flag -compact
.It Em List-types
.Bl -column "xbullet " -compact
.It Fl bullet Ta "Bullet Item List"
.It Fl dash Ta "Dash Item List"
.It Fl hyphen Ta "(as per" Fl dash ")"
.It Fl item Ta "Unlabeled List"
.It Fl enum Ta "Enumerated List"
.It Fl tag Ta "Tag Labeled List"
.It Fl diag Ta "Diagnostic List"
.It Fl hang Ta "Hanging Labeled List"
.It Fl ohang Ta "Overhanging Labeled List"
.It Fl inset Ta "Inset or Run-on Labeled List"
.It Fl column Ta "Multiple Columns"
.El
.It Em List-parameters
.Bl -tag -width "xcompact " -compact
.It Fl offset
(All lists.) See
.Ql \&.Bd
begin-display above.
.It Fl width
.Pf ( Fl tag
and
.Fl hang
lists only.)
This parameter is effectively required for
.Fl tag
lists.
.It Fl compact
(All lists.)
Suppresses blank lines.
.El
.El
.It Li \&.El
End-list.
.It Li \&.It
List item.
.El
.Sh 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:
.Bl -tag -width ".Op Fl s Ar filex" -offset indent
.It Li "\&.Op Fl s Ar file"
Produces
.Op Fl s Ar file
.El
.Pp
In this example, the option enclosure macro
.Ql \&.Op
is parsed, and calls the callable content macro
.Ql \&Fl
which operates on the argument
.Ql s
and then calls the callable content macro
.Ql \&Ar
which operates on the argument
.Ql file .
Some macros may be callable but are not parsed, or vice versa.
These macros are indicated in the
.Em parsed
and
.Em callable
columns below.
.Pp
Unless stated, manual domain macros share a common syntax:
.Pp
.Dl \&.Va argument [\ .\ ,\ ;\ :\ ?\ !\ (\ )\ [\ ]\ argument \...\ ]
.Pp
.Sy Note :
Opening and closing
punctuation characters are only recognized as such if they are presented
one at a time.
The string
.Ql "),"
is not recognized as punctuation and will be output with a leading whitespace
and in whatever font the calling macro uses.
The
argument list
.Ql "] ) ,"
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
.Ql \e& .
For example the following string,
.Bl -tag -width "&.Ar file1\ , file2\ , file3\ )\ ." -offset indent
.It Li "\&.Ar file1\ , file2\ , file3\ )\ ."
Produces
.Ar file1 , file2 , file3 ) .
.El
.Ss Manual Domain Macros
.Bl -column "Name" "Parsed" "Callable" -compact
.It Em Name	Parsed	Callable	Description
.It Li \&Ad Ta Yes Ta Yes Ta Address. "(This macro may be deprecated.)"
.It Li \&An Ta Yes Ta \&No Ta "Author name."
.It Li \&Ar Ta Yes Ta Yes Ta "Command line argument."
.It Li \&Cd Ta \&No Ta \&No Ta "Configuration declaration."
.It Li \&Cm Ta Yes Ta Yes Ta "Command line argument modifier."
.It Li \&Dv Ta Yes Ta Yes Ta "Defined variable (source code)."
.It Li \&Er Ta Yes Ta Yes Ta "Error number (source code)."
.It Li \&Ev Ta Yes Ta Yes Ta "Environment variable."
.It Li \&Ex Ta \&No Ta \&No Ta "Exit values."
.It Li \&Fa Ta Yes Ta Yes Ta "Function argument."
.It Li \&Fd Ta \&No Ta \&No Ta "Function declaration."
.It Li \&Fl Ta Yes Ta Yes Ta "Flags."
.It Li \&Fn Ta Yes Ta Yes Ta "Function call (also .Fo and .Fc)."
.It Li \&Ft Ta Yes Ta Yes Ta "Function type."
.It Li \&Ic Ta Yes Ta Yes Ta "Interactive command."
.It Li \&In Ta \&No Ta \&No Ta "Include header file."
.It Li \&Li Ta Yes Ta Yes Ta "Literal text."
.It Li \&Nd Ta \&No Ta \&No Ta "Command description."
.It Li \&Nm Ta Yes Ta Yes Ta "Command name."
.It Li \&Op Ta Yes Ta Yes Ta "Option (also .Oo and .Oc)."
.It Li \&Ot Ta Yes Ta Yes Ta "Old style function type (Fortran only)."
.It Li \&Pa Ta Yes Ta Yes Ta "Pathname or file name."
.It Li \&Rv Ta \&No Ta \&No Ta "Return values."
.It Li \&St Ta Yes Ta Yes Ta "Standards (see below)."
.It Li \&Va Ta Yes Ta Yes Ta "Variable name."
.It Li \&Vt Ta Yes Ta Yes Ta "Variable type."
.It Li \&Xr Ta Yes Ta Yes Ta "Manual Page Cross Reference."
.El
.Pp
The known standards for the St macro are:
.Bd -ragged -offset 4n
-p1003.1-88, -p1003.1-90, -p1003.1-96, -p1003.1-2001, -p1003.1-2004,
-p1003.1, -p1003.1b, -p1003.1b-93, -p1003.1c-95, -p1003.1g-2000,
-p1003.2-92, -p1003.2-95, -p1003.2, -p1387.2, -isoC-90, -isoC-amd1,
-isoC-tcor1, -isoC-tcor2, isoC-99, -ansiC, -ansiC-89, -ansiC-99, -ieee754,
-iso8802-3, -xpg3, -xpg4, -xpg4.2, -xpg4.3, -xbd5, -xcu5, -xsh5, -xns5,
-xns5.2d2.0, -xcurses4.2, -susv2, -susv3, and -svid4.
.Ed
.Ss General Text Domain Macros
.Bl -column "Name" "Parsed" "Callable" -compact
.It Em "Name	Parsed	Callable	Description"
.It Li \&%A Ta Yes Ta \&No Ta "Reference author."
.It Li \&%B Ta Yes Ta Yes Ta "Reference book title."
.It Li \&%\&D Ta \&No Ta \&No Ta "Reference date."
.It Li \&%I Ta Yes Ta Yes Ta "Issuer/Publisher name."
.It Li \&%J Ta Yes Ta Yes Ta "Reference journal title."
.It Li \&%N Ta \&No Ta \&No Ta "Reference issue number."
.It Li \&%\&O Ta \&No Ta \&No Ta "Reference optional information."
.It Li \&%P Ta \&No Ta \&No Ta "Reference page number(s)."
.It Li \&%R Ta \&No Ta \&No Ta "Reference report Name."
.It Li \&%T Ta Yes Ta Yes Ta "Reference article title."
.It Li \&%V Ta \&No Ta \&No Ta "Reference volume."
.It Li \&Ac Ta Yes Ta Yes Ta "Angle close quote."
.It Li \&Ao Ta Yes Ta Yes Ta "Angle open quote."
.It Li \&Aq Ta Yes Ta Yes Ta "Angle quote."
.It Li \&At Ta \&No Ta \&No Ta Tn "AT&T UNIX."
.It Li \&Bc Ta Yes Ta Yes Ta "Bracket close quote."
.It Li \&Bf Ta \&No Ta \&No Ta "Begin font mode."
.It Li \&Bo Ta Yes Ta Yes Ta "Bracket open quote."
.It Li \&Bq Ta Yes Ta Yes Ta "Bracket quote."
.It Li \&Bsx Ta Yes Ta \&No Ta "BSDI BSD/OS."
.It Li \&Bx Ta Yes Ta \&No Ta BSD .
.It Li \&Db Ta \&No Ta \&No Ta "Debug (default is \\*qoff\\*q)."
.It Li \&Dc Ta Yes Ta Yes Ta "Double close quote."
.It Li \&Do Ta Yes Ta Yes Ta "Double open quote."
.It Li \&Dq Ta Yes Ta Yes Ta "Double quote."
.It Li \&Ec Ta Yes Ta Yes Ta "Enclose string close quote."
.It Li \&Ef Ta \&No Ta \&No Ta "End font mode."
.It Li \&Em Ta Yes Ta Yes Ta "Emphasis (traditional English)."
.It Li \&Eo Ta Yes Ta Yes Ta "Enclose string open quote."
.It Li \&Fx Ta Yes Ta \&No Ta FreeBSD .
.It Li \&Ms Ta Yes Ta \&No Ta "Mathematical symbol."
.It Li \&No Ta Yes Ta Yes Ta "Normal text (no-op)."
.It Li \&Ns Ta Yes Ta Yes Ta "No space."
.It Li \&Nx Ta Yes Ta \&No Ta NetBSD .
.It Li \&Ox Ta Yes Ta \&No Ta OpenBSD .
.It Li \&Pc Ta Yes Ta Yes Ta "Parenthesis close quote."
.It Li \&Pf Ta Yes Ta \&No Ta "Prefix string."
.It Li \&Po Ta Yes Ta Yes Ta "Parenthesis open quote."
.It Li \&Pq Ta Yes Ta Yes Ta "Parentheses quote."
.It Li \&Qc Ta Yes Ta Yes Ta "Straight double close quote."
.It Li \&Ql Ta Yes Ta Yes Ta "Quoted literal."
.It Li \&Qo Ta Yes Ta Yes Ta "Straight double open quote."
.It Li \&Qq Ta Yes Ta Yes Ta "Straight double quote."
.It Li \&Re Ta \&No Ta \&No Ta "Reference end."
.It Li \&Rs Ta \&No Ta \&No Ta "Reference start."
.It Li \&Sc Ta Yes Ta Yes Ta "Single close quote."
.It Li \&So Ta Yes Ta Yes Ta "Single open quote."
.It Li \&Sq Ta Yes Ta Yes Ta "Single quote."
.It Li \&Sm Ta \&No Ta \&No Ta "Space mode (default is \\*qon\\*q)."
.It Li \&Sx Ta Yes Ta Yes Ta "Section Cross Reference."
.It Li \&Sy Ta Yes Ta Yes Ta "Symbolic (traditional English)."
.It Li \&Tn Ta Yes Ta Yes Ta "Trade or type name (small Caps)."
.It Li \&Ux Ta Yes Ta \&No Ta UNIX .
.It Li \&Xc Ta Yes Ta Yes Ta "Extend argument list close."
.It Li \&Xo Ta Yes Ta Yes Ta "Extend argument list open."
.El
.\" .It Sy \&Hf Ta \&No Ta \&No Ta "Include file with header"
.Pp
Macro names ending in
.Ql q
quote remaining items on the argument list.
Macro names ending in
.Ql o
begin a quote which may span more than one line of input and
are close quoted with the matching macro name ending in
.Ql c .
Enclosure macros may be nested and are limited to
eight arguments.
.Pp
Note: the extended argument list macros
.Pf ( Ql \&.Xo ,
.Ql \&.Xc )
and the function enclosure macros
.Pf ( Ql \&.Fo ,
.Ql \&.Fc )
are irregular.
The extended list macros are used when the number of macro arguments
would exceed the
.Xr troff 1
limitation of nine arguments.
.Sh FILES
.Bl -tag -width "/usr/share/misc/mdoc.template" -compact
.It Pa tmac.doc
manual macro package
.It Pa tmac.doc-common
common structural macros and definitions
.It Pa tmac.doc-ditroff
site dependent
.Xr troff 1
style file
.It Pa tmac.doc-nroff
site dependent
.Xr nroff 1
style file
.It Pa tmac.doc-syms
special defines
.It Pa /usr/share/misc/mdoc.template
template for writing a man page
.El
.Sh SEE ALSO
.Xr groff 1 ,
.Xr man 1 ,
.Xr nroff 1 ,
.Xr troff 1 ,
.Xr mdoc.samples 7