=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.279 retrieving revision 1.286 diff -u -p -r1.279 -r1.286 --- mandoc/mdoc.7 2019/07/15 19:20:30 1.279 +++ mandoc/mdoc.7 2021/07/29 16:25:20 1.286 @@ -1,7 +1,7 @@ -.\" $Id: mdoc.7,v 1.279 2019/07/15 19:20:30 schwarze Exp $ +.\" $Id: mdoc.7,v 1.286 2021/07/29 16:25:20 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons -.\" Copyright (c) 2010, 2011, 2013-2018 Ingo Schwarze +.\" Copyright (c) 2010, 2011, 2013-2020 Ingo Schwarze .\" .\" 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. .\" -.Dd $Mdocdate: July 15 2019 $ +.Dd $Mdocdate: July 29 2021 $ .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 -The arguments are as follows: +The options are as follows: \&.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 \&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 @@ -1202,7 +1203,8 @@ Close a 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. @@ -1566,20 +1568,26 @@ and .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 . .It Ic \&Fn Ar funcname Op Ar argument ... @@ -1847,8 +1855,8 @@ instead. 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 . @@ -2548,6 +2556,49 @@ Table cell separator in .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 @@ -2681,7 +2732,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 -.Ic \s&Bf +.Ic \&Bf and .Pq optionally .Ic \&Bl @@ -2912,6 +2963,7 @@ then the macro accepts an arbitrary number of argument .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 @@ -3039,17 +3091,6 @@ The following problematic behaviour is found in groff: .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. @@ -3057,9 +3098,6 @@ 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 @@ -3109,10 +3147,16 @@ but produces large indentations. .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