Make it more explicit that the statement "-O tag does not work with less(1)"

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 0624ce788cd2104b289db5c53642c489fcc5aef9..00a15139afdd60be5e983ee65f7a08cf45404ded 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,7 +1,7 @@
-.\"    $Id: mdoc.7,v 1.276 2019/02/07 15:45:53 schwarze Exp $
+.\"    $Id: mdoc.7,v 1.282 2020/06/25 20:45:09 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: February 7 2019 $
+.Dd $Mdocdate: June 25 2020 $

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


@@ -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


@@ -596,6 +597,13 @@ block.
 Book or journal page number of an
 .Ic \&Rs
 block.
 Book or journal page number of an
 .Ic \&Rs
 block.

+Conventionally, the argument starts with
+.Ql p.\&
+for a single page or
+.Ql pp.\&
+for a range of pages, for example:
+.Pp
+.Dl .%P pp. 42\e(en47

 .It Ic \&%Q Ar name
 Institutional author (school, government, etc.) of an
 .Ic \&Rs
 .It Ic \&%Q Ar name
 Institutional author (school, government, etc.) of an
 .Ic \&Rs


@@ -1156,17 +1164,19 @@ declarations.
 This practise is discouraged.
 .It Ic \&Cm Ar keyword ...
 Command modifiers.
 This practise is discouraged.
 .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"

 .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


@@ -1193,7 +1203,8 @@ Close a
 block.
 Does not have any tail arguments.
 .It Ic \&Dd Cm $\&Mdocdate$ | Ar month day , year
 block.
 Does not have any tail arguments.
 .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.


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


@@ -1838,8 +1849,8 @@ instead.
 Format a hyperlink.
 .Pp
 Examples:
 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 .
 .Pp
 See also
 .Ic \&Mt .


@@ -2539,6 +2550,49 @@ Table cell separator in
 .Ic \&Bl Fl column
 lists; can only be used below
 .Ic \&It .
 .Ic \&Bl Fl column
 lists; can only be used below
 .Ic \&It .

+.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


@@ -2903,6 +2957,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


@@ -2969,7 +3024,7 @@ exclamation mark
 Note that even a period preceded by a backslash
 .Pq Sq \e.\&
 gets this special handling; use
 Note that even a period preceded by a backslash
 .Pq Sq \e.\&
 gets this special handling; use

-.Sq \e&.
+.Sq \e&.\&

 to prevent that.
 .Pp
 Many in-line macros interrupt their scope when they encounter
 to prevent that.
 .Pp
 Many in-line macros interrupt their scope when they encounter


@@ -2996,6 +3051,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


@@ -3023,17 +3085,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.


@@ -3041,9 +3092,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


@@ -3093,10 +3141,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 somehwat different style.

 .Sh HISTORY
 The
 .Nm
 .Sh HISTORY
 The
 .Nm