![]() |
![]()
| ![]() |
![]()
NAMEmdoc —
semantic markup language for formatting manual
pages
DESCRIPTIONThemdoc language supports authoring of
manual pages for the
man(1)
utility by allowing semantic annotations of words, phrases, page sections and
complete manual pages. Such annotations are used by formatting tools to
achieve a uniform presentation across all manuals written in
mdoc , and to support hyperlinking if
supported by the output medium.
This reference document describes the structure of manual pages and the syntax
and usage of the mdoc language. The
reference implementation of a parsing and formatting tool is
mandoc(1);
the COMPATIBILITY section
describes compatibility with other implementations.
In an mdoc document, lines beginning with the
control character ‘.’ are called “macro lines”.
The first word is the macro name. It consists of two or three letters. Most
macro names begin with a capital letter. For a list of available macros, see
MACRO OVERVIEW. The words
following the macro name are arguments to the macro, optionally including the
names of other, callable macros; see
MACRO SYNTAX for details.
Lines not beginning with the control character are called “text
lines”. They provide free-form text to be printed; the formatting of
the text depends on the respective processing context:
.Sh Macro lines change control state. Text lines are interpreted within the current state. mdoc
language are based on the
roff(7)
language; see the LANGUAGE SYNTAX and
MACRO SYNTAX sections in the
roff(7)
manual for details, in particular regarding comments, escape sequences,
whitespace, and quoting. However, using
roff(7)
requests in mdoc documents is discouraged;
mandoc(1)
supports some of them merely for backward compatibility.
MANUAL STRUCTUREA well-formedmdoc document consists of a
document prologue followed by one or more sections.
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 for a utility “progname”:
.Dd $Mdocdate$ .Dt PROGNAME section .Os .Sh NAME .Nm progname .Nd one line about what it does .\" .Sh LIBRARY .\" For sections 2, 3, and 9 only. .\" Not used in OpenBSD. .Sh SYNOPSIS .Nm progname .Op Fl options .Ar .Sh DESCRIPTION The .Nm utility processes files ... .\" .Sh CONTEXT .\" For section 9 functions only. .\" .Sh IMPLEMENTATION NOTES .\" Not used in OpenBSD. .\" .Sh RETURN VALUES .\" For sections 2, 3, and 9 function return values only. .\" .Sh ENVIRONMENT .\" For sections 1, 6, 7, and 8 only. .\" .Sh FILES .\" .Sh EXIT STATUS .\" For sections 1, 6, and 8 only. .\" .Sh EXAMPLES .\" .Sh DIAGNOSTICS .\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only. .\" .Sh ERRORS .\" For sections 2, 3, 4, and 9 errno settings only. .\" .Sh SEE ALSO .\" .Xr foobar 1 .\" .Sh STANDARDS .\" .Sh HISTORY .\" .Sh AUTHORS .\" .Sh CAVEATS .\" .Sh BUGS .\" .Sh SECURITY CONSIDERATIONS .\" Not used in OpenBSD. mdoc document are
conventionally ordered as they appear above. Sections should be composed as
follows:
MACRO OVERVIEWThis overview is sorted such that macros of similar purpose are listed together, to help find the best macro for any given purpose. Deprecated macros are not included in the overview, but can be found below in the alphabetical MACRO REFERENCE.Document preamble and NAME section macros
Sections and cross references
Displays and lists
Spacing control
Semantic markup for command line utilities
Semantic markup for function libraries
Various semantic markup
Physical markup
Physical enclosures
Text production
MACRO REFERENCEThis section is a canonical reference of all macros, arranged alphabetically. For the scoping of individual macros, see MACRO SYNTAX.%AAuthor name of an Rs block. Multiple authors should each be accorded their own %A line. Author names should be ordered with full or abbreviated forename(s) first, then full surname.%BBook title of an Rs block. This macro may also be used in a non-bibliographic context when referring to book titles.%CPublication city or location of an Rs block.%DPublication date of an Rs block. Recommended formats of arguments are month day, year or just year.%IPublisher or issuer name of an Rs block.%JJournal name of an Rs block.%NIssue number (usually for journals) of an Rs block.%OOptional information of an Rs block.%PBook or journal page number of an Rs block.%QInstitutional author (school, government, etc.) of an Rs block. Multiple institutional authors should each be accorded their own %Q line.%RTechnical report name of an Rs block.%TArticle title of an Rs block. This macro may also be used in a non-bibliographical context when referring to article titles.%UURI of reference document.%VVolume number of an Rs block.AcClose an Ao block. Does not have any tail arguments.AdMemory address. Do not use this for postal addresses. Examples:.Ad [0,$] .Ad 0x00000000 AnAuthor name. Can be used both for the authors of the program, function, or driver documented in the manual, or for the authors of the manual itself. Requires either the name of an author or one of the following arguments:-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 Mt
kristaps@bsd.lv AoBegin a block enclosed by angle brackets. Does not have any head arguments. This macro is almost never useful. See Aq for more details.ApInserts an apostrophe without any surrounding whitespace. This is generally used as a grammatical device when referring to the verb form of a function. Examples:.Fn execve Ap d AqEncloses its arguments in angle brackets. The only important use case is for email addresses. See Mt for an example. Occasionally, it is used for names of characters and keys, for example:Press the .Aq escape key to ... ArCommand arguments. If an argument is not provided, the string “file ...” is used as a default. Examples:.Fl o Ar file .Ar .Ar arg1 , arg2 . AtFormats an AT&T UNIX version. Accepts one optional argument:.At .At III .At V.1 BcClose a Bo block. Does not have any tail arguments.BdBegin a display block. Its syntax is as follows: 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 text lines. By default, a display block is preceded by a vertical space. The type must be one of the following:
.Bd -literal -offset indent -compact Hello world. .Ed BfChange the font mode for a scoped block of text. Its syntax is as follows:.Bf
[
The -emphasis |
-literal |
-symbolic |
Em | Li
| Sy -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.
See also Li,
Ef,
Em, and
Sy.
BkFor each macro, keep its output together on the same output line, until the end of the macro or the end of the input line is reached, whichever comes first. Line breaks in text lines are unaffected. The syntax is as follows:.Bk
The -words -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 BlBegin a list. Lists consist of items specified using the It macro, containing a head or a body or both. The list syntax is as follows: The list type is mandatory and must be specified first. The-width and
-offset arguments accept macro names as
described for Bd
-offset , scaling widths as described in
roff(7),
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:
-column and
-enum lists may not be portable.
See also El and
It.
BoBegin a block enclosed by square brackets. Does not have any head arguments. Examples:.Bo 1 , .Dv BUFSIZ Bc BqEncloses its arguments in square brackets. Examples:.Bq 1, Dv BUFSIZ BrcClose a Bro block. Does not have any tail arguments.BroBegin a block enclosed by curly braces. Does not have any head arguments. Examples:.Bro 1 , ... , .Va n Brc BrqEncloses its arguments in curly braces. Examples:.Brq 1, ..., Va n BsxFormat the BSD/OS version provided as an argument, or a default value if no argument is provided. Examples:.Bsx 1.0 .Bsx BtSupported only for compatibility, do not use this in new manuals. Prints “is currently in beta test.”BxFormat the BSD version provided as an argument, or a default value if no argument is provided. Examples:.Bx 4.3 Tahoe .Bx 4.4 .Bx CdKernel configuration declaration. This denotes strings accepted by config(8). It is most often used in section 4 manual pages. Examples:.Cd device le0 at scode? CmCommand modifiers. Typically used for fixed strings passed as arguments, unless Fl is more appropriate. Also useful when specifying configuration options or keys. Examples:.Nm mt Fl f Ar device Cm
rewind .Nm ps Fl o Cm pid , Ns Cm
command .Nm dd Cm if= Ns Ar file1 Cm of= Ns
Ar file2 .Cm IdentityFile Pa
~/.ssh/id_rsa .Cm LogLevel Dv DEBUG D1One-line indented display. This is formatted by the default rules and is useful for simple indented statements. It is followed by a newline. Examples:.D1 Fl abcdefgh DbThis macro is obsolete. No replacement is needed. It is ignored by mandoc(1) and groff including its arguments. It was formerly used to toggle a debugging mode.DcClose a Do block. Does not have any tail arguments.DdDocument date for display in the page footer. This is the mandatory first macro of anymdoc manual. Its syntax is as
follows:
.Dd
month day,
year
The month is the full English month name, the
day is an integer number, and the
year is the full four-digit year.
Other arguments are not portable; the
mandoc(1)
utility handles them as follows:
.Dd $Mdocdate$ .Dd $Mdocdate: July 2
2018$ .Dd July 2, 2018 DlOne-line indented display. This is formatted as literal text and is useful for commands and invocations. It is followed by a newline. Examples:.Dl % mandoc mdoc.7 \(ba
less -literal , and
D1.
DoBegin a block enclosed by double quotes. Does not have any head arguments. Examples:.Do April is the cruellest month .Dc \(em T.S. Eliot DqEncloses its arguments in “typographic” double-quotes. Examples:.Dq April is the cruellest month \(em T.S. Eliot DtDocument title for display in the page header. This is the mandatory second macro of anymdoc file. Its syntax is as
follows:
.Dt
TITLE
section
[
Its arguments are as follows:
arch ]
.Dt FOO 1 .Dt FOO 9 i386 DvDefined variables such as preprocessor constants, constant symbols, enumeration values, and so on. Examples:.Dv NULL .Dv BUFSIZ .Dv STDOUT_FILENO DxFormat the DragonFly version provided as an argument, or a default value if no argument is provided. Examples:.Dx 2.4.1 .Dx EcClose a scope started by Eo. Its syntax is as follows:.Ec
[
The TERM argument is used as the enclosure
tail, for example, specifying \(rq will emulate
Dc.
TERM ]EdEnd a display context started by Bd.EfEnd a font mode context started by Bf.EkEnd a keep context started by Bk.ElEnd a list context started by Bl. See also Bl and It.EmRequest an italic font. If the output device does not provide that, underline. This is most often used for stress emphasis (not to be confused with importance, see Sy). In the rare cases where none of the semantic markup macros fit, it can also be used for technical terms and placeholders, except that for syntax elements, Sy and Ar are preferred, respectively. Examples:Selected lines are those .Em not matching any of the specified patterns. Some of the functions use a .Em hold space to save the pattern space for subsequent retrieval. EnThis macro is obsolete. Use Eo or any of the other enclosure macros. It encloses its argument in the delimiters specified by the last Es macro.EoAn arbitrary enclosure. Its syntax is as follows:.Eo
[
The TERM argument is used as the enclosure
head, for example, specifying \(lq will emulate
Do.
TERM ]ErError constants for definitions of the errno libc global variable. This is most often used in section 2 and 3 manual pages. Examples:.Er EPERM .Er ENOENT EsThis macro is obsolete. Use Eo or any of the other enclosure macros. It takes two arguments, defining the delimiters to be used by subsequent En macros.EvEnvironmental variables such as those specified in environ(7). Examples:.Ev DISPLAY .Ev PATH ExInsert a standard sentence regarding command exit values of 0 on success and >0 on failure. This is most often used in section 1, 6, and 8 manual pages. Its syntax is as follows: If utility is not specified, the document's name set by Nm is used. Multiple utility arguments are treated as separate utilities. See also Rv.FaFunction argument or parameter. Its syntax is as follows: Each argument may be a name and a type (recommended for the SYNOPSIS section), a name alone (for function invocations), or a type alone (for function prototypes). If both a type and a name are given or if the type consists of multiple words, all words belonging to the same function argument have to be given in a single argument to the Fa macro. This macro is also used to specify the field name of a structure. Most often, the Fa macro is used in the SYNOPSIS within Fo blocks 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 "char *"
size_t FcEnd a function context started by Fo.FdPreprocessor directive, in particular for listing it in the SYNOPSIS. Historically, it was also used to document include files. The latter usage has been deprecated in favour of In. Its syntax is as follows: Examples:.Fd #define sa_handler
__sigaction_u.__sa_handler .Fd #define SIO_MAXNFDS .Fd #ifdef FS_DEBUG .Ft void .Fn dbg_open "const char
*" .Fd #endif FlCommand-line flag or option. Used when listing arguments to command-line utilities. Prints a fixed-width hyphen ‘-’ directly followed by each argument. If no arguments are provided, a hyphen is printed followed by a space. If the argument is a macro, a hyphen is prefixed to the subsequent macro output. Examples:.Fl R Op Fl H | L | P .Op Fl
1AaCcdFfgHhikLlmnopqRrSsTtux .Fl type Cm d Fl name Pa
CVS .Fl Ar signal_number .Fl o Fl FnA function name. Its syntax is as follows: Function arguments are surrounded in parenthesis and are delimited by commas. If no arguments are specified, blank parenthesis are output. In the SYNOPSIS section, this macro starts a new output line, and a blank line is automatically inserted between function definitions. Examples:.Fn "int funcname"
"int arg0" "int arg1" .Fn funcname "int
arg0" .Fn funcname arg0 .Ft functype .Fn funcname FoBegin a function block. This is a multi-line version of Fn. Its syntax is as follows:.Fo
funcname
Invocations usually occur in the following context:
A Fo scope is closed by
Fc.
See also MANUAL STRUCTURE,
Fa,
Fc, and
Ft.
FrThis macro is obsolete. No replacement markup is needed. It was used to show numerical function return values in an italic font.FtA function type. Its syntax is as follows:.Ft
functype
In the SYNOPSIS section, a new output line is
started after this macro.
Examples:
.Ft int .Ft functype .Fn funcname FxFormat the FreeBSD version provided as an argument, or a default value if no argument is provided. Examples:.Fx 7.1 .Fx HfThis macro is not implemented in mandoc(1). It was used to include the contents of a (header) file literally. The syntax was:.Hf
filename IcDesignate an internal or interactive command. This is similar to Cm but used for instructions rather than values. Examples:.Ic :wq .Ic hash .Ic alias -literal or
D1 is preferred for displaying code;
the Ic macro is used when referring to
specific instructions.
InThe name of an include file. This macro is most often used in section 2, 3, and 9 manual pages. When invoked as the first macro on an input line in the SYNOPSIS section, the argument is displayed in angle brackets and preceded by “#include”, and a blank line is inserted in front if there is a preceding function declaration. In other sections, it only encloses its argument in angle brackets and causes no line break. Examples:.In sys/types.h ItA list item. The syntax of this macro depends on the list type. 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
[
Subsequent lines are interpreted as with
args -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
cell [
The arguments consist of one or more lines of text and macros representing a
complete table line. Cells within the line are delimited by the special
Ta block macro or by literal tab
characters.
Using literal tabs is strongly discouraged because they are very hard to use
correctly and <TAB>
cell ... ]mdoc code using them is very
hard to read. In particular, a blank character is syntactically significant
before and after the literal tab character. If a word precedes or follows the
tab without an intervening blank, that word is never interpreted as a macro
call, but always output literally.
The tab cell delimiter may only be used within the
It line itself; on following lines,
only the Ta macro can be used to
delimit cells, and portability requires that
Ta is called by other macros: some
parsers do not recognize it when it appears as the first macro on a line.
Note that quoted strings may span tab-delimited cells on an
It line. For example,
.It "col1 , <TAB> col2
," ; LbSpecify a library. The syntax is as follows:.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 libmandoc LiDenotes text that should be in aliteral font mode. Note
that this is a presentation term and should not be used for stylistically
decorating technical terms.
On terminal output devices, this is often indistinguishable from normal text.
See also Bf,
Em,
No, and
Sy.
LkFormat a hyperlink. Its syntax is as follows:.Lk
uri
[
Examples:
name ].Lk http://bsd.lv "The BSD.lv
Project" .Lk http://bsd.lv LpSynonym for Pp.MsDisplay a mathematical symbol. Its syntax is as follows:.Ms
symbol
Examples:
.Ms sigma .Ms aleph MtFormat a “mailto:” hyperlink. Its syntax is as follows:.Mt
address
Examples:
.Mt
discuss@manpages.bsd.lv .An Kristaps Dzonsons Aq Mt
kristaps@bsd.lv NdA one line description of the manual's content. This is the mandatory last macro of the NAME section and not appropriate for other sections. Examples: 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.NmThe name of the manual page, or — in particular in section 1, 6, and 8 pages — of an additional command or feature documented in the manual page. When first invoked, the Nm macro expects a single argument, the name of the manual page. Usually, the first invocation happens in the NAME section of the page. The specified name will be remembered and used whenever the macro is called again without arguments later in the page. The Nm macro uses Block full-implicit semantics when invoked as the first macro on an input line in the SYNOPSIS section; otherwise, it uses ordinary In-line semantics. Examples:.Sh SYNOPSIS .Nm cat .Op Fl benstuv .Op Ar NoNormal text. Closes the scope of any preceding in-line macro. When used after physical formatting macros like Em or Sy, switches back to the standard font face and weight. Can also be used to embed plain text strings in macro lines using semantic annotation macros. Examples:.Em italic , Sy bold , No and
roman .Sm off .Cm :C No / Ar pattern No / Ar replacement No / .Sm on NsSuppress a space between the output of the preceding macro and the following text or macro. Following invocation, input is interpreted as normal text just like after an No macro. This has no effect when invoked at the start of a macro line. Examples:.Ar name Ns = Ns Ar
value .Cm :M Ns Ar pattern .Fl o Ns Ar output NxFormat the NetBSD version provided as an argument, or a default value if no argument is provided. Examples:.Nx 5.01 .Nx OcClose multi-line Oo context.OoMulti-line version of Op. Examples:.Oo .Op Fl flag Ns Ar value .Oc OpOptional part of a command line. Prints the argument(s) in brackets. This is most often used in the SYNOPSIS section of section 1 and 8 manual pages. Examples:.Op Fl a Ar b .Op Ar a | b OsOperating system version for display in the page footer. This is the mandatory third macro of anymdoc file. Its syntax is
as follows:
.Os
[
The optional system parameter specifies the
relevant operating system or environment. It is suggested to leave it
unspecified, in which case
mandoc(1)
uses its system
[ ]version ]-Ios argument or, if that isn't
specified either, sysname and
release as returned by
uname(3).
Examples:
.Os .Os KTH/CSC/TCS .Os BSD 4.3 OtThis macro is obsolete. Use Ft instead; with mandoc(1), both have the same effect. Historicalmdoc packages described it as
“old function type (FORTRAN)”.
OxFormat the OpenBSD version provided as an argument, or a default value if no argument is provided. Examples:.Ox 4.5 .Ox PaAn absolute or relative file system path, or a file or directory name. If an argument is not provided, the character ‘~’ is used as a default. Examples:.Pa /usr/bin/mandoc .Pa
/usr/share/man/man7/mdoc.7 PcClose parenthesised context opened by Po.PfRemoves the space between its argument and the following macro. Its syntax is as follows:.Pf prefix macro arguments
...
This is equivalent to:
.No \&prefix
Ns macro arguments
...
The prefix argument is not parsed for macro
names or delimiters, but used verbatim as if it were escaped.
Examples:
.Pf $ Ar variable_name .Pf . Ar macro_name .Pf 0x Ar hex_digits PoMulti-line version of Pq.PpBreak a paragraph. This will assert vertical space between prior and subsequent macros and/or text. Paragraph breaks are not needed before or after Sh or Ss macros or before displays (Bd) or lists (Bl) unless the-compact flag is given.
PqParenthesised enclosure. See also Po.QcClose quoted context opened by Qo.QlIn-line literal display. This can for example be used for complete command invocations and for multi-word code fragments when more specific markup is not appropriate and an indented display is not desired. While mandoc(1) always encloses the arguments in single quotes, other formatters usually omit the quotes on non-terminal output devices when the arguments have three or more characters. See also Dl and Bd-literal .
QoMulti-line version of Qq.ReClose an Rs block. Does not have any tail arguments.RsBegin a bibliographic (“reference”) block. Does not have any head arguments. The block macro may only contain %A, %B, %C, %D, %I, %J, %N, %O, %P, %Q, %R, %T, %U, and %V child macros (at least one must be specified). Examples:.Rs .%A J. E. Hopcroft .%A J. D. Ullman .%B Introduction to Automata Theory, Languages, and Computation .%I Addison-Wesley .%C Reading, Massachusetts .%D 1979 .Re RvInsert a standard sentence regarding a function call's return value of 0 on success and -1 on error, with the errno libc global variable set on error. Its syntax is as follows: If function is not specified, the document's name set by Nm is used. Multiple function arguments are treated as separate functions. See also Ex.ScClose single-quoted context opened by So.ShBegin a new section. For a list of conventional manual sections, see MANUAL STRUCTURE. These sections should be used unless it's absolutely necessary that custom sections be used. Section names should be unique so that they may be keyed by Sx. Although this macro is parsed, it should not consist of child node or it may not be linked with Sx. See also Pp, Ss, and Sx.SmSwitches the spacing mode for output generated from macros. Its syntax is as follows:.Sm
[
By default, spacing is on |
off on . When switched
off , no white space is inserted between
macro arguments and between the output generated from adjacent macros, but
text lines still get normal spacing between words and sentences.
When called without an argument, the Sm
macro toggles the spacing mode. Using this is not recommended because it makes
the code harder to read.
SoMulti-line version of Sq.SqEncloses its arguments in ‘typewriter’ single-quotes. See also Dq, Qq, and So.SsBegin a new subsection. Unlike with Sh, there is no convention for the naming of subsections. Except DESCRIPTION, the conventional sections described in MANUAL STRUCTURE rarely have subsections. Sub-section names should be unique so that they may be keyed by Sx. Although this macro is parsed, it should not consist of child node or it may not be linked with Sx. See also Pp, Sh, and Sx.StReplace an abbreviation for a standard with the full form. The following standards are recognised. Where multiple lines are given without a blank line in between, they all refer to the same standard, and using the first form is recommended.
SxReference a section or subsection in the same manual page. The referenced section or subsection name must be identical to the enclosed argument, including whitespace. Examples:.Sx MANUAL STRUCTURE SyRequest a boldface font. This is most often used to indicate importance or seriousness (not to be confused with stress emphasis, see Em). When none of the semantic macros fit, it is also adequate for syntax elements that have to be given or that appear verbatim. Examples:.Sy Warning : If .Sy s appears in the owner permissions, set-user-ID mode is set. This utility replaces the former .Sy dumpdir program. TaTable cell separator in Bl-column lists; can only be used below
It.
TnSupported only for compatibility, do not use this in new manuals. Even though the macro name (“tradename”) suggests a semantic function, historic usage is inconsistent, mostly using it as a presentation-level macro to request a small caps font.UdSupported only for compatibility, do not use this in new manuals. Prints out “currently under development.”UxSupported only for compatibility, do not use this in new manuals. Prints out “UNIX”.VaA variable name. Examples:.Va foo .Va const char *bar; VtA variable type. This is also used for indicating global variables in the SYNOPSIS section, in which case a variable name is also specified. Note that it accepts Block partial-implicit syntax when invoked as the first macro on an input line in the SYNOPSIS section, else it accepts ordinary In-line syntax. In the former case, this macro starts a new output line, and a blank line is inserted in front if there is a preceding function definition or include directive. Examples:.Vt unsigned char .Vt extern const char * const
sys_signame[] ; XcClose a scope opened by Xo.XoExtend the header of an It macro or the body of a partial-implicit block macro beyond the end of the input line. This macro originally existed to work around the 9-argument limit of historic roff(7).XrLink to another manual (“cross-reference”). Its syntax is as follows:.Xr
name section
Cross reference the name and
section number of another man page.
Examples:
.Xr mandoc 1 .Xr mandoc 1 ; .Xr mandoc 1 Ns s
behaviour MACRO SYNTAXThe 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. For example, ‘.Op Fl O Ar file’ produces ‘[-O
fileFl O ]’. 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.
Block full-explicitMulti-line scope closed by an explicit closing macro. All macros contains bodies; only Bf and (optionally) Bl contain a head..Yo [-arg [parm...]] [head...] [body...] .Yc
Block full-implicitMulti-line scope closed by end-of-file or implicitly by another macro. All macros have bodies; some (It-bullet ,
-hyphen ,
-dash ,
-enum ,
-item ) don't have heads; only one
(It in
Bl
-column ) has multiple heads.
.Yo [-arg [parm...]] [head... [Ta head...]] [body...]
Block partial-explicitLike block full-explicit, but also with single-line scope. Each has at least a body and, in limited circumstances, a head (Fo, Eo) and/or tail (Ec)..Yo [-arg [parm...]] [head...] [body...] .Yc [tail...] .Yo [-arg [parm...]] [head...] [body...] Yc [tail...]
Block partial-implicitLike block full-implicit, but with single-line scope closed by the end of the line..Yo [-arg [val...]] [body...] [res...]
Special block macroThe Ta macro can only be used below It in Bl-column lists. It delimits blocks
representing table cells; these blocks have bodies, but no heads.
In-lineClosed by the end of the line, fixed argument lengths, and/or subsequent macros. In-line macros have only text children. If a number (or inequality) of arguments is (n), then the macro accepts an arbitrary number of arguments..Yo [-arg [val...]] [args...] [res...] .Yo [-arg [val...]] [args...] Yc... .Yo [-arg [val...]] arg0 arg1 argN
DelimitersWhen a macro argument consists of one single input character considered as a delimiter, the argument gets special handling. This does not apply when delimiters appear in arguments containing more than one character. Consequently, to prevent special handling and just handle it like any other argument, a delimiter can be escaped by prepending a zero-width space (‘\&’). In text lines, delimiters never need escaping, but may be used as normal punctuation. For many macros, when the leading arguments are opening delimiters, these delimiters are put before the macro scope, and when the trailing arguments are closing delimiters, these delimiters are put after the macro scope. Spacing is suppressed after opening delimiters and before closing delimiters. For example,.Aq ( [ word ] ) .
renders as:
([⟨word⟩]).
Opening delimiters are:
.Fl a ( b | c \*(Ba d ) e
renders as:
-a
(-b | -c
| -d )
-e
Font handlingInmdoc documents, usage of semantic markup
is recommended in order to have proper fonts automatically selected; only when
no fitting semantic markup is available, consider falling back to
Physical markup macros.
Whenever any mdoc macro switches the
roff(7)
font mode, it will automatically restore the previous font when exiting its
scope. Manually switching the font using the
roff(7)
‘\f ’ font escape sequences is never
required.
COMPATIBILITYThis section provides an incomplete list of compatibility issues between mandoc and GNU troff (“groff”). The following problematic behaviour is found in groff:
SEE ALSOman(1), mandoc(1), eqn(7), man(7), mandoc_char(7), roff(7), tbl(7) The web page extended documentation for the mdoc language provides a few tutorial-style pages for beginners, an extensive style guide for advanced authors, and an alphabetic index helping to choose the best macros for various kinds of content.HISTORYThemdoc language first appeared as a troff
macro package in 4.4BSD. It was later significantly
updated by Werner Lemberg and Ruslan Ermilov in groff-1.17. The standalone
implementation that is part of the
mandoc(1)
utility written by Kristaps Dzonsons appeared in OpenBSD
4.6.
AUTHORSThemdoc reference was written by
Kristaps Dzonsons
<kristaps@bsd.lv>.
|