diff options
Diffstat (limited to 'mdoc.7')
| -rw-r--r-- | mdoc.7 | 339 |
1 files changed, 195 insertions, 144 deletions
@@ -101,9 +101,11 @@ for two-character sequences; an open-bracket .Sq \&[ for n-character sequences (terminated at a close-bracket .Sq \&] ) ; -or a single one-character sequence. See +or a single one-character sequence. +See .Xr mandoc_char 7 -for a complete list. Examples include +for a complete list. +Examples include .Sq \e(em .Pq em-dash and @@ -118,14 +120,16 @@ escape followed by an indicator: B (bold), I, (italic), R (Roman), or P .D1 \efBbold\efR \efIitalic\efP .Pp A numerical representation 3, 2, or 1 (bold, italic, and Roman, -respectively) may be used instead. A text decoration is valid within +respectively) may be used instead. +A text decoration is valid within the current font scope only: if a macro opens a font scope alongside its own scope, such as .Sx \&Bf .Cm \&Sy , in-scope invocations of .Sq \ef -are only valid within the font scope of the macro. If +are only valid within the font scope of the macro. +If .Sq \ef is specified outside of any font scope, such as in unenclosed, free-form text, it will affect the remainder of the document. @@ -174,7 +178,8 @@ and N-character .Sq \e*[N] . See .Xr mandoc_char 7 -for a complete list. Examples include +for a complete list. +Examples include .Sq \e*(Am .Pq ampersand and @@ -187,14 +192,14 @@ trailing spaces are stripped from input (unless in a literal context). Blank free-form lines, which may include whitespace, are only permitted within literal contexts. .Pp -In macro lines, whitespace delimits arguments and is discarded. If -arguments are quoted, whitespace within the quotes is retained. +In macro lines, whitespace delimits arguments and is discarded. +If arguments are quoted, whitespace within the quotes is retained. .Ss Quotation Macro arguments may be quoted with a double-quote to group -space-delimited terms or to retain blocks of whitespace. A quoted -argument begins with a double-quote preceded by whitespace. The next -double-quote not pair-wise adjacent to another double-quote terminates -the literal, regardless of surrounding whitespace. +space-delimited terms or to retain blocks of whitespace. +A quoted argument begins with a double-quote preceded by whitespace. +The next double-quote not pair-wise adjacent to another double-quote +terminates the literal, regardless of surrounding whitespace. .Pp This produces tokens .Sq a" , @@ -203,7 +208,8 @@ This produces tokens and .Sq fg" . Note that any quoted term, be it argument or macro, is indiscriminately -considered literal text. Thus, the following produces +considered literal text. +Thus, the following produces .Sq \&Em a : .Bd -literal -offset indent \&.Em "Em a" @@ -213,16 +219,18 @@ In free-form mode, quotes are regarded as opaque text. .Ss Dates There are several macros in .Nm -that require a date argument. The canonical form for dates is the -American format: +that require a date argument. +The canonical form for dates is the American format: .Pp .D1 Cm Month Day , Year .Pp The .Cm Day -value is an optionally zero-padded numeral. The +value is an optionally zero-padded numeral. +The .Cm Month -value is the full month name. The +value is the full month name. +The .Cm Year value is the full four-digit year. .Pp @@ -246,8 +254,8 @@ stipulating a two-inch list indentation with the following: The syntax for scaled widths is .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , where a decimal must be preceded or proceeded by at least one digit. -Negative numbers, while accepted, are truncated to zero. The following -scaling units are accepted: +Negative numbers, while accepted, are truncated to zero. +The following scaling units are accepted: .Pp .Bl -tag -width Ds -offset indent -compact .It c @@ -285,7 +293,8 @@ Using anything other than .Sq u , or .Sq v -is necessarily non-portable across output media. See +is necessarily non-portable across output media. +See .Sx COMPATIBILITY . .Sh MANUAL STRUCTURE A well-formed @@ -358,12 +367,12 @@ utility processes files ... .Pp The sections in a .Nm -document are conventionally ordered as they appear above. Sections -should be composed as follows: +document are conventionally ordered as they appear above. +Sections should be composed as follows: .Bl -ohang -offset Ds .It Em NAME -The name(s) and a short description of the documented material. The -syntax for this as follows: +The name(s) and a short description of the documented material. +The syntax for this as follows: .Bd -literal -offset indent \&.Nm name0 \&.Nm name1 @@ -383,8 +392,8 @@ and .Sx \&Nd . .It Em LIBRARY The name of the library containing the documented material, which is -assumed to be a function in a section 2 or 3 manual. The syntax for -this is as follows: +assumed to be a function in a section 2 or 3 manual. +The syntax for this is as follows: .Bd -literal -offset indent \&.Lb libarm .Ed @@ -449,14 +458,14 @@ Print verbose information. .Pp Manuals not documenting a command won't include the above fragment. .It Em IMPLEMENTATION NOTES -Implementation-specific notes should be kept here. This is useful when -implementing standard functions that may have side effects or notable -algorithmic implications. +Implementation-specific notes should be kept here. +This is useful when implementing standard functions that may have side +effects or notable algorithmic implications. .It Em RETURN VALUES This section is the dual of .Em EXIT STATUS , -which is used for commands. It documents the return values of functions -in sections 2, 3, and 9. +which is used for commands. +It documents the return values of functions in sections 2, 3, and 9. .Pp See .Sx \&Rv . @@ -467,28 +476,30 @@ Documents any usages of environment variables, e.g., See .Sx \&Ev . .It Em FILES -Documents files used. It's helpful to document both the file and a -short description of how the file is used (created, modified, etc.). +Documents files used. +It's helpful to document both the file and a short description of how +the file is used (created, modified, etc.). .Pp See .Sx \&Pa . .It Em EXIT STATUS -Command exit status for section 1, 6, and 8 manuals. This section is -the dual of +Command exit status for section 1, 6, and 8 manuals. +This section is the dual of .Em RETURN VALUES , -which is used for functions. Historically, this information was -described in +which is used for functions. +Historically, this information was described in .Em DIAGNOSTICS , a practise that is now discouraged. .Pp See .Sx \&Ex . .It Em EXAMPLES -Example usages. This often contains snippets of well-formed, -well-tested invocations. Make doubly sure that your examples work -properly! +Example usages. +This often contains snippets of well-formed, well-tested invocations. +Make doubly sure that your examples work properly! .It Em DIAGNOSTICS -Documents error conditions. This is most useful in section 4 manuals. +Documents error conditions. +This is most useful in section 4 manuals. Historically, this section was used in place of .Em EXIT STATUS for manuals in sections 1, 6, and 8; however, this practise is @@ -503,15 +514,16 @@ Documents error handling in sections 2, 3, and 9. See .Sx \&Er . .It Em SEE ALSO -References other manuals with related topics. This section should exist -for most manuals. Cross-references should conventionally be ordered -first by section, then alphabetically. +References other manuals with related topics. +This section should exist for most manuals. +Cross-references should conventionally be ordered first by section, then +alphabetically. .Pp See .Sx \&Xr . .It Em STANDARDS -References any standards implemented or used. If not adhering to any -standards, the +References any standards implemented or used. +If not adhering to any standards, the .Em HISTORY section should be used instead. .Pp @@ -539,15 +551,17 @@ Documents any security precautions that operators should consider. Macros are one to three three characters in length and begin with a control character , .Sq \&. , -at the beginning of the line. An arbitrary amount of whitespace may -sit between the control character and the macro name. Thus, the -following are equivalent: +at the beginning of the line. +An arbitrary amount of whitespace may sit between the control character +and the macro name. +Thus, the following are equivalent: .Bd -literal -offset indent \&.Pp \&.\ \ \ \&Pp .Ed .Pp -The syntax of a macro depends on its classification. In this section, +The syntax of a macro depends on its classification. +In this section, .Sq \-arg refers to macro arguments, which may be followed by zero or more .Sq parm @@ -560,8 +574,9 @@ closes it out. The .Em Callable column indicates that the macro may be called subsequent to the initial -line-macro. If a macro is not callable, then its invocation after the -initial line macro is interpreted as opaque text, such that +line-macro. +If a macro is not callable, then its invocation after the initial line +macro is interpreted as opaque text, such that .Sq \&.Fl \&Sh produces .Sq Fl \&Sh . @@ -569,15 +584,16 @@ produces The .Em Parsable column indicates whether the macro may be followed by further -(ostensibly callable) macros. If a macro is not parsable, subsequent -macro invocations on the line will be interpreted as opaque text. +(ostensibly callable) macros. +If a macro is not parsable, subsequent macro invocations on the line +will be interpreted as opaque text. .Pp The .Em Scope column, if applicable, describes closure rules. .Ss Block full-explicit -Multi-line scope closed by an explicit closing macro. All macros -contains bodies; only +Multi-line scope closed by an explicit closing macro. +All macros contains bodies; only .Sx \&Bf contains a head. .Bd -literal -offset indent @@ -625,8 +641,8 @@ has multiple heads. .It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss .El .Ss Block partial-explicit -Like block full-explicit, but also with single-line scope. Each -has at least a body and, in limited circumstances, a head +Like block full-explicit, but also with single-line scope. +Each has at least a body and, in limited circumstances, a head .Po .Sx \&Fo , .Sx \&Eo @@ -703,9 +719,9 @@ in a SYNOPSIS section line, else it is .Ss In-line Closed by .Sx Reserved Characters , -end of line, fixed argument lengths, and/or subsequent macros. In-line -macros have only text children. If a number (or inequality) of -arguments is +end of line, fixed argument lengths, and/or subsequent macros. +In-line macros have only text children. +If a number (or inequality) of arguments is .Pq n , then the macro accepts an arbitrary number of arguments. .Bd -literal -offset indent @@ -795,7 +811,8 @@ then the macro accepts an arbitrary number of arguments. .El .Sh REFERENCE This section is a canonical reference of all macros, arranged -alphabetically. For the scoping of individual macros, see +alphabetically. +For the scoping of individual macros, see .Sx MACRO SYNTAX . .Ss \&%A Author name of an @@ -876,8 +893,9 @@ Examples: .D1 \&.Ad [0,$] .D1 \&.Ad 0x00000000 .Ss \&An -Author name. This macro may alternatively accepts the following -arguments, although these may not be specified along with a parameter: +Author name. +This macro may alternatively accepts the following arguments, although +these may not be specified along with a parameter: .Bl -tag -width 12n -offset indent .It Fl split Renders a line break before each author listing. @@ -888,10 +906,11 @@ The opposite of .Pp In the AUTHORS section, the default is not to split the first author listing, but all subsequent author listings, whether or not they're -interspersed by other macros or text, are split. Thus, specifying +interspersed by other macros or text, are split. +Thus, specifying .Fl split -will cause the first listing also to be split. If not in the AUTHORS -section, the default is not to split. +will cause the first listing also to be split. +If not in the AUTHORS section, the default is not to split. .Pp Examples: .D1 \&.An -nosplit @@ -907,8 +926,8 @@ are re-set when entering the AUTHORS section, so if one specifies in the general document body, it must be re-specified in the AUTHORS section. .Ss \&Ao -Begins a block enclosed by angled brackets. Does not have any head -arguments. +Begins a block enclosed by angled brackets. +Does not have any head arguments. .Pp Examples: .D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac @@ -916,9 +935,9 @@ Examples: See also .Sx \&Aq . .Ss \&Ap -Inserts an apostrophe without any surrounding white-space. This is -generally used as a grammatic device when referring to the verb form of -a function: +Inserts an apostrophe without any surrounding white-space. +This is generally used as a grammatic device when referring to the verb +form of a function: .Bd -literal -offset indent \&.Fn execve Ap d .Ed @@ -941,7 +960,8 @@ statements, which should use See also .Sx \&Ao . .Ss \&Ar -Command arguments. If an argument is not provided, the string +Command arguments. +If an argument is not provided, the string .Dq file ... is used as a default. .Pp @@ -950,7 +970,8 @@ Examples: .D1 \&.Ar .D1 \&.Ar arg1 , arg2 . .Ss \&At -Formats an AT&T version. Accepts at most one parameter: +Formats an AT&T version. +Accepts at most one parameter: .Bl -tag -width 12n -offset indent .It Cm v[1-7] | 32v A version of @@ -980,10 +1001,11 @@ Closes a .Sx \&Bo block. Does not have any tail arguments. .Ss \&Bd -Begins a display block. A display is collection of macros or text which -may be collectively offset or justified in a manner different from that -of the enclosing context. By default, the block is preceded by a -vertical space. +Begins a display block. +A display is collection of macros or text which may be collectively +offset or justified in a manner different from that +of the enclosing context. +By default, the block is preceded by a vertical space. .Pp Each display is associated with a type, which must be one of the following arguments: @@ -1001,7 +1023,8 @@ Alias for Centre-justify each line. .El .Pp -The type must be provided first. Secondary arguments are as follows: +The type must be provided first. +Secondary arguments are as follows: .Bl -tag -width 12n -offset indent .It Fl offset Ar width Offset by the value of @@ -1022,8 +1045,8 @@ which justifies to the right margin; and .Ar center , which aligns around an imagined centre axis. .It -As a precalculated width for a named macro. The most popular is the -imaginary macro +As a precalculated width for a named macro. +The most popular is the imaginary macro .Ar \&Ds , which resolves to .Ar 6n . @@ -1115,8 +1138,8 @@ and .\" More... .\" . .Ss \&Bo -Begins a block enclosed by square brackets. Does not have any head -arguments. +Begins a block enclosed by square brackets. +Does not have any head arguments. .Pp Examples: .Bd -literal -offset indent @@ -1147,8 +1170,8 @@ Closes a .Sx \&Bro block. Does not have any tail arguments. .Ss \&Bro -Begins a block enclosed by curly braces. Does not have any head -arguments. +Begins a block enclosed by curly braces. +Does not have any head arguments. .Pp Examples: .Bd -literal -offset indent @@ -1204,7 +1227,8 @@ See also and .Sx \&Ux . .Ss \&Cd -Configuration declaration. This denotes strings accepted by +Configuration declaration. +This denotes strings accepted by .Xr config 8 . .Pp Examples: @@ -1214,10 +1238,11 @@ Examples: this macro is commonly abused by using quoted literals to retain white-space and align consecutive .Sx \&Cd -declarations. This practise is discouraged. +declarations. +This practise is discouraged. .Ss \&Cm -Command modifiers. Useful when specifying configuration options or -keys. +Command modifiers. +Useful when specifying configuration options or keys. .Pp Examples: .D1 \&.Cm ControlPath @@ -1226,8 +1251,10 @@ Examples: See also .Sx \&Fl . .Ss \&D1 -One-line indented display. This is formatted by the default rules and -is useful for simple indented statements. It is followed by a newline. +One-line indented display. +This is formatted by the default rules and is useful for simple indented +statements. +It is followed by a newline. .Pp Examples: .D1 \&.D1 \&Fl abcdefgh @@ -1242,9 +1269,11 @@ Closes a .Sx \&Do block. Does not have any tail arguments. .Ss \&Dd -Document date. This is the mandatory first macro of any +Document date. +This is the mandatory first macro of any .Nm -manual. Its calling syntax is as follows: +manual. +Its calling syntax is as follows: .Pp .D1 \. Ns Sx \&Dd Cm date .Pp @@ -1268,8 +1297,10 @@ See also and .Sx \&Os . .Ss \&Dl -One-line intended display. This is formatted as literal text and is -useful for commands and invocations. It is followed by a newline. +One-line intended display. +This is formatted as literal text and is useful for commands and +invocations. +It is followed by a newline. .Pp Examples: .D1 \&.Dl % mandoc mdoc.7 | less @@ -1299,19 +1330,22 @@ Examples: See also .Sx \&Do . .Ss \&Dt -Document title. This is the mandatory second macro of any +Document title. +This is the mandatory second macro of any .Nm -file. Its calling syntax is as follows: +file. +Its calling syntax is as follows: .Pp .D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch .Pp Its arguments are as follows: .Bl -tag -width Ds -offset Ds .It Cm title -The document's title (name). This should be capitalised and is -required. +The document's title (name). +This should be capitalised and is required. .It Cm section -The manual section. This may be one of +The manual section. +This may be one of .Ar 1 .Pq utilities , .Ar 2 @@ -1377,10 +1411,13 @@ or .Ar CON .Pq contributed manuals . .It Cm arch -This specifies a specific relevant architecture. If +This specifies a specific relevant architecture. +If .Cm volume is not provided, it may be used in its place, else it may be used -subsequent that. It, too, is optional. It must be one of +subsequent that. +It, too, is optional. +It must be one of .Ar alpha , .Ar amd64 , .Ar amiga , @@ -1453,9 +1490,9 @@ and .Ss \&Ek .Ss \&El .Ss \&Em -Denotes text that should be emphasised. Note that this is a -presentation term and should not be used for stylistically decorating -technical terms. +Denotes text that should be emphasised. +Note that this is a presentation term and should not be used for +stylistically decorating technical terms. .Pp Examples: .D1 \&.Em Warnings! @@ -1480,8 +1517,8 @@ Examples: .D1 \&.Ev DISPLAY .D1 \&.Ev PATH .Ss \&Ex -Inserts text regarding a utility's exit values. This macro must have -first the +Inserts text regarding a utility's exit values. +This macro must have first the .Fl std argument specified, then an optional .Ar utility . @@ -1494,12 +1531,14 @@ is provided. .Ss \&Fc .Ss \&Fd .Ss \&Fl -Command-line flag. Used when listing arguments to command-line -utilities. Prints a fixed-width hyphen +Command-line flag. +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. +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. .Pp Examples: .D1 \&.Fl a b c @@ -1537,7 +1576,8 @@ and .Ss \&Lb .Ss \&Li .Ss \&Lk -Format a hyperlink. The calling syntax is as follows: +Format a hyperlink. +The calling syntax is as follows: .Pp .D1 \. Ns Sx \&Lk Cm uri Op Cm name .Pp @@ -1575,7 +1615,8 @@ and .Ss \&Oo .Ss \&Op .Ss \&Os -Document operating system version. This is the mandatory third macro of +Document operating system version. +This is the mandatory third macro of any .Nm file. Its calling syntax is as follows: @@ -1584,9 +1625,9 @@ file. Its calling syntax is as follows: .Pp The optional .Cm system -parameter specifies the relevant operating system or environment. Left -unspecified, it defaults to the local operating system version. This is -the suggested form. +parameter specifies the relevant operating system or environment. +Left unspecified, it defaults to the local operating system version. +This is the suggested form. .Pp Examples: .D1 \&.Os @@ -1632,12 +1673,14 @@ and .Ss \&Re Closes a .Sx \&Rs -block. Does not have any tail arguments. +block. +Does not have any tail arguments. .Ss \&Rs Begins a bibliographic .Pq Dq reference -block. Does not have any head arguments. The block macro may only -contain +block. +Does not have any head arguments. +The block macro may only contain .Sx \&%A , .Sx \&%B , .Sx \&%C , @@ -1684,7 +1727,8 @@ line. .Ss \&Tn .Ss \&Ud .Ss \&Ux -Format the UNIX name. Accepts no argument. +Format the UNIX name. +Accepts no argument. .Pp Examples: .D1 \&.Ux @@ -1700,9 +1744,10 @@ and .Sx \&Ox . .Ss \&Va .Ss \&Vt -A variable type. This is also used for indicating global variables in the -SYNOPSIS section, in which case a variable name is also specified. Note that -it accepts +A variable type. +This is also used for indicating global variables in the SYNOPSIS +section, in which case a variable name is also specified. +Note that it accepts .Sx Block partial-implicit syntax when invoked as the first macro in the SYNOPSIS section, else it accepts ordinary @@ -1725,9 +1770,9 @@ and Close a scope opened by .Sx \&Xo . .Ss \&Xo -Open an extension scope. This macro originally existed to extend the -9-argument limit of troff; since this limit has been lifted, the macro -has been deprecated. +Open an extension scope. +This macro originally existed to extend the 9-argument limit of troff; +since this limit has been lifted, the macro has been deprecated. .Ss \&Xr Link to another manual .Pq Qq cross-reference . @@ -1739,12 +1784,13 @@ The .Cm name and .Cm section -are the name and section of the linked manual. If +are the name and section of the linked manual. +If .Cm section is followed by non-punctuation, an .Sx \&Ns -is inserted into the token stream. This behaviour is for compatibility -with +is inserted into the token stream. +This behaviour is for compatibility with .Xr groff 1 . .Pp Examples: @@ -1776,25 +1822,29 @@ is no longer accepted. In groff, the .Sx \&Pa macro does not format its arguments when used in the FILES section under -certain list types. mandoc does. +certain list types. +mandoc does. .It Historic groff does not print a dash for empty .Sx \&Fl -arguments. mandoc and newer groff implementations do. +arguments. +mandoc and newer groff implementations do. .It groff behaves irregularly when specifying .Sq \ef .Sx Text Decoration -within line-macro scopes. mandoc follows a consistent system. +within line-macro scopes. +mandoc follows a consistent system. .It In mandoc, negative scaling units are truncated to zero; groff would -move to prior lines. Furthermore, the +move to prior lines. +Furthermore, the .Sq f scaling unit, while accepted, is rendered as the default unit. .It In quoted literals, groff allowed pair-wise double-quotes to produce a -standalone double-quote in formatted output. This idiosyncratic -behaviour is not applicable in mandoc. +standalone double-quote in formatted output. +This idiosyncratic behaviour is not applicable in mandoc. .It Display types .Sx \&Bd @@ -1805,8 +1855,8 @@ are aliases for .Fl left in manodc. Furthermore, the .Fl file Ar file -argument is ignored. Lastly, since text is not right-justified in -mandoc (or even groff), +argument is ignored. +Lastly, since text is not right-justified in mandoc (or even groff), .Fl ragged and .Fl filled @@ -1815,8 +1865,8 @@ are aliases, as are and .Fl unfilled . .It -Historic groff has many un-callable macros. Most of these (excluding -some block-level macros) are now callable. +Historic groff has many un-callable macros. +Most of these (excluding some block-level macros) are now callable. .It The vertical bar .Sq \(ba @@ -1833,20 +1883,21 @@ lists will restart the sequence only for the sub-list. Some manuals use .Sx \&Li incorrectly by following it with a reserved character and expecting the -delimiter to render. This is not supported in mandoc. +delimiter to render. +This is not supported in mandoc. .It In groff, the .Sx \&Fo -macro only produces the first parameter. This is not the case in -mandoc. +macro only produces the first parameter. +This is not the case in mandoc. .It In groff, the .Sx \&Cd , .Sx \&Er , and .Sx \&Ex -macros were stipulated only to occur in certain manual sections. mandoc -does not have these restrictions. +macros were stipulated only to occur in certain manual sections. +mandoc does not have these restrictions. .El .Sh SEE ALSO .Xr mandoc 1 , |