diff options
Diffstat (limited to 'usr.bin/mandoc/mdoc.7')
| -rw-r--r-- | usr.bin/mandoc/mdoc.7 | 466 |
1 files changed, 240 insertions, 226 deletions
diff --git a/usr.bin/mandoc/mdoc.7 b/usr.bin/mandoc/mdoc.7 index 1d64e581ead..80539686241 100644 --- a/usr.bin/mandoc/mdoc.7 +++ b/usr.bin/mandoc/mdoc.7 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.41 2010/07/25 18:05:54 schwarze Exp $ +.\" $Id: mdoc.7,v 1.42 2010/07/31 22:07:11 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv> .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org> @@ -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 25 2010 $ +.Dd $Mdocdate: July 31 2010 $ .Dt MDOC 7 .Os .Sh NAME @@ -93,10 +93,10 @@ Within a macro line, the following characters are reserved: .Pp Use of reserved characters is described in .Sx MACRO SYNTAX . -For general use in macro lines, these characters must either be escaped +For general use in macro lines, these characters can either be escaped with a non-breaking space .Pq Sq \e& -or, if applicable, an appropriate escape sequence used. +or, if applicable, an appropriate escape sequence can be used. .Ss Special Characters Special characters may occur in both macro and free-form lines. Sequences begin with the escape character @@ -201,24 +201,18 @@ within literal contexts. 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 +Macro arguments may be quoted with double-quotes 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. .Pp -This produces tokens -.Sq a" , -.Sq b c , -.Sq de , -and -.Sq fg" . -Note that any quoted term, be it argument or macro, is indiscriminately -considered literal text. +Note that any quoted text, even if it would cause a macro invocation +when unquoted, is considered literal text. Thus, the following produces -.Sq \&Em a : +.Sq Op "Fl a" : .Bd -literal -offset indent -\&.Em "Em a" +\&.Op "Fl a" .Ed .Pp In free-form mode, quotes are regarded as opaque text. @@ -325,12 +319,12 @@ A well-formed document consists of a document prologue followed by one or more sections. .Pp -The prologue, which consists of (in order) the +The prologue, which consists of the .Sx \&Dd , .Sx \&Dt , and .Sx \&Os -macros, is required for every document. +macros in that order, is required for every document. .Pp The first section (sections are denoted by .Sx \&Sh ) @@ -394,13 +388,13 @@ 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 name(s) and a one-line description of the documented material. The syntax for this as follows: .Bd -literal -offset indent \&.Nm name0 \&.Nm name1 \&.Nm name2 -\&.Nd a short description +\&.Nd a one-line description .Ed .Pp The @@ -493,7 +487,7 @@ with the text immediately following the .Sx \&Nm macro, up to the next .Sx \&Nm , -.Sx \&Sx , +.Sx \&Sh , or .Sx \&Ss macro or the end of an enclosing block, whichever comes first. @@ -524,14 +518,17 @@ It documents the return values of functions in sections 2, 3, and 9. See .Sx \&Rv . .It Em ENVIRONMENT -Documents any usages of environment variables, e.g., -.Xr environ 7 . +Lists the environment variables used by the utility, +and explains the syntax and semantics of their values. +The +.Xr environ 7 +manual provides examples of typical content and formatting. .Pp See .Sx \&Ev . .It Em FILES Documents files used. -It's helpful to document both the file and a short description of how +It's helpful to document both the file name and a short description of how the file is used (created, modified, etc.). .Pp See @@ -589,21 +586,22 @@ The history of any manual without a section should be described in this section. .It Em AUTHORS Credits to authors, if applicable, should appear in this section. -Authors should generally be noted by both name and an e-mail address. +Authors should generally be noted by both name and email address. .Pp See .Sx \&An . .It Em CAVEATS -Explanations of common misuses and misunderstandings should be explained +Common misuses and misunderstandings should be explained in this section. .It Em BUGS -Extant bugs should be described in this section. +Known bugs, limitations and work-arounds should be described +in this section. .It Em SECURITY CONSIDERATIONS Documents any security precautions that operators should consider. .El .Sh MACRO SYNTAX Macros are one to three three characters in length and begin with a -control character , +control character, .Sq \&. , at the beginning of the line. An arbitrary amount of whitespace may sit between the control character @@ -636,10 +634,10 @@ produces .Sq Fl \&Sh . .Pp The -.Em Parsable +.Em Parsed 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 +If a macro is not parsed, subsequent macro invocations on the line will be interpreted as opaque text. .Pp The @@ -656,8 +654,8 @@ contains a head. \&.Yc .Ed .Pp -.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX" -.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope +.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXX" +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope .It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed .It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef .It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek @@ -679,7 +677,9 @@ All macros have bodies; some .Pc don't have heads; only one .Po -.Sx \&It Fl column +.Sx \&It +in +.Sx \&Bl Fl column .Pc has multiple heads. .Bd -literal -offset indent @@ -687,8 +687,8 @@ has multiple heads. \(lBbody...\(rB .Ed .Pp -.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX" -.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope +.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope .It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El .It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh .It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss @@ -723,8 +723,8 @@ and/or tail \(lBbody...\(rB \&Yc \(lBtail...\(rB .Ed .Pp -.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent -.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope .It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao .It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac .It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo @@ -758,8 +758,8 @@ or end of line. \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB .Ed .Pp -.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent -.It Em Macro Ta Em Callable Ta Em Parsable +.Bl -column "MacroX" "CallableX" "ParsedX" -compact -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed .It Sx \&Aq Ta Yes Ta Yes .It Sx \&Bq Ta Yes Ta Yes .It Sx \&Brq Ta Yes Ta Yes @@ -799,8 +799,8 @@ then the macro accepts an arbitrary number of arguments. \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN .Ed .Pp -.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent -.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments +.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -compact -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments .It Sx \&%A Ta \&No Ta \&No Ta >0 .It Sx \&%B Ta \&No Ta \&No Ta >0 .It Sx \&%C Ta \&No Ta \&No Ta >0 @@ -826,7 +826,7 @@ then the macro accepts an arbitrary number of arguments. .It Sx \&Cd Ta Yes Ta Yes Ta >0 .It Sx \&Cm Ta Yes Ta Yes Ta n .It Sx \&Db Ta \&No Ta \&No Ta 1 -.It Sx \&Dd Ta \&No Ta \&No Ta >0 +.It Sx \&Dd Ta \&No Ta \&No Ta n .It Sx \&Dt Ta \&No Ta \&No Ta n .It Sx \&Dv Ta Yes Ta Yes Ta n .It Sx \&Dx Ta Yes Ta Yes Ta n @@ -954,60 +954,50 @@ Volume number of an .Sx \&Rs block. .Ss \&Ac -Closes an +Close an .Sx \&Ao block. Does not have any tail arguments. .Ss \&Ad -Address construct: usually in the context of an computational address in -memory, not a physical (post) address. +Memory address. +Do not use this for postal addresses. .Pp 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: +Requires either the name of an author or one of the following arguments: .Pp .Bl -tag -width "-nosplitX" -offset indent -compact .It Fl split -Renders a line break before each author listing. +Start a new output line before each subsequent invocation of +.Sx \&An . .It Fl nosplit The opposite of .Fl split . .El .Pp +The default is +.Fl nosplit . +The effect of selecting either of the +.Fl split +modes ends at the beginning of the +.Em AUTHORS +section. In the .Em 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 +section, the default is +.Fl nosplit +for the first author listing and .Fl split -will cause the first listing also to be split. -If not in the -.Em AUTHORS -section, the default is not to split. +for all other author listings. .Pp Examples: .D1 \&.An -nosplit -.D1 \&.An J. D. Ullman . -.Pp -.Em Remarks : -the effects of -.Fl split -or -.Fl nosplit -are re-set when entering the -.Em AUTHORS -section, so if one specifies -.Sx \&An Fl nosplit -in the general document body, it must be re-specified in the -.Em AUTHORS -section. +.D1 \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv .Ss \&Ao -Begins a block enclosed by angled brackets. +Begin a block enclosed by angle brackets. Does not have any head arguments. .Pp Examples: @@ -1023,7 +1013,7 @@ form of a function. Examples: .D1 \&.Fn execve \&Ap d .Ss \&Aq -Encloses its arguments in angled brackets. +Encloses its arguments in angle brackets. .Pp Examples: .D1 \&.Fl -key= \&Ns \&Aq \&Ar val @@ -1043,7 +1033,7 @@ See also .Ss \&Ar Command arguments. If an argument is not provided, the string -.Dq file ... +.Dq file ...\& is used as a default. .Pp Examples: @@ -1052,18 +1042,18 @@ Examples: .D1 \&.Ar arg1 , arg2 . .Ss \&At Formats an AT&T version. -Accepts at most one parameter: +Accepts one optional argument: .Pp .Bl -tag -width "v[1-7] | 32vX" -offset indent -compact .It Cm v[1-7] | 32v A version of .At . .It Cm V[.[1-4]]? -A system version of -.At . +A version of +.At V . .El .Pp -Note that these parameters do not begin with a hyphen. +Note that these arguments do not begin with a hyphen. .Pp Examples: .D1 \&.At @@ -1079,83 +1069,93 @@ See also and .Sx \&Ux . .Ss \&Bc -Closes a +Close a .Sx \&Bo block. Does not have any tail arguments. .Ss \&Bd -Begins a display block. +Begin a display block. Its syntax is as follows: .Bd -ragged -offset indent .Pf \. Sx \&Bd -.Fl type +.Fl Ns Ar type .Op Fl offset Ar width .Op Fl compact .Ed .Pp -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. +Display blocks are used to select a different indentation and +justification than the one used by the surrounding text. +They may contain both macro lines and free-form text lines. +By default, a display block is preceded by a vertical space. .Pp -Each display is associated with a type, which must be one of the -following arguments: -.Bl -tag -width 12n -offset indent -.It Fl ragged -Only left-justify the block. -.It Fl unfilled -Do not justify the block at all. +The +.Ar type +must be one of the following: +.Bl -tag -width 13n -offset indent +.It Fl centered +Centre-justify each line. +Using this display type is not recommended; many +.Nm +implementations render it poorly. .It Fl filled Left- and right-justify the block. .It Fl literal -Alias for -.Fl unfilled . -.It Fl centered -Centre-justify each line. +Do not justify the block at all. +Preserve white space as it appears in the input. +.It Fl ragged +Only left-justify the block. +.It Fl unfilled +An alias for +.Fl literal . .El .Pp -The type must be provided first. -Secondary arguments are as follows: -.Bl -tag -width 12n -offset indent -.It Fl offset Ar val -Offset by the value of -.Ar val , -which is interpreted as one of the following, specified in order: +The +.Ar type +must be provided first. +Additional arguments may follow: +.Bl -tag -width 13n -offset indent +.It Fl offset Ar width +Indent the display by the +.Ar width , +which may be one of the following: .Bl -item .It -As one of the pre-defined strings -.Ar indent , +One of the pre-defined strings +.Cm indent , the width of standard indentation; -.Ar indent-two , +.Cm indent-two , twice -.Ar indent ; -.Ar left , +.Cm indent ; +.Cm left , which has no effect; -.Ar right , -which justifies to the right margin; and -.Ar center , +.Cm right , +which justifies to the right margin; or +.Cm center , which aligns around an imagined centre axis. .It -As a precalculated width for a named macro. +A macro invocation, which selects a predefined width +associated with that macro. The most popular is the imaginary macro .Ar \&Ds , which resolves to -.Ar 6n . +.Sy 6n . .It -As a scaling unit following the syntax described in +A width using the syntax described in .Sx Scaling Widths . .It -As the calculated string length of the opaque string. +An arbitrary string, which indents by the length of this string. .El .Pp -If not provided an argument, it will be ignored. +When the argument is missing, +.Fl offset +is ignored. .It Fl compact -Do not assert a vertical space before the block. +Do not assert vertical space before the display. .El .Pp Examples: .Bd -literal -offset indent -\&.Bd \-unfilled \-offset two-indent \-compact +\&.Bd \-literal \-offset indent \-compact Hello world. \&.Ed .Ed @@ -1196,21 +1196,22 @@ is encountered. See also .Sx \&Li , .Sx \&Ef , +.Sx \&Em , and .Sx \&Sy . .Ss \&Bk -Begins a collection of macros or text not breaking the line. -Its syntax is as follows: +Keep the output generated from each macro input line together +on one single output line. +Line breaks in free-form text lines are unaffected. +The syntax is as follows: .Pp .D1 Pf \. Sx \&Bk Fl words .Pp -Subsequent arguments are ignored. The .Fl words -argument is required. +argument is required; additional arguments are ignored. .Pp -Each line within a keep block is kept intact, so the following example -will not break within each +The following example will not break within each .Sx \&Op macro line: .Bd -literal -offset indent @@ -1223,124 +1224,128 @@ macro line: Be careful in using over-long lines within a keep block! Doing so will clobber the right margin. .Ss \&Bl -Begins a list composed of one or more list entries. -Its syntax is as follows: +Begin a list. +Lists consist of items started by the +.Sx \&It +macro, containing a head or a body or both. +The list syntax is as follows: .Bd -ragged -offset indent .Pf \. Sx \&Bl -.Fl type +.Fl Ns Ar type .Op Fl width Ar val .Op Fl offset Ar val .Op Fl compact .Op HEAD ... .Ed .Pp -A list is associated with a type, which is a required argument. -Other arguments are -.Fl width , -defined per-type as accepting a literal or -.Sx Scaling Widths -value; -.Fl offset , -also accepting a literal or +The list +.Ar type +is mandatory and must be specified first. +The +.Fl width +and +.Fl offset +arguments accept .Sx Scaling Widths -value setting the list's global offset; and -.Fl compact , -suppressing the default vertical space printed before each list entry. -A list entry is specified by the -.Sx \&It -macro, which consists of a head and optional body (depending on the list -type). +or use the length of the given string. +The +.Fl offset +is a global indentation for the whole list, affecting both item heads +and bodies. +For those list types supporting it, the +.Fl width +argument requests an additional indentation of item bodies, +to be added to the +.Fl offset . +Unless the +.Fl compact +argument is specified, list entries are separated by vertical space. +.Pp A list must specify one of the following list types: .Bl -tag -width 12n -offset indent .It Fl bullet -A list offset by a bullet. -The head of list entries must be empty. -List entry bodies are positioned after the bullet. -The +No item heads can be specified, but a bullet will be printed at the head +of each item. +Item bodies start on the same output line as the bullet +and are indented according to the .Fl width -argument varies the width of list bodies' left-margins. +argument. .It Fl column A columnated list. The .Fl width -argument has no effect. -The number of columns is specified as parameters to the -.Sx \&Bl -macro. -These dictate the width of columns either as +argument has no effect; instead, each argument specifies the width +of one column, using either the .Sx Scaling Widths -or literal text. -If the initial macro of a +syntax or the string length of the argument. +If the first line of the body of a .Fl column list is not an -.Sx \&It , -an .Sx \&It -context spanning each line is implied until an +macro line, .Sx \&It -line macro is encountered, at which point list bodies are interpreted as +contexts spanning one input line each are implied until an +.Sx \&It +macro line is encountered, at which point items start being interpreted as described in the .Sx \&It documentation. .It Fl dash -A list offset by a dash (hyphen). -The head of list entries must be empty. -List entry bodies are positioned past the dash. -The -.Fl width -argument varies the width of list bodies' left-margins. +Like +.Fl bullet , +except that dashes are used in place of bullets. .It Fl diag Like .Fl inset , -but with additional formatting to the head. -The -.Fl width -argument varies the width of list bodies' left-margins. +except that item heads are not parsed for macro invocations. +.\" but with additional formatting to the head. .It Fl enum -An enumerated list offset by the enumeration from 1. -The head of list entries must be empty. -List entry bodies are positioned after the enumeration. -The -.Fl width -argument varies the width of list bodies' left-margins. +A numbered list. +Formatted like +.Fl bullet , +except that cardinal numbers are used in place of bullets, +starting at 1. .It Fl hang Like .Fl tag , -but instead of list bodies positioned after the head, they trail the -head text. -The -.Fl width -argument varies the width of list bodies' left-margins. +except that the first lines of item bodies are not indented, but follow +the item heads like in +.Fl inset +lists. .It Fl hyphen Synonym for .Fl dash . .It Fl inset -List bodies follow the list head. -The +Item bodies follow items heads on the same line, using normal inter-word +spacing. +Bodies are not indented, and the .Fl width argument is ignored. .It Fl item -This produces blocks of text. -The head of list entries must be empty. -The +No item heads can be specified, and none are printed. +Bodies are not indented, and the .Fl width argument is ignored. .It Fl ohang -List bodies are positioned on the line following the head. +Item bodies start on the line following item heads and are not indented. The .Fl width argument is ignored. .It Fl tag -A list offset by list entry heads. -List entry bodies are positioned after the head as specified by the +Item bodies are indented according to the .Fl width argument. +When an item head fits inside the indentation, the item body follows +this head on the same output line. +Otherwise, the body starts on the output line following the head. .El .Pp See also +.Sx \&El +and .Sx \&It . .Ss \&Bo -Begins a block enclosed by square brackets. +Begin a block enclosed by square brackets. Does not have any head arguments. .Pp Examples: @@ -1368,12 +1373,12 @@ and See also .Sx \&Bo . .Ss \&Brc -Closes a +Close a .Sx \&Bro block. Does not have any tail arguments. .Ss \&Bro -Begins a block enclosed by curly braces. +Begin a block enclosed by curly braces. Does not have any head arguments. .Pp Examples: @@ -1430,7 +1435,7 @@ See also and .Sx \&Ux . .Ss \&Cd -Configuration declaration. +Kernel configuration declaration. This denotes strings accepted by .Xr config 8 . .Pp @@ -1467,13 +1472,15 @@ See also and .Sx \&Dl . .Ss \&Db -Start a debugging context. -This macro is parsed, but generally ignored. +Switch debugging mode. Its syntax is as follows: .Pp .D1 Pf \. Sx \&Db Cm on | off +.Pp +This macro is ignored by +.Xr mandoc 1 . .Ss \&Dc -Closes a +Close a .Sx \&Do block. Does not have any tail arguments. @@ -1484,17 +1491,17 @@ This is the mandatory first macro of any manual. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Dd Cm date +.D1 Pf \. Sx \&Dd Op Ar date .Pp The -.Cm date -field may be either +.Ar date +may be either .Ar $\&Mdocdate$ , which signifies the current manual revision date dictated by .Xr cvs 1 , or instead a valid canonical date as specified by .Sx Dates . -If a date does not conform, the current date is used instead. +If a date does not conform or is empty, the current date is used. .Pp Examples: .D1 \&.Dd $\&Mdocdate$ @@ -1519,7 +1526,7 @@ See also and .Sx \&D1 . .Ss \&Do -Begins a block enclosed by double quotes. +Begin a block enclosed by double quotes. Does not have any head arguments. .Pp Examples: @@ -1557,22 +1564,22 @@ Its syntax is as follows: .Bd -ragged -offset indent .Pf \. Sx \&Dt .Oo -.Cm title +.Ar title .Oo -.Cm section -.Op Cm volume | arch +.Ar section +.Op Ar volume | arch .Oc .Oc .Ed .Pp Its arguments are as follows: .Bl -tag -width Ds -offset Ds -.It Cm title +.It Ar title The document's title (name), defaulting to .Dq UNKNOWN if unspecified. It should be capitalised. -.It Cm section +.It Ar section The manual section. This may be one of .Ar 1 @@ -1611,7 +1618,7 @@ or It should correspond to the manual's filename suffix and defaults to .Dq 1 if unspecified. -.It Cm volume +.It Ar volume This overrides the volume inferred from .Ar section . This field is optional, and if specified, must be one of @@ -1640,10 +1647,10 @@ This field is optional, and if specified, must be one of or .Ar CON .Pq contributed manuals . -.It Cm arch +.It Ar arch This specifies a specific relevant architecture. If -.Cm volume +.Ar volume is not provided, it may be used in its place, else it may be used subsequent that. It, too, is optional. @@ -1718,10 +1725,10 @@ Close a scope started by .Sx \&Eo . Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Ec Op Cm TERM +.D1 Pf \. Sx \&Ec Op Ar TERM .Pp The -.Cm TERM +.Ar TERM argument is used as the enclosure tail, for example, specifying \e(rq will emulate .Sx \&Dc . @@ -1729,13 +1736,13 @@ will emulate End a display context started by .Sx \&Bd . .Ss \&Ef -Ends a font mode context started by +End a font mode context started by .Sx \&Bf . .Ss \&Ek -Ends a keep context started by +End a keep context started by .Sx \&Bk . .Ss \&El -Ends a list context started by +End a list context started by .Sx \&Bl . .Pp See also @@ -1757,15 +1764,16 @@ See also and .Sx \&Li . .Ss \&En -This macro is obsolete and not implemented. +This macro is obsolete and not implemented in +.Xr mandoc 1 . .Ss \&Eo An arbitrary enclosure. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Eo Op Cm TERM +.D1 Pf \. Sx \&Eo Op Ar TERM .Pp The -.Cm TERM +.Ar TERM argument is used as the enclosure head, for example, specifying \e(lq will emulate .Sx \&Do . @@ -1788,16 +1796,16 @@ Examples: .D1 \&.Ev DISPLAY .D1 \&.Ev PATH .Ss \&Ex -Inserts text regarding a utility's exit value. -This macro must consist of the -.Fl std -argument followed by an optional -.Ar utility . -If +Insert a standard sentence regarding exit values. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Ex Fl std Op Ar utility +.Pp +When .Ar utility -is not provided, the document's name as stipulated in +is not specified, the document's name set by .Sx \&Nm -is provided. +is used. .Pp See also .Sx \&Rv . @@ -1833,7 +1841,7 @@ Examples: See also .Sx \&Fo . .Ss \&Fc -Ends a function context started by +End a function context started by .Sx \&Fo . .Ss \&Fd Historically used to document include files. @@ -1984,7 +1992,7 @@ In the section (only if invoked as the line macro), the first argument is preceded by .Dq #include , -the arguments is enclosed in angled braces. +the arguments is enclosed in angle brackets. .Pp Examples: .D1 \&.In sys/types @@ -2238,7 +2246,7 @@ See also and .Sx \&Ux . .Ss \&Oc -Closes multi-line +Close multi-line .Sx \&Oo context. .Ss \&Oo @@ -2372,12 +2380,12 @@ See also and .Sx \&Qo . .Ss \&Re -Closes a +Close an .Sx \&Rs block. Does not have any tail arguments. .Ss \&Rs -Begins a bibliographic +Begin a bibliographic .Pq Dq reference block. Does not have any head arguments. @@ -2731,6 +2739,12 @@ Heirloom troff, the other significant troff implementation accepting .Pp .Bl -dash -compact .It +An empty +.Sq \&Dd +macro in groff prints +.Dq Epoch . +In mandoc, it resolves to the current date. +.It Old groff fails to assert a newline before .Sx \&Bd Fl ragged compact . .It |