-.\" $Id: mdoc.7,v 1.279 2019/07/15 19:20:30 schwarze Exp $
+.\" $Id: mdoc.7,v 1.287 2021/07/29 17:32:01 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
-.\" Copyright (c) 2010, 2011, 2013-2018 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2010, 2011, 2013-2020 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: July 15 2019 $
+.Dd $Mdocdate: July 29 2021 $
.Dt MDOC 7
.Os
.Sh NAME
It usually follows with a breakdown of the options (if documenting a
command), such as:
.Bd -literal -offset indent
-The arguments are as follows:
+The options are as follows:
\&.Bl \-tag \-width Ds
\&.It Fl v
Print verbose information.
.It Ic \&Ss Ta subsection header (one line)
.It Ic \&Sx Ta internal cross reference to a section or subsection
.It Ic \&Xr Ta cross reference to another manual page: Ar name section
+.It Ic \&Tg Ta tag the definition of a Ar term Pq <= 1 arguments
.It Ic \&Pp Ta start a text paragraph (no arguments)
.El
.Ss Displays and lists
.Ic \&Ao
block.
Does not have any tail arguments.
+.Tg Ad
.It Ic \&Ad Ar address
Memory address.
Do not use this for postal addresses.
Examples:
.Dl \&.Ad [0,$]
.Dl \&.Ad 0x00000000
+.Tg An
.It Ic \&An Fl split | nosplit | Ar first_name ... last_name
Author name.
Can be used both for the authors of the program, function, or driver
See
.Ic \&Aq
for more details.
+.Tg Ap
.It Ic \&Ap
Inserts an apostrophe without any surrounding whitespace.
This is generally used as a grammatical device when referring to the verb
.Pp
Examples:
.Dl \&.Fn execve \&Ap d
+.Tg Aq
.It Ic \&Aq Ar line
Enclose the rest of the input line in angle brackets.
The only important use case is for email addresses.
.Pp
See also
.Ic \&Ao .
+.Tg Ar
.It Ic \&Ar Op Ar placeholder ...
Command arguments.
If an argument is not provided, the string
.Ic \&Fl
or
.Ic \&Cm .
+.Tg At
.It Ic \&At Op Ar version
Formats an
.At
.Ic \&Bo
block.
Does not have any tail arguments.
+.Tg Bd
.It Ic \&Bd Fl Ns Ar type Oo Fl offset Ar width Oc Op Fl compact
Begin a display block.
Display blocks are used to select a different indentation and
.Ic \&D1
and
.Ic \&Dl .
+.Tg Bf
.It Ic \&Bf Fl emphasis | literal | symbolic | Cm \&Em | \&Li | \&Sy
Change the font mode for a scoped block of text.
The
.Ic \&Em ,
and
.Ic \&Sy .
+.Tg Bk
.It Ic \&Bk Fl words
For 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,
.Pp
Be careful in using over-long lines within a keep block!
Doing so will clobber the right margin.
+.Tg Bl
.It Xo
.Ic \&Bl
.Fl Ns Ar type
.Pp
See also
.Ic \&Bq .
+.Tg Bq
.It Ic \&Bq Ar line
Encloses its arguments in square brackets.
.Pp
.Pp
See also
.Ic \&Brq .
+.Tg Brq
.It Ic \&Brq Ar line
Encloses its arguments in curly braces.
.Pp
.Pp
See also
.Ic \&Bro .
+.Tg Bsx
.It Ic \&Bsx Op Ar version
Format the
.Bsx
Supported only for compatibility, do not use this in new manuals.
Prints
.Dq is currently in beta test.
+.Tg Bx
.It Ic \&Bx Op Ar version Op Ar variant
Format the
.Bx
.Ic \&Nx ,
and
.Ic \&Ox .
+.Tg Cd
.It Ic \&Cd Ar line
Kernel configuration declaration.
This denotes strings accepted by
.Ic \&Cd
declarations.
This practise is discouraged.
+.Tg Cm
.It Ic \&Cm Ar keyword ...
Command modifiers.
Typically used for fixed strings passed as arguments to interactive
.Dl ".Ic set Fl o Cm vi"
.Dl ".Ic lookup Cm file bind"
.Dl ".Ic permit Ar identity Op Cm as Ar target"
+.Tg D1
.It Ic \&D1 Ar line
One-line indented display.
This is formatted by the default rules and is useful for simple indented
.Ic \&Do
block.
Does not have any tail arguments.
+.Tg Dd
.It Ic \&Dd Cm $\&Mdocdate$ | Ar month day , year
-Document date for display in the page footer.
+Document date for display in the page footer,
+by convention the date of the last change.
This is the mandatory first macro of any
.Nm
manual.
.Ic \&Dt
and
.Ic \&Os .
+.Tg Dl
.It Ic \&Dl Ar line
One-line indented display.
This is formatted as literal text and is useful for commands and
.Pp
See also
.Ic \&Dq .
+.Tg Dq
.It Ic \&Dq Ar line
Encloses its arguments in
.Dq typographic
.Ic \&Sq ,
and
.Ic \&Do .
+.Tg Dt
.It Ic \&Dt Ar TITLE section Op Ar arch
Document title for display in the page header.
This is the mandatory second macro of any
.Ic \&Dd
and
.Ic \&Os .
+.Tg Dv
.It Ic \&Dv Ar identifier ...
Defined variables such as preprocessor constants, constant symbols,
enumeration values, and so on.
.Ic \&Fd
for listing preprocessor variable definitions in the
.Em SYNOPSIS .
+.Tg Dx
.It Ic \&Dx Op Ar version
Format the
.Dx
.Ic \&Bl .
See also
.Ic \&It .
+.Tg Em
.It Ic \&Em Ar word ...
Request an italic font.
If the output device does not provide that, underline.
It encloses its argument in the delimiters specified by the last
.Ic \&Es
macro.
+.Tg Eo
.It Ic \&Eo Op Ar opening_delimiter
An arbitrary enclosure.
The
argument is used as the enclosure head, for example, specifying \e(lq
will emulate
.Ic \&Do .
+.Tg Er
.It Ic \&Er Ar identifier ...
Error constants for definitions of the
.Va errno
It takes two arguments, defining the delimiters to be used by subsequent
.Ic \&En
macros.
+.Tg Ev
.It Ic \&Ev Ar identifier ...
Environmental variables such as those specified in
.Xr environ 7 .
See also
.Ic \&Dv
for general constants.
+.Tg Ex
.It Ic \&Ex Fl std Op Ar utility ...
Insert a standard sentence regarding command exit values of 0 on success
and >0 on failure.
.Pp
See also
.Ic \&Rv .
+.Tg Fa
.It Ic \&Fa Ar argument ...
Function argument or parameter.
Each argument may be a name and a type (recommended for the
.It Ic \&Fc
End a function context started by
.Ic \&Fo .
+.Tg Fd
.It Ic \&Fd Pf # Ar directive Op Ar argument ...
Preprocessor directive, in particular for listing it in the
.Em SYNOPSIS .
.Ic \&In ,
and
.Ic \&Dv .
+.Tg Fl
.It Ic \&Fl Op Ar word ...
Command-line flag or option.
Used when listing arguments to command-line utilities.
-Prints a fixed-width hyphen
-.Sq \-
-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.
+For each argument, prints an ASCII hyphen-minus character
+.Sq \- ,
+immediately followed by the argument.
+If no arguments are provided, a hyphen-minus is printed followed by a space.
+If the argument is a macro, a hyphen-minus is prefixed
+to the subsequent macro output.
.Pp
Examples:
-.Dl ".Fl R Op Fl H | L | P"
-.Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
-.Dl ".Fl type Cm d Fl name Pa CVS"
-.Dl ".Fl Ar signal_number"
-.Dl ".Fl o Fl"
+.Dl ".Nm du Op Fl H | L | P"
+.Dl ".Nm ls Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
+.Dl ".Nm route Cm add Fl inet Ar destination gateway"
+.Dl ".Nm locate.updatedb Op Fl \e-fcodes Ns = Ns Ar dbfile"
+.Dl ".Nm aucat Fl o Fl"
+.Dl ".Nm kill Fl Ar signal_number"
+.Pp
+For GNU-sytle long options, escaping the additional hyphen-minus is not
+strictly required, but may be safer with future versions of GNU troff; see
+.Xr mandoc_char 7
+for details.
.Pp
See also
.Ic \&Cm .
+.Tg Fn
.It Ic \&Fn Ar funcname Op Ar argument ...
A function name.
.Pp
.Ic \&Fo ,
and
.Ic \&Ft .
+.Tg Fo
.It Ic \&Fo Ar funcname
Begin a function block.
This is a multi-line version of
No replacement markup is needed.
.Pp
It was used to show numerical function return values in an italic font.
+.Tg Ft
.It Ic \&Ft Ar functype
A function type.
.Pp
.Ic \&Fn ,
and
.Ic \&Fo .
+.Tg Fx
.It Ic \&Fx Op Ar version
Format the
.Fx
This macro is not implemented in
.Xr mandoc 1 .
It was used to include the contents of a (header) file literally.
+.Tg Ic
.It Ic \&Ic Ar keyword ...
Internal or interactive command, or configuration instruction
in a configuration file.
is preferred for displaying code samples; the
.Ic \&Ic
macro is used when referring to an individual command name.
+.Tg In
.It Ic \&In Ar filename
The name of an include file.
This macro is most often used in section 2, 3, and 9 manual pages.
.Pp
See also
.Sx MANUAL STRUCTURE .
+.Tg It
.It Ic \&It Op Ar head
A list item.
The syntax of this macro depends on the list type.
.Pp
See also
.Ic \&Bl .
+.Tg Lb
.It Ic \&Lb Cm lib Ns Ar name
Specify a library.
.Pp
Examples:
.Dl \&.Lb libz
.Dl \&.Lb libmandoc
+.Tg Li
.It Ic \&Li Ar word ...
Request a typewriter (literal) font.
Deprecated because on terminal output devices, this is usually
or
.Ic \&Bd Fl literal Pq multi-line
instead.
+.Tg Lk
.It Ic \&Lk Ar uri Op Ar display_name
Format a hyperlink.
.Pp
Examples:
-.Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq
-.Dl \&.Lk http://bsd.lv
+.Dl \&.Lk https://bsd.lv \(dqThe BSD.lv Project\(dq
+.Dl \&.Lk https://bsd.lv
.Pp
See also
.Ic \&Mt .
.It Ic \&Lp
Deprecated synonym for
.Ic \&Pp .
+.Tg Ms
.It Ic \&Ms Ar name
Display a mathematical symbol.
.Pp
Examples:
.Dl \&.Ms sigma
.Dl \&.Ms aleph
+.Tg Mt
.It Ic \&Mt Ar localpart Ns @ Ns Ar domain
Format a
.Dq mailto:
Examples:
.Dl \&.Mt discuss@manpages.bsd.lv
.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
+.Tg Nd
.It Ic \&Nd Ar line
A one line description of the manual's content.
This is the mandatory last macro of the
.Pp
See also
.Ic \&Nm .
+.Tg Nm
.It Ic \&Nm Op Ar name
The name of the manual page, or \(em in particular in section 1, 6,
and 8 pages \(em of an additional command or feature documented in
macro rather than
.Ic \&Nm
to mark up the name of the manual page.
+.Tg No
.It Ic \&No Ar word ...
Normal text.
Closes the scope of any preceding in-line macro.
.Ic \&Ql ,
and
.Ic \&Sy .
+.Tg Ns
.It Ic \&Ns
Suppress a space between the output of the preceding macro
and the following text or macro.
.Ic \&No
and
.Ic \&Sm .
+.Tg Nx
.It Ic \&Nx Op Ar version
Format the
.Nx
\&.Op Fl flag Ns Ar value
\&.Oc
.Ed
+.Tg Op
.It Ic \&Op Ar line
Optional part of a command line.
Prints the argument(s) in brackets.
.Pp
See also
.Ic \&Oo .
+.Tg Os
.It Ic \&Os Op Ar system Op Ar version
Operating system version for display in the page footer.
This is the mandatory third macro of
.Nm
packages described it as
.Dq "old function type (FORTRAN)" .
+.Tg Ox
.It Ic \&Ox Op Ar version
Format the
.Ox
.Ic \&Fx ,
and
.Ic \&Nx .
+.Tg Pa
.It Ic \&Pa Ar name ...
An absolute or relative file system path, or a file or directory name.
If an argument is not provided, the character
.It Ic \&Pc
Close parenthesised context opened by
.Ic \&Po .
+.Tg Pf
.It Ic \&Pf Ar prefix macro Op Ar argument ...
Removes the space between its argument and the following macro.
It is equivalent to:
.It Ic \&Po Ar block
Multi-line version of
.Ic \&Pq .
+.Tg Pp
.It Ic \&Pp
Break a paragraph.
This will assert vertical space between prior and subsequent macros
unless the
.Fl compact
flag is given.
+.Tg Pq
.It Ic \&Pq Ar line
Parenthesised enclosure.
.Pp
.It Ic \&Qc
Close quoted context opened by
.Ic \&Qo .
+.Tg Ql
.It Ic \&Ql Ar line
In-line literal display.
This can be used for complete command invocations and for multi-word
.It Ic \&Qo Ar block
Multi-line version of
.Ic \&Qq .
+.Tg Qq
.It Ic \&Qq Ar line
Encloses its arguments in
.Qq typewriter
.Ic \&Rs
block.
Does not have any tail arguments.
+.Tg Rs
.It Ic \&Rs
Begin a bibliographic
.Pq Dq reference
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.
+.Tg Rv
.It Ic \&Rv Fl std Op Ar function ...
Insert a standard sentence regarding a function call's return value of 0
on success and \-1 on error, with the
.It Ic \&Sc
Close single-quoted context opened by
.Ic \&So .
+.Tg Sh
.It Ic \&Sh Ar TITLE LINE
Begin a new section.
For a list of conventional manual sections, see
.Ic \&Ss ,
and
.Ic \&Sx .
+.Tg Sm
.It Ic \&Sm Op Cm on | off
Switches the spacing mode for output generated from macros.
.Pp
.It Ic \&So Ar block
Multi-line version of
.Ic \&Sq .
+.Tg Sq
.It Ic \&Sq Ar line
Encloses its arguments in
.Sq typewriter
.Ic \&Qq ,
and
.Ic \&So .
+.Tg Ss
.It Ic \&Ss Ar Title line
Begin a new subsection.
Unlike with
.Ic \&Sh ,
and
.Ic \&Sx .
+.Tg St
.It Ic \&St Fl Ns Ar abbreviation
Replace an abbreviation for a standard with the full form.
The following standards are recognised.
.St -ieee1275-94
.El
.El
+.Tg Sx
.It Ic \&Sx Ar Title line
Reference a section or subsection in the same manual page.
The referenced section or subsection name must be identical to the
.Ic \&Sh
and
.Ic \&Ss .
+.Tg Sy
.It Ic \&Sy Ar word ...
Request a boldface font.
.Pp
.Ic \&No ,
and
.Ic \&Ql .
+.Tg Ta
.It Ic \&Ta
Table cell separator in
.Ic \&Bl Fl column
lists; can only be used below
.Ic \&It .
+.Tg Tg
+.It Ic \&Tg Op Ar term
+Announce that the next input line starts a definition of the
+.Ar term .
+This macro must appear alone on its own input line.
+The argument defaults to the first argument of the first macro
+on the next line.
+The argument may not contain whitespace characters, not even when it is quoted.
+This macro is a
+.Xr mandoc 1
+extension and is typically ignored by other formatters.
+.Pp
+When viewing terminal output with
+.Xr less 1 ,
+the interactive
+.Ic :t
+command can be used to go to the definition of the
+.Ar term
+as described for the
+.Ev MANPAGER
+variable in
+.Xr man 1 ;
+when producing HTML output, a fragment identifier
+.Pq Ic id No attribute
+is generated, to be used for deep linking to this place of the document.
+.Pp
+In most cases, adding a
+.Ic \&Tg
+macro would be redundant because
+.Xr mandoc 1
+is able to automatically tag most definitions.
+This macro is intended for cases where automatic tagging of a
+.Ar term
+is unsatisfactory, for example if a definition is not tagged
+automatically (false negative) or if places are tagged that do
+not define the
+.Ar term
+(false positives).
+When there is at least one
+.Ic \&Tg
+macro for a
+.Ar term ,
+no other places are automatically marked as definitions of that
+.Ar term .
.It Ic \&Tn Ar word ...
Supported only for compatibility, do not use this in new manuals.
Even though the macro name
Supported only for compatibility, do not use this in new manuals.
Prints out
.Dq Ux .
+.Tg Va
.It Ic \&Va Oo Ar type Oc Ar identifier ...
A variable name.
.Pp
.Em SYNOPSIS
section, use
.Ic \&Vt .
+.Tg Vt
.It Ic \&Vt Ar type Op Ar identifier
A variable type.
.Pp
This macro originally existed to work around the 9-argument limit
of historic
.Xr roff 7 .
+.Tg Xr
.It Ic \&Xr Ar name section
Link to another manual
.Pq Qq cross-reference .
.Ss Block full-explicit
Multi-line scope closed by an explicit closing macro.
All macros contains bodies; only
-.Ic \s&Bf
+.Ic \&Bf
and
.Pq optionally
.Ic \&Bl
.It Ic \&St Ta \&No Ta Yes Ta 1
.It Ic \&Sx Ta Yes Ta Yes Ta >0
.It Ic \&Sy Ta Yes Ta Yes Ta >0
+.It Ic \&Tg Ta \&No Ta \&No Ta <2
.It Ic \&Tn Ta Yes Ta Yes Ta >0
.It Ic \&Ud Ta \&No Ta \&No Ta 0
.It Ic \&Ux Ta Yes Ta Yes Ta n
.Pp
.Bl -dash -compact
.It
-.Ic \&Dd
-with non-standard arguments behaves very strangely.
-When there are three arguments, they are printed verbatim.
-Any other number of arguments is replaced by the current date,
-but without any arguments the string
-.Dq Epoch
-is printed.
-.It
-.Ic \&Lk
-only accepts a single link-name argument; the remainder is misformatted.
-.It
.Ic \&Pa
does not format its arguments when used in the FILES section under
certain list types.
.Ic \&Ta
can only be called by other macros, but not at the beginning of a line.
.It
-.Ic \&%C
-is not implemented (up to and including groff-1.22.2).
-.It
.Sq \ef
.Pq font face
and
.Xr tbl 7
.Pp
The web page
-.Lk http://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language"
+.Lk https://mandoc.bsd.lv/mdoc/ "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.
+.Pp
+The manual page
+.Lk https://man.voidlinux.org/groff_mdoc "groff_mdoc(7)"
+contained in the
+.Dq groff
+package documents exactly the same language in a somewhat different style.
.Sh HISTORY
The
.Nm
git.ckatri.com / mandoc.git / blobdiff