more details about Mac OS X; information from Sevan Janiyan

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 51498e1943228b52646afde1acec44909aaa7cd7..7ac6ff11c00d2051bebf6c94600bb171cb0af5b2 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,7 +1,7 @@
-.\"    $Id: mdoc.7,v 1.277 2019/04/23 18:46:06 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) 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
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above


@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: April 23 2019 $
+.Dd $Mdocdate: July 29 2021 $

 .Dt MDOC 7
 .Os
 .Sh NAME
 .Dt MDOC 7
 .Os
 .Sh NAME


@@ -297,7 +297,7 @@ utility does this, that, and the other.
 It usually follows with a breakdown of the options (if documenting a
 command), such as:
 .Bd -literal -offset indent
 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.
 \&.Bl \-tag \-width Ds
 \&.It Fl v
 Print verbose information.


@@ -449,6 +449,7 @@ in the alphabetical
 .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 \&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
 .It Ic \&Pp Ta start a text paragraph (no arguments)
 .El
 .Ss Displays and lists


@@ -631,6 +632,7 @@ Close an
 .Ic \&Ao
 block.
 Does not have any tail arguments.
 .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.
 .It Ic \&Ad Ar address
 Memory address.
 Do not use this for postal addresses.


@@ -638,6 +640,7 @@ Do not use this for postal addresses.
 Examples:
 .Dl \&.Ad [0,$]
 .Dl \&.Ad 0x00000000
 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
 .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


@@ -678,6 +681,7 @@ This macro is almost never useful.
 See
 .Ic \&Aq
 for more details.
 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
 .It Ic \&Ap
 Inserts an apostrophe without any surrounding whitespace.
 This is generally used as a grammatical device when referring to the verb


@@ -685,6 +689,7 @@ form of a function.
 .Pp
 Examples:
 .Dl \&.Fn execve \&Ap d
 .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.
 .It Ic \&Aq Ar line
 Enclose the rest of the input line in angle brackets.
 The only important use case is for email addresses.


@@ -729,6 +734,7 @@ as needed.
 .Pp
 See also
 .Ic \&Ao .
 .Pp
 See also
 .Ic \&Ao .

+.Tg Ar

 .It Ic \&Ar Op Ar placeholder ...
 Command arguments.
 If an argument is not provided, the string
 .It Ic \&Ar Op Ar placeholder ...
 Command arguments.
 If an argument is not provided, the string


@@ -747,6 +753,7 @@ for fixed strings to be passed verbatim as arguments, use
 .Ic \&Fl
 or
 .Ic \&Cm .
 .Ic \&Fl
 or
 .Ic \&Cm .

+.Tg At

 .It Ic \&At Op Ar version
 Formats an
 .At
 .It Ic \&At Op Ar version
 Formats an
 .At


@@ -784,6 +791,7 @@ Close a
 .Ic \&Bo
 block.
 Does not have any tail arguments.
 .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
 .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


@@ -874,6 +882,7 @@ See also
 .Ic \&D1
 and
 .Ic \&Dl .
 .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
 .It Ic \&Bf Fl emphasis | literal | symbolic | Cm \&Em | \&Li | \&Sy
 Change the font mode for a scoped block of text.
 The


@@ -900,6 +909,7 @@ See also
 .Ic \&Em ,
 and
 .Ic \&Sy .
 .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,
 .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,


@@ -922,6 +932,7 @@ macro line:
 .Pp
 Be careful in using over-long lines within a keep block!
 Doing so will clobber the right margin.
 .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
 .It Xo
 .Ic \&Bl
 .Fl Ns Ar type


@@ -1064,6 +1075,7 @@ Examples:
 .Pp
 See also
 .Ic \&Bq .
 .Pp
 See also
 .Ic \&Bq .

+.Tg Bq

 .It Ic \&Bq Ar line
 Encloses its arguments in square brackets.
 .Pp
 .It Ic \&Bq Ar line
 Encloses its arguments in square brackets.
 .Pp


@@ -1097,6 +1109,7 @@ Examples:
 .Pp
 See also
 .Ic \&Brq .
 .Pp
 See also
 .Ic \&Brq .

+.Tg Brq

 .It Ic \&Brq Ar line
 Encloses its arguments in curly braces.
 .Pp
 .It Ic \&Brq Ar line
 Encloses its arguments in curly braces.
 .Pp


@@ -1105,6 +1118,7 @@ Examples:
 .Pp
 See also
 .Ic \&Bro .
 .Pp
 See also
 .Ic \&Bro .

+.Tg Bsx

 .It Ic \&Bsx Op Ar version
 Format the
 .Bsx
 .It Ic \&Bsx Op Ar version
 Format the
 .Bsx


@@ -1127,6 +1141,7 @@ and
 Supported only for compatibility, do not use this in new manuals.
 Prints
 .Dq is currently in beta test.
 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
 .It Ic \&Bx Op Ar version Op Ar variant
 Format the
 .Bx


@@ -1146,6 +1161,7 @@ See also
 .Ic \&Nx ,
 and
 .Ic \&Ox .
 .Ic \&Nx ,
 and
 .Ic \&Ox .

+.Tg Cd

 .It Ic \&Cd Ar line
 Kernel configuration declaration.
 This denotes strings accepted by
 .It Ic \&Cd Ar line
 Kernel configuration declaration.
 This denotes strings accepted by


@@ -1161,19 +1177,23 @@ whitespace and align consecutive
 .Ic \&Cd
 declarations.
 This practise is discouraged.
 .Ic \&Cd
 declarations.
 This practise is discouraged.

+.Tg Cm

 .It Ic \&Cm Ar keyword ...
 Command modifiers.
 .It Ic \&Cm Ar keyword ...
 Command modifiers.

-Typically used for fixed strings passed as arguments, unless
+Typically used for fixed strings passed as arguments to interactive
+commands, to commands in interpreted scripts, or to configuration
+file directives, unless

 .Ic \&Fl
 is more appropriate.
 .Ic \&Fl
 is more appropriate.

-Also useful when specifying configuration options or keys.

 .Pp
 Examples:
 .Dl ".Nm mt Fl f Ar device Cm rewind"
 .Dl ".Nm ps Fl o Cm pid , Ns Cm command"
 .Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2"
 .Pp
 Examples:
 .Dl ".Nm mt Fl f Ar device Cm rewind"
 .Dl ".Nm ps Fl o Cm pid , Ns Cm command"
 .Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2"

-.Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa"
-.Dl ".Cm LogLevel Dv DEBUG"
+.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
 .It Ic \&D1 Ar line
 One-line indented display.
 This is formatted by the default rules and is useful for simple indented


@@ -1199,8 +1219,10 @@ Close a
 .Ic \&Do
 block.
 Does not have any tail arguments.
 .Ic \&Do
 block.
 Does not have any tail arguments.

+.Tg Dd

 .It Ic \&Dd Cm $\&Mdocdate$ | Ar month day , year
 .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.
 This is the mandatory first macro of any
 .Nm
 manual.


@@ -1246,6 +1268,7 @@ See also
 .Ic \&Dt
 and
 .Ic \&Os .
 .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
 .It Ic \&Dl Ar line
 One-line indented display.
 This is formatted as literal text and is useful for commands and


@@ -1274,6 +1297,7 @@ April is the cruellest month
 .Pp
 See also
 .Ic \&Dq .
 .Pp
 See also
 .Ic \&Dq .

+.Tg Dq

 .It Ic \&Dq Ar line
 Encloses its arguments in
 .Dq typographic
 .It Ic \&Dq Ar line
 Encloses its arguments in
 .Dq typographic


@@ -1290,6 +1314,7 @@ See also
 .Ic \&Sq ,
 and
 .Ic \&Do .
 .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
 .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


@@ -1349,6 +1374,7 @@ See also
 .Ic \&Dd
 and
 .Ic \&Os .
 .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.
 .It Ic \&Dv Ar identifier ...
 Defined variables such as preprocessor constants, constant symbols,
 enumeration values, and so on.


@@ -1368,6 +1394,7 @@ for variable symbols, and
 .Ic \&Fd
 for listing preprocessor variable definitions in the
 .Em SYNOPSIS .
 .Ic \&Fd
 for listing preprocessor variable definitions in the
 .Em SYNOPSIS .

+.Tg Dx

 .It Ic \&Dx Op Ar version
 Format the
 .Dx
 .It Ic \&Dx Op Ar version
 Format the
 .Dx


@@ -1409,6 +1436,7 @@ End a list context started by
 .Ic \&Bl .
 See also
 .Ic \&It .
 .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 Ic \&Em Ar word ...
 Request an italic font.
 If the output device does not provide that, underline.


@@ -1448,6 +1476,7 @@ or any of the other enclosure macros.
 It encloses its argument in the delimiters specified by the last
 .Ic \&Es
 macro.
 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
 .It Ic \&Eo Op Ar opening_delimiter
 An arbitrary enclosure.
 The


@@ -1455,6 +1484,7 @@ The
 argument is used as the enclosure head, for example, specifying \e(lq
 will emulate
 .Ic \&Do .
 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 Ic \&Er Ar identifier ...
 Error constants for definitions of the
 .Va errno


@@ -1477,6 +1507,7 @@ or any of the other enclosure macros.
 It takes two arguments, defining the delimiters to be used by subsequent
 .Ic \&En
 macros.
 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 .
 .It Ic \&Ev Ar identifier ...
 Environmental variables such as those specified in
 .Xr environ 7 .


@@ -1488,6 +1519,7 @@ Examples:
 See also
 .Ic \&Dv
 for general constants.
 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.
 .It Ic \&Ex Fl std Op Ar utility ...
 Insert a standard sentence regarding command exit values of 0 on success
 and >0 on failure.


@@ -1504,6 +1536,7 @@ arguments are treated as separate utilities.
 .Pp
 See also
 .Ic \&Rv .
 .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 \&Fa Ar argument ...
 Function argument or parameter.
 Each argument may be a name and a type (recommended for the


@@ -1541,6 +1574,7 @@ See also
 .It Ic \&Fc
 End a function context started by
 .Ic \&Fo .
 .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 .
 .It Ic \&Fd Pf # Ar directive Op Ar argument ...
 Preprocessor directive, in particular for listing it in the
 .Em SYNOPSIS .


@@ -1561,25 +1595,33 @@ See also
 .Ic \&In ,
 and
 .Ic \&Dv .
 .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.
 .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:
 .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 .
 .Pp
 See also
 .Ic \&Cm .

+.Tg Fn

 .It Ic \&Fn Ar funcname Op Ar argument ...
 A function name.
 .Pp
 .It Ic \&Fn Ar funcname Op Ar argument ...
 A function name.
 .Pp


@@ -1608,6 +1650,7 @@ See also
 .Ic \&Fo ,
 and
 .Ic \&Ft .
 .Ic \&Fo ,
 and
 .Ic \&Ft .

+.Tg Fo

 .It Ic \&Fo Ar funcname
 Begin a function block.
 This is a multi-line version of
 .It Ic \&Fo Ar funcname
 Begin a function block.
 This is a multi-line version of


@@ -1642,6 +1685,7 @@ This macro is obsolete.
 No replacement markup is needed.
 .Pp
 It was used to show numerical function return values in an italic font.
 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
 .It Ic \&Ft Ar functype
 A function type.
 .Pp


@@ -1661,6 +1705,7 @@ See also
 .Ic \&Fn ,
 and
 .Ic \&Fo .
 .Ic \&Fn ,
 and
 .Ic \&Fo .

+.Tg Fx

 .It Ic \&Fx Op Ar version
 Format the
 .Fx
 .It Ic \&Fx Op Ar version
 Format the
 .Fx


@@ -1683,11 +1728,12 @@ and
 This macro is not implemented in
 .Xr mandoc 1 .
 It was used to include the contents of a (header) file literally.
 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 ...
 .It Ic \&Ic Ar keyword ...

-Designate an internal or interactive command.
-This is similar to
-.Ic \&Cm
-but used for instructions rather than values.
+Internal or interactive command, or configuration instruction
+in a configuration file.
+See also
+.Ic \&Cm .

 .Pp
 Examples:
 .Dl \&.Ic :wq
 .Pp
 Examples:
 .Dl \&.Ic :wq


@@ -1702,6 +1748,7 @@ or
 is preferred for displaying code samples; the
 .Ic \&Ic
 macro is used when referring to an individual command name.
 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.
 .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.


@@ -1721,6 +1768,7 @@ Examples:
 .Pp
 See also
 .Sx MANUAL STRUCTURE .
 .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.
 .It Ic \&It Op Ar head
 A list item.
 The syntax of this macro depends on the list type.


@@ -1811,6 +1859,7 @@ but not the whitespace before the semicolon.
 .Pp
 See also
 .Ic \&Bl .
 .Pp
 See also
 .Ic \&Bl .

+.Tg Lb

 .It Ic \&Lb Cm lib Ns Ar name
 Specify a library.
 .Pp
 .It Ic \&Lb Cm lib Ns Ar name
 Specify a library.
 .Pp


@@ -1831,6 +1880,7 @@ section as described in
 Examples:
 .Dl \&.Lb libz
 .Dl \&.Lb libmandoc
 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
 .It Ic \&Li Ar word ...
 Request a typewriter (literal) font.
 Deprecated because on terminal output devices, this is usually


@@ -1841,24 +1891,27 @@ For literal displays, use
 or
 .Ic \&Bd Fl literal Pq multi-line
 instead.
 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:
 .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 .
 .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
 .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:
 .It Ic \&Mt Ar localpart Ns @ Ns Ar domain
 Format a
 .Dq mailto:


@@ -1867,6 +1920,7 @@ hyperlink.
 Examples:
 .Dl \&.Mt discuss@manpages.bsd.lv
 .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
 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
 .It Ic \&Nd Ar line
 A one line description of the manual's content.
 This is the mandatory last macro of the


@@ -1889,6 +1943,7 @@ arguments and will display macros verbatim.
 .Pp
 See also
 .Ic \&Nm .
 .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
 .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


@@ -1926,6 +1981,7 @@ of section 2, 3 and 9 manual pages, use the
 macro rather than
 .Ic \&Nm
 to mark up the name of the manual page.
 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.
 .It Ic \&No Ar word ...
 Normal text.
 Closes the scope of any preceding in-line macro.


@@ -1950,6 +2006,7 @@ See also
 .Ic \&Ql ,
 and
 .Ic \&Sy .
 .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.
 .It Ic \&Ns
 Suppress a space between the output of the preceding macro
 and the following text or macro.


@@ -1969,6 +2026,7 @@ See also
 .Ic \&No
 and
 .Ic \&Sm .
 .Ic \&No
 and
 .Ic \&Sm .

+.Tg Nx

 .It Ic \&Nx Op Ar version
 Format the
 .Nx
 .It Ic \&Nx Op Ar version
 Format the
 .Nx


@@ -2001,6 +2059,7 @@ Examples:
 \&.Op Fl flag Ns Ar value
 \&.Oc
 .Ed
 \&.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.
 .It Ic \&Op Ar line
 Optional part of a command line.
 Prints the argument(s) in brackets.


@@ -2014,6 +2073,7 @@ Examples:
 .Pp
 See also
 .Ic \&Oo .
 .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
 .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


@@ -2056,6 +2116,7 @@ Historical
 .Nm
 packages described it as
 .Dq "old function type (FORTRAN)" .
 .Nm
 packages described it as
 .Dq "old function type (FORTRAN)" .

+.Tg Ox

 .It Ic \&Ox Op Ar version
 Format the
 .Ox
 .It Ic \&Ox Op Ar version
 Format the
 .Ox


@@ -2074,6 +2135,7 @@ See also
 .Ic \&Fx ,
 and
 .Ic \&Nx .
 .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 \&Pa Ar name ...
 An absolute or relative file system path, or a file or directory name.
 If an argument is not provided, the character


@@ -2089,6 +2151,7 @@ See also
 .It Ic \&Pc
 Close parenthesised context opened by
 .Ic \&Po .
 .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 \&Pf Ar prefix macro Op Ar argument ...
 Removes the space between its argument and the following macro.
 It is equivalent to:


@@ -2112,6 +2175,7 @@ and
 .It Ic \&Po Ar block
 Multi-line version of
 .Ic \&Pq .
 .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
 .It Ic \&Pp
 Break a paragraph.
 This will assert vertical space between prior and subsequent macros


@@ -2128,6 +2192,7 @@ or lists
 unless the
 .Fl compact
 flag is given.
 unless the
 .Fl compact
 flag is given.

+.Tg Pq

 .It Ic \&Pq Ar line
 Parenthesised enclosure.
 .Pp
 .It Ic \&Pq Ar line
 Parenthesised enclosure.
 .Pp


@@ -2136,6 +2201,7 @@ See also
 .It Ic \&Qc
 Close quoted context opened by
 .Ic \&Qo .
 .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 \&Ql Ar line
 In-line literal display.
 This can be used for complete command invocations and for multi-word


@@ -2149,6 +2215,7 @@ and
 .It Ic \&Qo Ar block
 Multi-line version of
 .Ic \&Qq .
 .It Ic \&Qo Ar block
 Multi-line version of
 .Ic \&Qq .

+.Tg Qq

 .It Ic \&Qq Ar line
 Encloses its arguments in
 .Qq typewriter
 .It Ic \&Qq Ar line
 Encloses its arguments in
 .Qq typewriter


@@ -2166,6 +2233,7 @@ Close an
 .Ic \&Rs
 block.
 Does not have any tail arguments.
 .Ic \&Rs
 block.
 Does not have any tail arguments.

+.Tg Rs

 .It Ic \&Rs
 Begin a bibliographic
 .Pq Dq reference
 .It Ic \&Rs
 Begin a bibliographic
 .Pq Dq reference


@@ -2206,6 +2274,7 @@ If an
 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.
 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 \&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


@@ -2226,6 +2295,7 @@ See also
 .It Ic \&Sc
 Close single-quoted context opened by
 .Ic \&So .
 .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
 .It Ic \&Sh Ar TITLE LINE
 Begin a new section.
 For a list of conventional manual sections, see


@@ -2244,6 +2314,7 @@ See also
 .Ic \&Ss ,
 and
 .Ic \&Sx .
 .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 \&Sm Op Cm on | off
 Switches the spacing mode for output generated from macros.
 .Pp


@@ -2262,6 +2333,7 @@ Using this is not recommended because it makes the code harder to read.
 .It Ic \&So Ar block
 Multi-line version of
 .Ic \&Sq .
 .It Ic \&So Ar block
 Multi-line version of
 .Ic \&Sq .

+.Tg Sq

 .It Ic \&Sq Ar line
 Encloses its arguments in
 .Sq typewriter
 .It Ic \&Sq Ar line
 Encloses its arguments in
 .Sq typewriter


@@ -2272,6 +2344,7 @@ See also
 .Ic \&Qq ,
 and
 .Ic \&So .
 .Ic \&Qq ,
 and
 .Ic \&So .

+.Tg Ss

 .It Ic \&Ss Ar Title line
 Begin a new subsection.
 Unlike with
 .It Ic \&Ss Ar Title line
 Begin a new subsection.
 Unlike with


@@ -2294,6 +2367,7 @@ See also
 .Ic \&Sh ,
 and
 .Ic \&Sx .
 .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.
 .It Ic \&St Fl Ns Ar abbreviation
 Replace an abbreviation for a standard with the full form.
 The following standards are recognised.


@@ -2504,6 +2578,7 @@ Ethernet local area networks.
 .St -ieee1275-94
 .El
 .El
 .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
 .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


@@ -2516,6 +2591,7 @@ See also
 .Ic \&Sh
 and
 .Ic \&Ss .
 .Ic \&Sh
 and
 .Ic \&Ss .

+.Tg Sy

 .It Ic \&Sy Ar word ...
 Request a boldface font.
 .Pp
 .It Ic \&Sy Ar word ...
 Request a boldface font.
 .Pp


@@ -2541,11 +2617,56 @@ See also
 .Ic \&No ,
 and
 .Ic \&Ql .
 .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 .
 .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
 .It Ic \&Tn Ar word ...
 Supported only for compatibility, do not use this in new manuals.
 Even though the macro name


@@ -2560,6 +2681,7 @@ Prints out
 Supported only for compatibility, do not use this in new manuals.
 Prints out
 .Dq Ux .
 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
 .It Ic \&Va Oo Ar type Oc Ar identifier ...
 A variable name.
 .Pp


@@ -2574,6 +2696,7 @@ For declarations of global variables in the
 .Em SYNOPSIS
 section, use
 .Ic \&Vt .
 .Em SYNOPSIS
 section, use
 .Ic \&Vt .

+.Tg Vt

 .It Ic \&Vt Ar type Op Ar identifier
 A variable type.
 .Pp
 .It Ic \&Vt Ar type Op Ar identifier
 A variable type.
 .Pp


@@ -2617,6 +2740,7 @@ beyond the end of the input line.
 This macro originally existed to work around the 9-argument limit
 of historic
 .Xr roff 7 .
 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 .
 .It Ic \&Xr Ar name section
 Link to another manual
 .Pq Qq cross-reference .


@@ -2679,7 +2803,7 @@ column, if applicable, describes closure rules.
 .Ss Block full-explicit
 Multi-line scope closed by an explicit closing macro.
 All macros contains bodies; only
 .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
 and
 .Pq optionally
 .Ic \&Bl


@@ -2910,6 +3034,7 @@ then the macro accepts an arbitrary number of arguments.
 .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 \&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
 .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


@@ -3003,6 +3128,13 @@ in the same way as a plain
 .Sq \&|
 character.
 Using this predefined string is not recommended in new manuals.
 .Sq \&|
 character.
 Using this predefined string is not recommended in new manuals.

+.Pp
+Appending a zero-width space
+.Pq Sq \e&
+to the end of an input line is also useful to prevent the interpretation
+of a trailing period, exclamation or question mark as the end of a
+sentence, for example when an abbreviation happens to occur
+at the end of a text or macro input line.

 .Ss Font handling
 In
 .Nm
 .Ss Font handling
 In
 .Nm


@@ -3030,17 +3162,6 @@ The following problematic behaviour is found in groff:
 .Pp
 .Bl -dash -compact
 .It
 .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 \&Pa
 does not format its arguments when used in the FILES section under
 certain list types.


@@ -3048,9 +3169,6 @@ certain list types.
 .Ic \&Ta
 can only be called by other macros, but not at the beginning of a line.
 .It
 .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
 .Sq \ef
 .Pq font face
 and


@@ -3100,10 +3218,16 @@ but produces large indentations.
 .Xr tbl 7
 .Pp
 The web page
 .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.
 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
 .Sh HISTORY
 The
 .Nm