version 1.276, 2019/02/07 15:45:53 |
version 1.286, 2021/07/29 16:25:20 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" 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 |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
Line 297 utility does this, that, and the other. |
|
Line 297 utility does this, that, and the other. |
|
It usually follows with a breakdown of the options (if documenting a |
It usually follows with a breakdown of the options (if documenting a |
command), such as: |
command), such as: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
The arguments are as follows: |
The options are as follows: |
\&.Bl \-tag \-width Ds |
\&.Bl \-tag \-width Ds |
\&.It Fl v |
\&.It Fl v |
Print verbose information. |
Print verbose information. |
Line 449 in the alphabetical |
|
Line 449 in the alphabetical |
|
.It Ic \&Ss Ta subsection header (one line) |
.It Ic \&Ss Ta subsection header (one line) |
.It Ic \&Sx Ta internal cross reference to a section or subsection |
.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 \&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) |
.It Ic \&Pp Ta start a text paragraph (no arguments) |
.El |
.El |
.Ss Displays and lists |
.Ss Displays and lists |
|
|
Book or journal page number of an |
Book or journal page number of an |
.Ic \&Rs |
.Ic \&Rs |
block. |
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 |
.It Ic \&%Q Ar name |
Institutional author (school, government, etc.) of an |
Institutional author (school, government, etc.) of an |
.Ic \&Rs |
.Ic \&Rs |
|
|
This practise is discouraged. |
This practise is discouraged. |
.It Ic \&Cm Ar keyword ... |
.It Ic \&Cm Ar keyword ... |
Command modifiers. |
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 |
.Ic \&Fl |
is more appropriate. |
is more appropriate. |
Also useful when specifying configuration options or keys. |
|
.Pp |
.Pp |
Examples: |
Examples: |
.Dl ".Nm mt Fl f Ar device Cm rewind" |
.Dl ".Nm mt Fl f Ar device Cm rewind" |
.Dl ".Nm ps Fl o Cm pid , Ns Cm command" |
.Dl ".Nm ps Fl o Cm pid , Ns Cm command" |
.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2" |
.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2" |
.Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa" |
.Dl ".Ic set Fl o Cm vi" |
.Dl ".Cm LogLevel Dv DEBUG" |
.Dl ".Ic lookup Cm file bind" |
|
.Dl ".Ic permit Ar identity Op Cm as Ar target" |
.It Ic \&D1 Ar line |
.It Ic \&D1 Ar line |
One-line indented display. |
One-line indented display. |
This is formatted by the default rules and is useful for simple indented |
This is formatted by the default rules and is useful for simple indented |
|
|
block. |
block. |
Does not have any tail arguments. |
Does not have any tail arguments. |
.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 |
This is the mandatory first macro of any |
.Nm |
.Nm |
manual. |
manual. |
|
|
.It Ic \&Fl Op Ar word ... |
.It Ic \&Fl Op Ar word ... |
Command-line flag or option. |
Command-line flag or option. |
Used when listing arguments to command-line utilities. |
Used when listing arguments to command-line utilities. |
Prints a fixed-width hyphen |
For each argument, prints an ASCII hyphen-minus character |
.Sq \- |
.Sq \- , |
directly followed by each argument. |
immediately followed by the argument. |
If no arguments are provided, a hyphen is printed followed by a space. |
If no arguments are provided, a hyphen-minus is printed followed by a space. |
If the argument is a macro, a hyphen is prefixed to the subsequent macro |
If the argument is a macro, a hyphen-minus is prefixed |
output. |
to the subsequent macro output. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl ".Fl R Op Fl H | L | P" |
.Dl ".Nm du Op Fl H | L | P" |
.Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux" |
.Dl ".Nm ls Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux" |
.Dl ".Fl type Cm d Fl name Pa CVS" |
.Dl ".Nm route Cm add Fl inet Ar destination gateway" |
.Dl ".Fl Ar signal_number" |
.Dl ".Nm locate.updatedb Op Fl \e-fcodes Ns = Ns Ar dbfile" |
.Dl ".Fl o Fl" |
.Dl ".Nm aucat Fl o Fl" |
|
.Dl ".Nm kill Fl Ar signal_number" |
.Pp |
.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 |
See also |
.Ic \&Cm . |
.Ic \&Cm . |
.It Ic \&Fn Ar funcname Op Ar argument ... |
.It Ic \&Fn Ar funcname Op Ar argument ... |
Line 1677 This macro is not implemented in |
|
Line 1694 This macro is not implemented in |
|
.Xr mandoc 1 . |
.Xr mandoc 1 . |
It was used to include the contents of a (header) file literally. |
It was used to include the contents of a (header) file literally. |
.It Ic \&Ic Ar keyword ... |
.It Ic \&Ic Ar keyword ... |
Designate an internal or interactive command. |
Internal or interactive command, or configuration instruction |
This is similar to |
in a configuration file. |
.Ic \&Cm |
See also |
but used for instructions rather than values. |
.Ic \&Cm . |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Ic :wq |
.Dl \&.Ic :wq |
|
|
Format a hyperlink. |
Format a hyperlink. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq |
.Dl \&.Lk https://bsd.lv \(dqThe BSD.lv Project\(dq |
.Dl \&.Lk http://bsd.lv |
.Dl \&.Lk https://bsd.lv |
.Pp |
.Pp |
See also |
See also |
.Ic \&Mt . |
.Ic \&Mt . |
Line 2539 Table cell separator in |
|
Line 2556 Table cell separator in |
|
.Ic \&Bl Fl column |
.Ic \&Bl Fl column |
lists; can only be used below |
lists; can only be used below |
.Ic \&It . |
.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 ... |
.It Ic \&Tn Ar word ... |
Supported only for compatibility, do not use this in new manuals. |
Supported only for compatibility, do not use this in new manuals. |
Even though the macro name |
Even though the macro name |
Line 2672 column, if applicable, describes closure rules. |
|
Line 2732 column, if applicable, describes closure rules. |
|
.Ss Block full-explicit |
.Ss Block full-explicit |
Multi-line scope closed by an explicit closing macro. |
Multi-line scope closed by an explicit closing macro. |
All macros contains bodies; only |
All macros contains bodies; only |
.Ic \s&Bf |
.Ic \&Bf |
and |
and |
.Pq optionally |
.Pq optionally |
.Ic \&Bl |
.Ic \&Bl |
Line 2903 then the macro accepts an arbitrary number of argument |
|
Line 2963 then the macro accepts an arbitrary number of argument |
|
.It Ic \&St Ta \&No Ta Yes Ta 1 |
.It Ic \&St Ta \&No Ta Yes Ta 1 |
.It Ic \&Sx Ta Yes Ta Yes Ta >0 |
.It Ic \&Sx Ta Yes Ta Yes Ta >0 |
.It Ic \&Sy 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 \&Tn Ta Yes Ta Yes Ta >0 |
.It Ic \&Ud Ta \&No Ta \&No Ta 0 |
.It Ic \&Ud Ta \&No Ta \&No Ta 0 |
.It Ic \&Ux Ta Yes Ta Yes Ta n |
.It Ic \&Ux Ta Yes Ta Yes Ta n |
Line 2969 exclamation mark |
|
Line 3030 exclamation mark |
|
Note that even a period preceded by a backslash |
Note that even a period preceded by a backslash |
.Pq Sq \e.\& |
.Pq Sq \e.\& |
gets this special handling; use |
gets this special handling; use |
.Sq \e&. |
.Sq \e&.\& |
to prevent that. |
to prevent that. |
.Pp |
.Pp |
Many in-line macros interrupt their scope when they encounter |
Many in-line macros interrupt their scope when they encounter |
Line 2996 in the same way as a plain |
|
Line 3057 in the same way as a plain |
|
.Sq \&| |
.Sq \&| |
character. |
character. |
Using this predefined string is not recommended in new manuals. |
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 |
.Ss Font handling |
In |
In |
.Nm |
.Nm |
Line 3023 The following problematic behaviour is found in groff: |
|
Line 3091 The following problematic behaviour is found in groff: |
|
.Pp |
.Pp |
.Bl -dash -compact |
.Bl -dash -compact |
.It |
.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 |
.Ic \&Pa |
does not format its arguments when used in the FILES section under |
does not format its arguments when used in the FILES section under |
certain list types. |
certain list types. |
Line 3041 certain list types. |
|
Line 3098 certain list types. |
|
.Ic \&Ta |
.Ic \&Ta |
can only be called by other macros, but not at the beginning of a line. |
can only be called by other macros, but not at the beginning of a line. |
.It |
.It |
.Ic \&%C |
|
is not implemented (up to and including groff-1.22.2). |
|
.It |
|
.Sq \ef |
.Sq \ef |
.Pq font face |
.Pq font face |
and |
and |
Line 3093 but produces large indentations. |
|
Line 3147 but produces large indentations. |
|
.Xr tbl 7 |
.Xr tbl 7 |
.Pp |
.Pp |
The web page |
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 |
provides a few tutorial-style pages for beginners, an extensive style |
guide for advanced authors, and an alphabetic index helping to choose |
guide for advanced authors, and an alphabetic index helping to choose |
the best macros for various kinds of content. |
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 |
.Sh HISTORY |
The |
The |
.Nm |
.Nm |