MDOC(7) | NetBSD Miscellaneous Information Manual | MDOC(7) |
An mdoc document follows simple rules: lines beginning with the control character ‘'. are parsed for macros. Other lines are interpreted within the scope of prior macros:
.Sh Macro lines change control state. Other lines are interpreted within the current state.
If the first character of a line is a space, that line is printed with a leading newline.
Use of reserved terms is described in MACRO SYNTAX. For general use in macro lines, these can be escaped with a non-breaking space (‘\&').
\fBbold\fR \fIitalic\fP
A numerical representation 3, 2, or 1 (bold, italic, and Roman, respectively) may be used instead. A text decoration is valid within the current font scope only: if a macro opens a font scope alongside its own scope, such as Bf Sy, in-scope invocations of ‘\f' are only valid within the font scope of the macro. If ‘\f' is specified outside of any font scope, such as in unenclosed, free-form text, it will affect the remainder of the document.
Note this form is not recommended for mdoc, which encourages semantic annotation.
In macro lines, whitespace delimits arguments and is discarded. If arguments are quoted, whitespace within the quotes is retained.
Note that any quoted text, even if it would cause a macro invocation when unquoted, is considered literal text. Thus, the following produces ‘[Fl a]':
.Op "Fl a"
In free-form mode, quotes are regarded as opaque text.
.Bl -tag -width 2i
The syntax for scaled widths is ‘[+-]?[0-9]*.[0-9]*[:unit:]', where a decimal must be preceded or proceeded by at least one digit. Negative numbers, while accepted, are truncated to zero. The following scaling units are accepted:
Using anything other than ‘m', ‘n', ‘u', or ‘v' is necessarily non-portable across output media. See COMPATIBILITY.
The proper spacing is also intelligently preserved if a sentence ends at the boundary of a macro line. For example:
Xr mandoc 1.
Fl T Ns Cm ascii.
The prologue, which consists of the Dd, Dt, and Os macros in that order, is required for every document.
The first section (sections are denoted by Sh) must be the NAME section, consisting of at least one Nm followed by Nd.
Following that, convention dictates specifying at least the SYNOPSIS and DESCRIPTION sections, although this varies between manual sections.
The following is a well-formed skeleton mdoc file:
.Dd $Mdocdate$ .Dt mdoc 7 .Os .Sh NAME .Nm foo .Nd a description goes here .\" .Sh LIBRARY .\" For sections 2, 3, & 9 only. .\" Not used in OpenBSD. .Sh SYNOPSIS .Nm foo .Op Fl options .Ar .Sh DESCRIPTION The .Nm utility processes files ... .\" .Sh IMPLEMENTATION NOTES .\" Not used in OpenBSD. .\" .Sh RETURN VALUES .\" For sections 2, 3, & 9 only. .\" .Sh ENVIRONMENT .\" For sections 1, 6, 7, & 8 only. .\" .Sh FILES .\" .Sh EXIT STATUS .\" For sections 1, 6, & 8 only. .\" .Sh EXAMPLES .\" .Sh DIAGNOSTICS .\" For sections 1, 4, 6, 7, & 8 only. .\" .Sh ERRORS .\" For sections 2, 3, & 9 only. .\" .Sh SEE ALSO .\" .Xr foobar 1 .\" .Sh STANDARDS .\" .Sh HISTORY .\" .Sh AUTHORS .\" .Sh CAVEATS .\" .Sh BUGS .\" .Sh SECURITY CONSIDERATIONS .\" Not used in OpenBSD.
The sections in an mdoc document are conventionally ordered as they appear above. Sections should be composed as follows:
.Nm name0 , .Nm name1 , .Nm name2 .Nd a one line description
.Lb libarm
See Lb.
For the first, utilities (sections 1, 6, and 8), this is generally structured as follows:
.Nm foo .Op Fl v .Op Fl o Ar file .Op Ar .Nm bar .Op Fl v .Op Fl o Ar file .Op Ar
For the second, function calls (sections 2, 3, 9):
.In header.h .Vt extern const char *global; .Ft "char *" .Fn foo "const char *src" .Ft "char *" .Fn bar "const char *src"
And for the third, configurations (section 4):
.Cd "it* at isa? port 0x2e" .Cd "it* at isa? port 0x4e"
Manuals not in these sections generally don't need a SYNOPSIS.
Some macros are displayed differently in the SYNOPSIS section, particularly Nm, Cd, Fd, Fn, Fo, In, Vt, and Ft. All of these macros are output on their own line. If two such dissimilar macros are pairwise invoked (except for Ft before Fo or Fn), they are separated by a vertical space, unless in the case of Fo, Fn, and Ft, which are always separated by vertical space.
When text and macros following an Nm macro starting an input line span multiple output lines, all output lines but the first will be indented to align with the text immediately following the Nm macro, up to the next Nm, Sh, or Ss macro or the end of an enclosing block, whichever comes first.
The arguments are as follows: .Bl -tag -width Ds .It Fl v Print verbose information. .El
Manuals not documenting a command won't include the above fragment.
See Rv.
See Ev.
See Pa.
See Ex.
See Bl -diag.
See Er.
See Xr.
See St.
See An.
.Pp . Pp
The syntax of a macro depends on its classification. In this section, ‘-arg' refers to macro arguments, which may be followed by zero or more ‘parm' parameters; ‘Yo' opens the scope of a macro; and if specified, ‘Yc' closes it out.
The Callable column indicates that the macro may also be called by passing its name as an argument to another macro. If a macro is not callable but its name appears as an argument to another macro, it is interpreted as opaque text. For example, ‘.Fl Sh' produces ‘-Sh'.
The Parsed column indicates whether the macro may call other macros by receiving their names as arguments. If a macro is not parsed but the name of another macro appears as an argument, it is interpreted as opaque text.
The Scope column, if applicable, describes closure rules.
.Yo [-arg [parm...]] [head...] [body...] .Yc
Macro | Callable | Parsed | Scope |
Bd | No | No | closed by Ed |
Bf | No | No | closed by Ef |
Bk | No | No | closed by Ek |
Bl | No | No | closed by El |
Ed | No | No | opened by Bd |
Ef | No | No | opened by Bf |
Ek | No | No | opened by Bk |
El | No | No | opened by Bl |
.Yo [-arg [parm...]] [head... [Ta head...]] [body...]
Macro | Callable | Parsed | Scope |
It | No | Yes | closed by It, El |
Nd | No | No | closed by Sh |
Nm | No | Yes | closed by Nm, Sh, Ss |
Sh | No | No | closed by Sh |
Ss | No | No | closed by Sh, Ss |
Note that the Nm macro is a Block full-implicit macro only when invoked as the first macro in a SYNOPSIS section line, else it is In-line.
.Yo [-arg [parm...]] [head...] [body...] .Yc [tail...] .Yo [-arg [parm...]] [head...] [body...] Yc [tail...]
Macro | Callable | Parsed | Scope |
Ac | Yes | Yes | opened by Ao |
Ao | Yes | Yes | closed by Ac |
Bc | Yes | Yes | closed by Bo |
Bo | Yes | Yes | opened by Bc |
Brc | Yes | Yes | opened by Bro |
Bro | Yes | Yes | closed by Brc |
Dc | Yes | Yes | opened by Do |
Do | Yes | Yes | closed by Dc |
Ec | Yes | Yes | opened by Eo |
Eo | Yes | Yes | closed by Ec |
Fc | Yes | Yes | opened by Fo |
Fo | No | No | closed by Fc |
Oc | Yes | Yes | closed by Oo |
Oo | Yes | Yes | opened by Oc |
Pc | Yes | Yes | closed by Po |
Po | Yes | Yes | opened by Pc |
Qc | Yes | Yes | opened by Oo |
Qo | Yes | Yes | closed by Oc |
Re | No | No | opened by Rs |
Rs | No | No | closed by Re |
Sc | Yes | Yes | opened by So |
So | Yes | Yes | closed by Sc |
Xc | Yes | Yes | opened by Xo |
Xo | Yes | Yes | closed by Xc |
.Yo [-arg [val...]] [body...] [res...]
Macro | Callable | Parsed |
Aq | Yes | Yes |
Bq | Yes | Yes |
Brq | Yes | Yes |
D1 | No | Yes |
Dl | No | Yes |
Dq | Yes | Yes |
Op | Yes | Yes |
Pq | Yes | Yes |
Ql | Yes | Yes |
Yes | Yes | |
Sq | Yes | Yes |
Vt | Yes | Yes |
Note that the Vt macro is a Block partial-implicit only when invoked as the first macro in a SYNOPSIS section line, else it is In-line.
.Yo [-arg [val...]] [args...] [res...] .Yo [-arg [val...]] [args...] Yc... .Yo [-arg [val...]] arg0 arg1 argN
Macro | Callable | Parsed | Arguments |
%A | No | No | >0 |
%B | No | No | >0 |
%C | No | No | >0 |
%D | No | No | >0 |
%I | No | No | >0 |
%J | No | No | >0 |
%N | No | No | >0 |
%O | No | No | >0 |
%P | No | No | >0 |
%Q | No | No | >0 |
%R | No | No | >0 |
%T | No | No | >0 |
%U | No | No | >0 |
%V | No | No | >0 |
Ad | Yes | Yes | >0 |
An | Yes | Yes | >0 |
Ap | Yes | Yes | 0 |
Ar | Yes | Yes | n |
At | Yes | Yes | 1 |
Bsx | Yes | Yes | n |
Bt | No | No | 0 |
Bx | Yes | Yes | n |
Cd | Yes | Yes | >0 |
Cm | Yes | Yes | >0 |
Db | No | No | 1 |
Dd | No | No | n |
Dt | No | No | n |
Dv | Yes | Yes | >0 |
Dx | Yes | Yes | n |
Em | Yes | Yes | >0 |
En | No | No | 0 |
Er | Yes | Yes | >0 |
Es | No | No | 0 |
Ev | Yes | Yes | >0 |
Ex | No | No | n |
Fa | Yes | Yes | >0 |
Fd | No | No | >0 |
Fl | Yes | Yes | n |
Fn | Yes | Yes | >0 |
Fr | No | No | n |
Ft | Yes | Yes | >0 |
Fx | Yes | Yes | n |
Hf | No | No | n |
Ic | Yes | Yes | >0 |
In | No | No | 1 |
Lb | No | No | 1 |
Li | Yes | Yes | >0 |
Lk | Yes | Yes | >0 |
Lp | No | No | 0 |
Ms | Yes | Yes | >0 |
Mt | Yes | Yes | >0 |
Nm | Yes | Yes | n |
No | Yes | Yes | 0 |
Ns | Yes | Yes | 0 |
Nx | Yes | Yes | n |
Os | No | No | n |
Ot | No | No | n |
Ox | Yes | Yes | n |
Pa | Yes | Yes | n |
Pf | Yes | Yes | 1 |
Pp | No | No | 0 |
Rv | No | No | n |
Sm | No | No | 1 |
St | No | Yes | 1 |
Sx | Yes | Yes | >0 |
Sy | Yes | Yes | >0 |
Tn | Yes | Yes | >0 |
Ud | No | No | 0 |
Ux | Yes | Yes | n |
Va | Yes | Yes | n |
Vt | Yes | Yes | >0 |
Xr | Yes | Yes | >0 |
br | No | No | 0 |
sp | No | No | 1 |
Examples:
.Ad [0,$]
.Ad 0x00000000
The default is -nosplit. The effect of selecting either of the -split modes ends at the beginning of the AUTHORS section. In the AUTHORS section, the default is -nosplit for the first author listing and -split for all other author listings.
Examples:
.An -nosplit
.An Kristaps Dzonsons Aq kristaps@bsd.lv
Examples:
.Fl -key= Ns Ao Ar val Ac
See also Aq.
Examples:
.Fn execve Ap d
Examples:
.Fl -key= Ns Aq Ar val
Remarks: this macro is often abused for rendering URIs, which should instead use Lk or Mt, or to note pre-processor “#include” statements, which should use In.
See also Ao.
Examples:
.Fl o Ns Ar file1
.Ar
.Ar arg1, arg2.
Note that these arguments do not begin with a hyphen.
Examples:
.At
.At V.1
Display blocks are used to select a different indentation and justification than the one used by the surrounding text. They may contain both macro lines and free-form text lines. By default, a display block is preceded by a vertical space.
The type must be one of the following:
The type must be provided first. Additional arguments may follow:
When the argument is missing, -offset is ignored.
Examples:
.Bd -literal -offset indent -compact Hello world. .Ed
The -emphasis and Em argument are equivalent, as are -symbolic and Sy, and -literal and Li. Without an argument, this macro does nothing. The font mode continues until broken by a new font mode in a nested scope or Ef is encountered.
.Bk -words
The -words argument is required; additional arguments are ignored.
The following example will not break within each Op macro line:
.Bk -words .Op Fl f Ar flags .Op Fl o Ar output .Ek
Be careful in using over-long lines within a keep block! Doing so will clobber the right margin.
The list type is mandatory and must be specified first. The -width and -offset arguments accept Scaling Widths or use the length of the given string. The -offset is a global indentation for the whole list, affecting both item heads and bodies. For those list types supporting it, the -width argument requests an additional indentation of item bodies, to be added to the -offset. Unless the -compact argument is specified, list entries are separated by vertical space.
A list must specify one of the following list types:
Examples:
.Bo 1 , .Dv BUFSIZ Bc
See also Bq.
Examples:
.Bq 1, Dv BUFSIZ
Remarks: this macro is sometimes abused to emulate optional arguments for commands; the correct macros to use for this purpose are Op, Oo, and Oc.
See also Bo.
Examples:
.Bro 1 , ... , .Va n Brc
See also Brq.
Examples:
.Bsx 1.0
.Bsx
Examples:
.Bx 4.4
.Bx
Examples:
.Cd device le0 at scode?
Remarks: this macro is commonly abused by using quoted literals to retain whitespace and align consecutive Cd declarations. This practise is discouraged.
Examples:
.Cm ControlPath
.Cm ControlMaster
See also Fl.
Examples:
.D1 Fl abcdefgh
.Db on | off
This macro is ignored by mandoc(1).
.Dd month day, year
The month is the full English month name, the day is an optionally zero-padded numeral, and the year is the full four-digit year.
Other arguments are not portable; the mandoc(1) utility handles them as follows:
Examples:
.Dd $Mdocdate$
.Dd $Mdocdate: July 21 2007$
.Dd July 21, 2007
Examples:
.Dl % mandoc mdoc.7 \(ba less
Examples:
.Do April is the cruellest month .Dc \(em T.S. Eliot
See also Dq.
Examples:
.Dq April is the cruellest month \(em T.S. Eliot
Its arguments are as follows:
Examples:
.Dt FOO 1
.Dt FOO 4 KM
.Dt FOO 9 i386
Examples:
.Dv BUFSIZ
.Dv STDOUT_FILENO
See also Er.
Examples:
.Dx 2.4.1
.Dx
.Ec [TERM]
The TERM argument is used as the enclosure tail, for example, specifying \(rq will emulate Dc.
Examples:
.Em Warnings!
.Em Remarks:
.Eo [TERM]
The TERM argument is used as the enclosure head, for example, specifying \(lq will emulate Do.
.Ex -std [utility]
When utility is not specified, the document's name set by Nm is used.
See also Rv.
This may be invoked for names with or without the corresponding type. It is also used to specify the field name of a structure. Most often, the Fa macro is used in the SYNOPSIS within Fo section when documenting multi-line function prototypes. If invoked with multiple arguments, the arguments are separated by a comma. Furthermore, if the following macro is another Fa, the last argument will also have a trailing comma.
Examples:
.Fa "const char *p"
.Fa "int a" "int b" "int c"
.Fa foo
See also Fo.
See also MANUAL STRUCTURE and In.
Examples:
.Fl a b c
.Fl Pf a b
.Fl
.Op Fl o Ns Ar file
See also Cm.
Function arguments are surrounded in parenthesis and are delimited by commas. If no arguments are specified, blank parenthesis are output.
Examples:
.Fn "int funcname" "int arg0" "int arg1"
.Fn funcname "int arg0"
.Fn funcname arg0
.Ft functype .Fn funcname
When referring to a function documented in another manual page, use Xr instead. See also MANUAL STRUCTURE and Ft.
.Fo funcname
Invocations usually occur in the following context:
A Fo scope is closed by
See also MANUAL STRUCTURE, Fa, Fc, and Ft.
.Ft functype
Examples:
.Ft int
.Ft functype .Fn funcname
See also MANUAL STRUCTURE, Fn, and Fo.
Examples:
.Fx 7.1
.Fx
Examples:
.Ic hash
.Ic alias
Note that using Bd -literal or D1 is preferred for displaying code; the Ic macro is used when referring to specific instructions.
Examples:
.In sys/types
See also MANUAL STRUCTURE.
Lists of type -hang, -ohang, -inset, and -diag have the following syntax:
.It args
Lists of type -bullet, -dash, -enum, -hyphen and -item have the following syntax:
.It
with subsequent lines interpreted within the scope of the It until either a closing El or another It.
The -tag list has the following syntax:
.It [args]
Subsequent lines are interpreted as with -bullet and family. The line arguments correspond to the list's left-hand side; body arguments correspond to the list's contents.
The -column list is the most complicated. Its syntax is as follows:
.It [args]
The args are phrases, a mix of macros and text corresponding to a line column, delimited by tabs or the special ‘Ta' pseudo-macro. Lines subsequent the It are interpreted within the scope of the last phrase. Calling the pseudo-macro ‘Ta' will open a new phrase scope (this must occur on a macro line to be interpreted as a macro). Note that the tab phrase delimiter may only be used within the It line itself. Subsequent this, only the ‘Ta' pseudo-macro may be used to delimit phrases. Furthermore, note that quoted sections propagate over tab-delimited phrases on an It, for example,
.It "col1; <TAB> col2 ;" ;
will preserve the semicolon whitespace except for the last.
See also Bl.
.Lb library
The library parameter may be a system library, such as libz or libpam, in which case a small library description is printed next to the linker invocation; or a custom library, in which case the library name is printed in quotes. This is most commonly used in the SYNOPSIS section as described in MANUAL STRUCTURE.
Examples:
.Lb libz
.Lb mdoc
.Lk uri [name]
Examples:
.Lk http://bsd.lv "The BSD.lv Project"
.Lk http://bsd.lv
See also Mt.
.Ms symbol
Examples:
.Ms sigma
.Ms aleph
.Mt address
Examples:
.Mt discuss@manpages.bsd.lv
Examples:
.Sx Nd mdoc language reference
.Sx Nd format and display UNIX manuals
The Nd macro technically accepts child macros and terminates with a subsequent Sh invocation. Do not assume this behaviour: some whatis(1) database generators are not smart enough to parse more than the line arguments and will display macros verbatim.
See also Nm.
Examples:
.Sh SYNOPSIS .Nm cat .Op Fl benstuv .Op Ar
In the SYNOPSIS of section 2, 3 and 9 manual pages, use the Fn macro rather than Nm to mark up the name of the manual page.
Examples:
.Sx Fl ab No cd Fl ef
This has no effect when invoked at the start of a macro line.
Examples:
.Fl o Ns Ar output
Examples:
.Nx 5.01
.Nx
Examples:
.Op Fl a Ar b
.Op Ar a | b
See also Oo.
.Os [system [version]]
The optional system parameter specifies the relevant operating system or environment. Left unspecified, it defaults to the local operating system version. This is the suggested form.
Examples:
.Os
.Os KTH/CSC/TCS
.Os BSD 4.3
Remarks: this macro has been deprecated.
Examples:
.Ox 4.5
.Ox
Examples:
.Pa /usr/bin/mandoc
.Pa /usr/share/man/man7/mdoc.7
See also Lk.
.Pf prefix suffix
The suffix argument may be a macro.
Examples:
.Pf \. Sx Pf Cm prefix suffix
See also Po.
Examples:
.Rs .%A J. E. Hopcroft .%A J. D. Ullman .%B Introduction to Automata Theory, Languages, and Computation .%I Addison-Wesley .%C Reading, Massachusettes .%D 1979 .Re
If an Rs block is used within a SEE ALSO section, a vertical space is asserted before the rendered output, else the block continues on the current line.
See also Ex.
Section names should be unique so that they may be keyed by Sx.
.Sm on | off
By default, spacing is on. When switched off, no white space is inserted between macro arguments and between the output generated from adjacent macros, but free-form text lines still get normal spacing between words and sentences.
Sub-section names should be unique so that they may be keyed by Sx.
Examples:
.Sx MANUAL STRUCTURE
Examples:
.Tn IBM
Examples:
.Ux
Examples:
.Va foo
.Va const char *bar;
Note that this should not be confused with Ft, which is used for function return types.
Examples:
.Vt unsigned char
.Vt extern const char * const sys_signame[] ;
See also MANUAL STRUCTURE and Va.
.Xr name section
The name and section are the name and section of the linked manual. If section is followed by non-punctuation, an Ns is inserted into the token stream. This behaviour is for compatibility with GNU troff.
Examples:
.Xr mandoc 1
.Xr mandoc 1 ;
.Xr mandoc 1 Ns s behaviour
Consider using Pp in the event of natural paragraph breaks.
.sp [height]
The height argument must be formatted as described in Scaling Widths. If unspecified, sp asserts a single vertical space.
Heirloom troff, the other significant troff implementation accepting -mdoc, is similar to historic groff.
The following problematic behaviour is found in groff:
The following features are unimplemented in mandoc:
April 1, 2011 | NetBSD 5.99 |