-.\" $Id: mdoc.7,v 1.284 2021/05/12 17:13:01 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-2020 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: May 12 2021 $
+.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.
.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,
by convention the date of the last change.
.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
.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 .
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 .
git.ckatri.com / mandoc.git / blobdiff