-.\" $Id: mdoc.7,v 1.211 2011/09/26 23:07:31 schwarze Exp $
+.\" $Id: mdoc.7,v 1.222 2013/11/02 20:39:49 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: September 26 2011 $
+.Dd $Mdocdate: November 2 2013 $
.Dt MDOC 7
.Os
.Sh NAME
.Op Fl offset Ar val
.Op Fl compact
.It Sx \&It Ta list item (syntax depends on Fl Ar type )
-.It Sx \&Ta Ta table cell separator in Sx Bl Fl column No lists
+.It Sx \&Ta Ta table cell separator in Sx \&Bl Fl column No lists
.It Sx \&Rs , \&%* , \&Re Ta bibliographic block (references)
.El
.Ss Spacing control
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Lb Ta function library (one argument)
.It Sx \&In Ta include file (one argument)
+.It Sx \&Fd Ta other preprocessor directive (>0 arguments)
.It Sx \&Ft Ta function type (>0 arguments)
.It Sx \&Fo , \&Fc Ta function block: Ar funcname
.It Sx \&Fn Ta function name:
.Pp
Examples:
.Dl \&.An -nosplit
-.Dl \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv
+.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
.Ss \&Ao
Begin a block enclosed by angle brackets.
Does not have any head arguments.
or
.Sx \&Cm .
.Ss \&At
-Formats an AT&T version.
+Formats an
+.At
+version.
Accepts one optional argument:
.Pp
.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
which resolves to
.Sy 6n .
.It
-A width using the syntax described in
-.Sx Scaling Widths .
+A scaling width as described in
+.Xr roff 7 .
.It
An arbitrary string, which indents by the length of this string.
.El
.Fl width
and
.Fl offset
-arguments accept
-.Sx Scaling Widths
+arguments accept scaling widths as described in
+.Xr roff 7
or use the length of the given string.
The
.Fl offset
The
.Fl width
argument has no effect; instead, each argument specifies the width
-of one column, using either the
-.Sx Scaling Widths
-syntax or the string length of the argument.
+of one column, using either the scaling width syntax described in
+.Xr roff 7
+or the string length of the argument.
If the first line of the body of a
.Fl column
list is not an
See also
.Sx \&Bro .
.Ss \&Bsx
-Format the BSD/OS version provided as an argument, or a default value if
+Format the
+.Bsx
+version provided as an argument, or a default value if
no argument is provided.
.Pp
Examples:
Prints
.Dq is currently in beta test.
.Ss \&Bx
-Format the BSD version provided as an argument, or a default value if no
+Format the
+.Bx
+version provided as an argument, or a default value if no
argument is provided.
.Pp
Examples:
.Ar title
.Oo
.Ar section
-.Op Ar volume | arch
+.Op Ar volume
+.Op Ar arch
.Oc
.Oc
.Ed
.Ar CON
.Pq contributed manuals .
.It Ar arch
-This specifies a specific relevant architecture.
-If
-.Ar volume
-is not provided, it may be used in its place, else it may be used
-subsequent that.
-It, too, is optional.
-It must be one of
-.Ar alpha ,
-.Ar amd64 ,
-.Ar amiga ,
-.Ar arc ,
-.Ar arm ,
-.Ar armish ,
-.Ar aviion ,
-.Ar hp300 ,
-.Ar hppa ,
-.Ar hppa64 ,
-.Ar i386 ,
-.Ar landisk ,
-.Ar loongson ,
-.Ar luna88k ,
-.Ar mac68k ,
-.Ar macppc ,
-.Ar mips64 ,
-.Ar mvme68k ,
-.Ar mvme88k ,
-.Ar mvmeppc ,
-.Ar pmax ,
-.Ar sgi ,
-.Ar socppc ,
-.Ar sparc ,
-.Ar sparc64 ,
-.Ar sun3 ,
-.Ar vax ,
+This specifies the machine architecture a manual page applies to,
+where relevant, for example
+.Cm alpha ,
+.Cm amd64 ,
+.Cm i386 ,
or
-.Ar zaurus .
+.Cm sparc64 .
+The list of supported architectures varies by operating system.
+For the full list of all architectures recognized by
+.Xr mandoc 1 ,
+see the file
+.Pa arch.in
+in the source distribution.
.El
.Pp
Examples:
.Sx \&Er
and
.Sx \&Ev
-for special-purpose constants and
+for special-purpose constants,
.Sx \&Va
-for variable symbols.
+for variable symbols, and
+.Sx \&Fd
+for listing preprocessor variable definitions in the
+.Em SYNOPSIS .
.Ss \&Dx
-Format the DragonFly BSD version provided as an argument, or a default
+Format the
+.Dx
+version provided as an argument, or a default
value if no argument is provided.
.Pp
Examples:
End a function context started by
.Sx \&Fo .
.Ss \&Fd
-Historically used to document include files.
-This usage has been deprecated in favour of
+Preprocessor directive, in particular for listing it in the
+.Em SYNOPSIS .
+Historically, it was also used to document include files.
+The latter usage has been deprecated in favour of
.Sx \&In .
-Do not use this macro.
+.Pp
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Fd
+.Li # Ns Ar directive
+.Op Ar argument ...
+.Ed
+.Pp
+Examples:
+.Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler
+.Dl \&.Fd #define SIO_MAXNFDS
+.Dl \&.Fd #ifdef FS_DEBUG
+.Dl \&.Ft void
+.Dl \&.Fn dbg_open \(dqconst char *\(dq
+.Dl \&.Fd #endif
.Pp
See also
-.Sx MANUAL STRUCTURE
+.Sx MANUAL STRUCTURE ,
+.Sx \&In ,
and
-.Sx \&In .
+.Sx \&Dv .
.Ss \&Fl
Command-line flag or option.
Used when listing arguments to command-line utilities.
.Pp
Examples:
.Dl \&.Lb libz
-.Dl \&.Lb mdoc
+.Dl \&.Lb libmandoc
.Ss \&Li
Denotes text that should be in a
.Li literal
.Pp
Examples:
.Dl \&.Mt discuss@manpages.bsd.lv
+.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
.Ss \&Nd
A one line description of the manual's content.
This may only be invoked in the
.Xr mandoc 1 .
.Pp
Historical
-.Xr mdoc 7
+.Nm
packages described it as
.Dq "old function type (FORTRAN)" .
.Ss \&Ox
.St -p1003.1b-93
.It \-p1003.1c-95
.St -p1003.1c-95
+.It \-p1003.1d-99
+.St -p1003.1d-99
.It \-p1003.1g-2000
.St -p1003.1g-2000
.It \-p1003.1i-95
.St -p1003.1i-95
+.It \-p1003.1j-2000
+.St -p1003.1j-2000
+.It \-p1003.1q-2000
+.St -p1003.1q-2000
+.It \-p1003.2
+.St -p1003.2
.It \-p1003.2-92
.St -p1003.2-92
.It \-p1003.2a-92
.St -p1003.2a-92
-.It \-p1387.2-95
-.St -p1387.2-95
-.It \-p1003.2
-.St -p1003.2
.It \-p1387.2
.St -p1387.2
+.It \-p1387.2-95
+.St -p1387.2-95
.It \-isoC
.St -isoC
.It \-isoC-90
.St -isoC-tcor2
.It \-isoC-99
.St -isoC-99
+.It \-isoC-2011
+.St -isoC-2011
.It \-iso9945-1-90
.St -iso9945-1-90
.It \-iso9945-1-96
Prints out
.Dq currently under development.
.Ss \&Ux
-Format the UNIX name.
+Format the
+.Ux
+name.
Accepts no argument.
.Pp
Examples:
.Pq Qq cross-reference .
Its syntax is as follows:
.Pp
-.D1 Pf \. Sx \&Xr Ar name section
+.D1 Pf \. Sx \&Xr Ar name Op section
.Pp
-The
+Cross reference the
.Ar name
and
.Ar section
-are the name and section of the linked manual.
-If
-.Ar section
-is followed by non-punctuation, an
-.Sx \&Ns
-is inserted into the token stream.
-This behaviour is for compatibility with
-GNU troff.
+number of another man page;
+omitting the section number is rarely useful.
.Pp
Examples:
.Dl \&.Xr mandoc 1
.Pp
The
.Ar height
-argument must be formatted as described in
-.Sx Scaling Widths .
+argument is a scaling width as described in
+.Xr roff 7 .
If unspecified,
.Sx \&sp
asserts a single vertical space.
.Ql \ef
font escape sequences is never required.
.Sh COMPATIBILITY
-This section documents compatibility between mandoc and other other
+This section documents compatibility between mandoc and other
troff implementations, at this time limited to GNU troff
.Pq Qq groff .
The term
The
.Nm
reference was written by
-.An Kristaps Dzonsons ,
-.Mt kristaps@bsd.lv .
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
git.ckatri.com / mandoc.git / blobdiff