=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.159 retrieving revision 1.194 diff -u -p -r1.159 -r1.194 --- mandoc/mdoc.7 2010/09/26 19:46:48 1.159 +++ mandoc/mdoc.7 2011/08/01 07:45:11 1.194 @@ -1,6 +1,6 @@ -.\" $Id: mdoc.7,v 1.159 2010/09/26 19:46:48 schwarze Exp $ +.\" $Id: mdoc.7,v 1.194 2011/08/01 07:45:11 schwarze Exp $ .\" -.\" Copyright (c) 2009, 2010 Kristaps Dzonsons +.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" Copyright (c) 2010 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -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: September 26 2010 $ +.Dd $Mdocdate: August 1 2011 $ .Dt MDOC 7 .Os .Sh NAME @@ -40,37 +40,39 @@ An .Nm document follows simple rules: lines beginning with the control character -.Sq \. +.Sq \&. are parsed for macros. -Other lines are interpreted within the scope of -prior macros: +Text lines, those not beginning with the control character, are +interpreted within the scope of prior macros: .Bd -literal -offset indent \&.Sh Macro lines change control state. -Other lines are interpreted within the current state. +Text lines are interpreted within the current state. .Ed .Sh LANGUAGE SYNTAX .Nm documents may contain only graphable 7-bit ASCII characters, the space character, and, in certain circumstances, the tab character. -All manuals must have -.Ux -line terminators. +.Pp +If the first character of a text line is a space, that line is printed +with a leading newline. .Ss Comments Text following a .Sq \e\*q , -whether in a macro or free-form text line, is ignored to the end of +whether in a macro or text line, is ignored to the end of line. A macro line with only a control character and comment escape, .Sq \&.\e\*q , is also ignored. Macro lines with only a control character and optional whitespace are stripped from input. -.Ss Reserved Characters -Within a macro line, the following characters are reserved: +.Ss Reserved Terms +Within a macro line, the following terms are reserved: .Pp .Bl -tag -width Ds -offset indent -compact .It \&. .Pq period +.It \e. +.Pq escaped period .It \&, .Pq comma .It \&: @@ -91,16 +93,16 @@ Within a macro line, the following characters are rese .Pq exclamation .It \&| .Pq vertical bar +.It \e*(Ba +.Pq reserved-word vertical bar .El .Pp -Use of reserved characters is described in -.Sx MACRO SYNTAX . -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 can be used. +For general use in macro lines, these can be escaped with a non-breaking +space +.Pq Sq \e& . +In text lines, these may be used as normal punctuation. .Ss Special Characters -Special characters may occur in both macro and free-form lines. +Special characters may occur in both macro and text lines. Sequences begin with the escape character .Sq \e followed by either an open-parenthesis @@ -125,22 +127,19 @@ Terms may be text-decorated using the escape followed by an indicator: B (bold), I (italic), R (Roman), or P (revert to previous mode): .Pp -.D1 \efBbold\efR \efIitalic\efP +.Dl \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 -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 +If a macro opens a font scope after calling +.Sq \ef , +such as with +.Sx \&Bf , +the .Sq \ef -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. +mode will be restored upon exiting the +.Sx \&Bf +scope. .Pp Note this form is .Em not @@ -174,20 +173,43 @@ and .Pq vertical bar . .Ss Whitespace Whitespace consists of the space character. -In free-form lines, whitespace is preserved within a line; unescaped +In text lines, whitespace is preserved within a line; unescaped trailing spaces are stripped from input (unless in a literal context). -Blank free-form lines, which may include whitespace, are only permitted +Blank text lines, which may include whitespace, are only permitted within literal contexts. .Pp +In general, trailing whitespace on input lines is discouraged +for reasons of clarity and portability. +In the rare case that a blank character is needed at the end of an +input line, it may be forced by +.Sq \e\ \e& . +.Pp 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 double-quotes to group -space-delimited terms or to retain blocks of whitespace. +Macro arguments may be quoted with double-quotes; in this case, +whitespace within the quotes is retained as part of the argument. +For example, +.Pp +.D1 Pf \. \&Fn strlen "\(dqconst char *s\(dq" +.Pp +renders as +.Sq Fn strlen "const char *s" , +while +.Pp +.D1 Pf \. \&Fn strlen "const char *s" +.Pp +would produce +.Sq Fn strlen const char *s . +.Pp A quoted argument begins with a double-quote preceded by whitespace. The next double-quote not pairwise adjacent to another double-quote terminates the literal, regardless of surrounding whitespace. .Pp +In unquoted arguments, space characters can alternatively be included +by preceding them with a backslash +.Pq Sq \e\~ , +but quoting is usually better for clarity. +.Pp Note that any quoted text, even if it would cause a macro invocation when unquoted, is considered literal text. Thus, the following produces @@ -196,35 +218,7 @@ Thus, the following produces \&.Op "Fl a" .Ed .Pp -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: -.Pp -.D1 Cm Month Day , Year -.Pp -The -.Cm Day -value is an optionally zero-padded numeral. -The -.Cm Month -value is the full month name. -The -.Cm Year -value is the full four-digit year. -.Pp -Reduced form dates are broken-down canonical form dates: -.Pp -.D1 Cm Month , Year -.D1 Cm Year -.Pp -Some examples of valid dates follow: -.Pp -.D1 "May, 2009" Pq reduced form -.D1 "2009" Pq reduced form -.D1 "May 20, 2009" Pq canonical form +In text lines, quotes are regarded as opaque text. .Ss Scaling Widths Many macros support scaled widths for their arguments, such as stipulating a two-inch list indentation with the following: @@ -283,18 +277,20 @@ a line. By doing so, front-ends will be able to apply the proper amount of spacing after the end of sentence (unescaped) period, exclamation mark, or question mark followed by zero or more non-sentence closing -delimiters ( -.Ns Sq \&) , +delimiters +.Po +.Sq \&) , .Sq \&] , .Sq \&' , -.Sq \&" ) . +.Sq \&" +.Pc . .Pp The proper spacing is also intelligently preserved if a sentence ends at the boundary of a macro line. For example: .Pp -.D1 \&Xr mandoc 1 \. -.D1 \&Fl T \&Ns \&Cm ascii \. +.Dl \&.Xr mandoc 1 \&. +.Dl \&.Fl T \&Ns \&Cm ascii \&. .Sh MANUAL STRUCTURE A well-formed .Nm @@ -323,19 +319,20 @@ sections, although this varies between manual sections .Pp The following is a well-formed skeleton .Nm -file: +file for a utility +.Qq progname : .Bd -literal -offset indent \&.Dd $\&Mdocdate$ -\&.Dt mdoc 7 +\&.Dt PROGNAME section \&.Os \&.Sh NAME -\&.Nm foo -\&.Nd a description goes here +\&.Nm progname +\&.Nd one line about what it does \&.\e\*q .Sh LIBRARY \&.\e\*q For sections 2, 3, & 9 only. \&.\e\*q Not used in OpenBSD. \&.Sh SYNOPSIS -\&.Nm foo +\&.Nm progname \&.Op Fl options \&.Ar \&.Sh DESCRIPTION @@ -382,6 +379,10 @@ The syntax for this as follows: \&.Nd a one line description .Ed .Pp +Multiple +.Sq \&Nm +names should be separated by commas. +.Pp The .Sx \&Nm macro(s) must precede the @@ -409,16 +410,18 @@ configuration. For the first, utilities (sections 1, 6, and 8), this is generally structured as follows: .Bd -literal -offset indent -\&.Nm foo +\&.Nm bar \&.Op Fl v \&.Op Fl o Ar file \&.Op Ar -\&.Nm bar +\&.Nm foo \&.Op Fl v \&.Op Fl o Ar file \&.Op Ar .Ed .Pp +Commands should be ordered alphabetically. +.Pp For the second, function calls (sections 2, 3, 9): .Bd -literal -offset indent \&.In header.h @@ -429,6 +432,14 @@ For the second, function calls (sections 2, 3, 9): \&.Fn bar "const char *src" .Ed .Pp +Ordering of +.Sx \&In , +.Sx \&Vt , +.Sx \&Fn , +and +.Sx \&Fo +macros should follow C header-file conventions. +.Pp And for the third, configurations (section 4): .Bd -literal -offset indent \&.Cd \*qit* at isa? port 0x2e\*q @@ -477,9 +488,15 @@ or .Sx \&Ss macro or the end of an enclosing block, whichever comes first. .It Em DESCRIPTION -This expands upon the brief, one line description in -.Em NAME . -It usually contains a breakdown of the options (if documenting a +This begins with an expansion of the brief, one line description in +.Em NAME : +.Bd -literal -offset indent +The +\&.Nm +utility does this, that, and the other. +.Ed +.Pp +It usually follows with a breakdown of the options (if documenting a command), such as: .Bd -literal -offset indent The arguments are as follows: @@ -604,20 +621,32 @@ closes it out. .Pp 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 +column indicates that the macro may also be called by passing its name +as an argument to another macro. +For example, +.Sq \&.Op \&Fl O \&Ar file +produces +.Sq Op Fl O Ar file . +To prevent a macro call and render the macro name literally, +escape it by prepending a non-breaking space, +.Sq \e& . +For example, +.Sq \&Op \e&Fl O +produces +.Sq Op \&Fl O . +If a macro is not callable but its name appears as an argument +to another macro, it is interpreted as opaque text. +For example, .Sq \&.Fl \&Sh produces .Sq Fl \&Sh . .Pp The .Em Parsed -column indicates whether the macro may be followed by further -(ostensibly callable) macros. -If a macro is not parsed, subsequent macro invocations on the line -will be interpreted as opaque text. +column indicates whether the macro may call other macros by receiving +their names as arguments. +If a macro is not parsed but the name of another macro appears +as an argument, it is interpreted as opaque text. .Pp The .Em Scope @@ -626,7 +655,10 @@ column, if applicable, describes closure rules. Multi-line scope closed by an explicit closing macro. All macros contains bodies; only .Sx \&Bf -contains a head. +and +.Pq optionally +.Sx \&Bl +contain a head. .Bd -literal -offset indent \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \(lBbody...\(rB @@ -731,7 +763,7 @@ and/or tail .El .Ss Block partial-implicit Like block full-implicit, but with single-line scope closed by -.Sx Reserved Characters +.Sx Reserved Terms or end of line. .Bd -literal -offset indent \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB @@ -762,9 +794,24 @@ in a .Em SYNOPSIS section line, else it is .Sx In-line . +.Ss Special block macro +The +.Sx \&Ta +macro can only be used below +.Sx \&It +in +.Sx \&Bl Fl column +lists. +It delimits blocks representing table cells; +these blocks have bodies, but no heads. +.Pp +.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 \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It +.El .Ss In-line Closed by -.Sx Reserved Characters , +.Sx Reserved Terms , 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 @@ -794,8 +841,8 @@ then the macro accepts an arbitrary number of argument .It Sx \&%T Ta \&No Ta \&No Ta >0 .It Sx \&%U Ta \&No Ta \&No Ta >0 .It Sx \&%V Ta \&No Ta \&No Ta >0 -.It Sx \&Ad Ta Yes Ta Yes Ta n -.It Sx \&An Ta Yes Ta Yes Ta n +.It Sx \&Ad Ta Yes Ta Yes Ta >0 +.It Sx \&An Ta Yes Ta Yes Ta >0 .It Sx \&Ap Ta Yes Ta Yes Ta 0 .It Sx \&Ar Ta Yes Ta Yes Ta n .It Sx \&At Ta Yes Ta Yes Ta 1 @@ -803,31 +850,31 @@ then the macro accepts an arbitrary number of argument .It Sx \&Bt Ta \&No Ta \&No Ta 0 .It Sx \&Bx Ta Yes Ta Yes Ta n .It Sx \&Cd Ta Yes Ta Yes Ta >0 -.It Sx \&Cm Ta Yes Ta Yes Ta n +.It Sx \&Cm Ta Yes Ta Yes Ta >0 .It Sx \&Db Ta \&No Ta \&No Ta 1 .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 \&Dv Ta Yes Ta Yes Ta >0 .It Sx \&Dx Ta Yes Ta Yes Ta n .It Sx \&Em Ta Yes Ta Yes Ta >0 .It Sx \&En Ta \&No Ta \&No Ta 0 .It Sx \&Er Ta Yes Ta Yes Ta >0 .It Sx \&Es Ta \&No Ta \&No Ta 0 -.It Sx \&Ev Ta Yes Ta Yes Ta n +.It Sx \&Ev Ta Yes Ta Yes Ta >0 .It Sx \&Ex Ta \&No Ta \&No Ta n -.It Sx \&Fa Ta Yes Ta Yes Ta n +.It Sx \&Fa Ta Yes Ta Yes Ta >0 .It Sx \&Fd Ta \&No Ta \&No Ta >0 .It Sx \&Fl Ta Yes Ta Yes Ta n .It Sx \&Fn Ta Yes Ta Yes Ta >0 .It Sx \&Fr Ta \&No Ta \&No Ta n -.It Sx \&Ft Ta Yes Ta Yes Ta n +.It Sx \&Ft Ta Yes Ta Yes Ta >0 .It Sx \&Fx Ta Yes Ta Yes Ta n .It Sx \&Hf Ta \&No Ta \&No Ta n .It Sx \&Ic Ta Yes Ta Yes Ta >0 -.It Sx \&In Ta \&No Ta \&No Ta n +.It Sx \&In Ta \&No Ta \&No Ta 1 .It Sx \&Lb Ta \&No Ta \&No Ta 1 -.It Sx \&Li Ta Yes Ta Yes Ta n -.It Sx \&Lk Ta Yes Ta Yes Ta n +.It Sx \&Li Ta Yes Ta Yes Ta >0 +.It Sx \&Lk Ta Yes Ta Yes Ta >0 .It Sx \&Lp Ta \&No Ta \&No Ta 0 .It Sx \&Ms Ta Yes Ta Yes Ta >0 .It Sx \&Mt Ta Yes Ta Yes Ta >0 @@ -883,8 +930,10 @@ block. Publication date of an .Sx \&Rs block. -This should follow the reduced or canonical form syntax described in -.Sx Dates . +Recommended formats of arguments are +.Ar month day , year +or just +.Ar year . .Ss \&%I Publisher or issuer name of an .Sx \&Rs @@ -938,8 +987,8 @@ Memory address. Do not use this for postal addresses. .Pp Examples: -.D1 \&.Ad [0,$] -.D1 \&.Ad 0x00000000 +.Dl \&.Ad [0,$] +.Dl \&.Ad 0x00000000 .Ss \&An Author name. Requires either the name of an author or one of the following arguments: @@ -969,14 +1018,14 @@ for the first author listing and for all other author listings. .Pp Examples: -.D1 \&.An -nosplit -.D1 \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv +.Dl \&.An -nosplit +.Dl \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv .Ss \&Ao Begin a block enclosed by angle brackets. Does not have any head arguments. .Pp Examples: -.D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac +.Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac .Pp See also .Sx \&Aq . @@ -986,12 +1035,12 @@ This is generally used as a grammatical device when re form of a function. .Pp Examples: -.D1 \&.Fn execve \&Ap d +.Dl \&.Fn execve \&Ap d .Ss \&Aq Encloses its arguments in angle brackets. .Pp Examples: -.D1 \&.Fl -key= \&Ns \&Aq \&Ar val +.Dl \&.Fl -key= \&Ns \&Aq \&Ar val .Pp .Em Remarks : this macro is often abused for rendering URIs, which should instead use @@ -1012,9 +1061,9 @@ If an argument is not provided, the string is used as a default. .Pp Examples: -.D1 \&.Fl o \&Ns \&Ar file1 -.D1 \&.Ar -.D1 \&.Ar arg1 , arg2 . +.Dl \&.Fl o \&Ns \&Ar file1 +.Dl \&.Ar +.Dl \&.Ar arg1 , arg2 . .Ss \&At Formats an AT&T version. Accepts one optional argument: @@ -1023,6 +1072,8 @@ Accepts one optional argument: .It Cm v[1-7] | 32v A version of .At . +.It Cm III +.At III . .It Cm V[.[1-4]]? A version of .At V . @@ -1031,8 +1082,9 @@ A version of Note that these arguments do not begin with a hyphen. .Pp Examples: -.D1 \&.At -.D1 \&.At V.1 +.Dl \&.At +.Dl \&.At III +.Dl \&.At V.1 .Pp See also .Sx \&Bsx , @@ -1060,7 +1112,7 @@ Its syntax is as follows: .Pp 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. +They may contain both macro lines and text lines. By default, a display block is preceded by a vertical space. .Pp The @@ -1175,9 +1227,10 @@ See also and .Sx \&Sy . .Ss \&Bk -Keep the output generated from each macro input line together -on one single output line. -Line breaks in free-form text lines are unaffected. +For each macro, keep its output together on the same output line, +until the end of the macro or the end of the input line is reached, +whichever comes first. +Line breaks in text lines are unaffected. The syntax is as follows: .Pp .D1 Pf \. Sx \&Bk Fl words @@ -1200,7 +1253,7 @@ Be careful in using over-long lines within a keep bloc Doing so will clobber the right margin. .Ss \&Bl Begin a list. -Lists consist of items started by the +Lists consist of items specified using the .Sx \&It macro, containing a head or a body or both. The list syntax is as follows: @@ -1335,7 +1388,7 @@ See also Encloses its arguments in square brackets. .Pp Examples: -.D1 \&.Bq 1 , \&Dv BUFSIZ +.Dl \&.Bq 1 , \&Dv BUFSIZ .Pp .Em Remarks : this macro is sometimes abused to emulate optional arguments for @@ -1368,7 +1421,7 @@ See also Encloses its arguments in curly braces. .Pp Examples: -.D1 \&.Brq 1 , ... , \&Va n +.Dl \&.Brq 1 , ... , \&Va n .Pp See also .Sx \&Bro . @@ -1377,8 +1430,8 @@ Format the BSD/OS version provided as an argument, or no argument is provided. .Pp Examples: -.D1 \&.Bsx 1.0 -.D1 \&.Bsx +.Dl \&.Bsx 1.0 +.Dl \&.Bsx .Pp See also .Sx \&At , @@ -1397,8 +1450,8 @@ Format the BSD version provided as an argument, or a d argument is provided. .Pp Examples: -.D1 \&.Bx 4.4 -.D1 \&.Bx +.Dl \&.Bx 4.4 +.Dl \&.Bx .Pp See also .Sx \&At , @@ -1415,7 +1468,7 @@ This denotes strings accepted by .Xr config 8 . .Pp Examples: -.D1 \&.Cd device le0 at scode? +.Dl \&.Cd device le0 at scode? .Pp .Em Remarks : this macro is commonly abused by using quoted literals to retain @@ -1428,8 +1481,8 @@ Command modifiers. Useful when specifying configuration options or keys. .Pp Examples: -.D1 \&.Cm ControlPath -.D1 \&.Cm ControlMaster +.Dl \&.Cm ControlPath +.Dl \&.Cm ControlMaster .Pp See also .Sx \&Fl . @@ -1440,7 +1493,7 @@ statements. It is followed by a newline. .Pp Examples: -.D1 \&.D1 \&Fl abcdefgh +.Dl \&.D1 \&Fl abcdefgh .Pp See also .Sx \&Bd @@ -1466,22 +1519,41 @@ This is the mandatory first macro of any manual. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Dd Op Ar date +.D1 Pf \. Sx \&Dd Ar month day , year .Pp The -.Ar date -may be either -.Ar $\&Mdocdate$ , -which signifies the current manual revision date dictated by +.Ar month +is the full English month name, the +.Ar day +is an optionally zero-padded numeral, and the +.Ar year +is the full four-digit year. +.Pp +Other arguments are not portable; the +.Xr mandoc 1 +utility handles them as follows: +.Bl -dash -offset 3n -compact +.It +To have the date automatically filled in by the +.Ox +version of .Xr cvs 1 , -or instead a valid canonical date as specified by -.Sx Dates . -If a date does not conform or is empty, the current date is used. +the special string +.Dq $\&Mdocdate$ +can be given as an argument. +.It +A few alternative date formats are accepted as well +and converted to the standard form. +.It +If a date string cannot be parsed, it is used verbatim. +.It +If no date string is given, the current date is used. +.El .Pp Examples: -.D1 \&.Dd $\&Mdocdate$ -.D1 \&.Dd $\&Mdocdate: July 21 2007$ -.D1 \&.Dd July 21, 2007 +.Dl \&.Dd $\&Mdocdate$ +.Dl \&.Dd $\&Mdocdate: July 21 2007$ +.Dl \&.Dd July 21, 2007 .Pp See also .Sx \&Dt @@ -1494,7 +1566,7 @@ invocations. It is followed by a newline. .Pp Examples: -.D1 \&.Dl % mandoc mdoc.7 \e(ba less +.Dl \&.Dl % mandoc mdoc.7 \e(ba less .Pp See also .Sx \&Bd @@ -1646,6 +1718,7 @@ It must be one of .Ar luna88k , .Ar mac68k , .Ar macppc , +.Ar mips64 , .Ar mvme68k , .Ar mvme88k , .Ar mvmeppc , @@ -1661,30 +1734,37 @@ or .El .Pp Examples: -.D1 \&.Dt FOO 1 -.D1 \&.Dt FOO 4 KM -.D1 \&.Dt FOO 9 i386 +.Dl \&.Dt FOO 1 +.Dl \&.Dt FOO 4 KM +.Dl \&.Dt FOO 9 i386 .Pp See also .Sx \&Dd and .Sx \&Os . .Ss \&Dv -Defined variables such as preprocessor constants. +Defined variables such as preprocessor constants, constant symbols, +enumeration values, and so on. .Pp Examples: -.D1 \&.Dv BUFSIZ -.D1 \&.Dv STDOUT_FILENO +.Dl \&.Dv NULL +.Dl \&.Dv BUFSIZ +.Dl \&.Dv STDOUT_FILENO .Pp See also -.Sx \&Er . +.Sx \&Er +and +.Sx \&Ev +for special-purpose constants and +.Sx \&Va +for variable symbols. .Ss \&Dx Format the DragonFly BSD version provided as an argument, or a default value if no argument is provided. .Pp Examples: -.D1 \&.Dx 2.4.1 -.D1 \&.Dx +.Dl \&.Dx 2.4.1 +.Dl \&.Dx .Pp See also .Sx \&At , @@ -1730,8 +1810,8 @@ Note that this is a presentation term and should not b stylistically decorating technical terms. .Pp Examples: -.D1 \&.Em Warnings! -.D1 \&.Em Remarks : +.Dl \&.Em Warnings! +.Dl \&.Em Remarks : .Pp See also .Sx \&Bf , @@ -1753,14 +1833,17 @@ argument is used as the enclosure head, for example, s will emulate .Sx \&Do . .Ss \&Er -Display error constants. +Error constants for definitions of the +.Va errno +libc global variable. .Pp Examples: -.D1 \&.Er EPERM -.D1 \&.Er ENOENT +.Dl \&.Er EPERM +.Dl \&.Er ENOENT .Pp See also -.Sx \&Dv . +.Sx \&Dv +for general constants. .Ss \&Es This macro is obsolete and not implemented. .Ss \&Ev @@ -1768,19 +1851,27 @@ Environmental variables such as those specified in .Xr environ 7 . .Pp Examples: -.D1 \&.Ev DISPLAY -.D1 \&.Ev PATH +.Dl \&.Ev DISPLAY +.Dl \&.Ev PATH +.Pp +See also +.Sx \&Dv +for general constants. .Ss \&Ex -Insert a standard sentence regarding exit values. +Insert a standard sentence regarding command exit values of 0 on success +and >0 on failure. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Ex Fl std Op Ar utility +.D1 Pf \. Sx \&Ex Fl std Op Ar utility ... .Pp -When +If .Ar utility is not specified, the document's name set by .Sx \&Nm is used. +Multiple +.Ar utility +arguments are treated as separate utilities. .Pp See also .Sx \&Rv . @@ -1809,9 +1900,9 @@ Furthermore, if the following macro is another the last argument will also have a trailing comma. .Pp Examples: -.D1 \&.Fa \(dqconst char *p\(dq -.D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq -.D1 \&.Fa foo +.Dl \&.Fa \(dqconst char *p\(dq +.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq +.Dl \&.Fa foo .Pp See also .Sx \&Fo . @@ -1839,10 +1930,10 @@ If the argument is a macro, a hyphen is prefixed to th output. .Pp Examples: -.D1 \&.Fl a b c -.D1 \&.Fl \&Pf a b -.D1 \&.Fl -.D1 \&.Op \&Fl o \&Ns \&Ar file +.Dl \&.Fl a b c +.Dl \&.Fl \&Pf a b +.Dl \&.Fl +.Dl \&.Op \&Fl o \&Ns \&Ar file .Pp See also .Sx \&Cm . @@ -1851,9 +1942,9 @@ A function name. Its syntax is as follows: .Bd -ragged -offset indent .Pf \. Ns Sx \&Fn -.Op Cm functype -.Cm funcname -.Op Oo Cm argtype Oc Cm argname +.Op Ar functype +.Ar funcname +.Op Oo Ar argtype Oc Ar argname .Ed .Pp Function arguments are surrounded in parenthesis and @@ -1861,14 +1952,17 @@ are delimited by commas. If no arguments are specified, blank parenthesis are output. .Pp Examples: -.D1 \&.Fn "int funcname" "int arg0" "int arg1" -.D1 \&.Fn funcname "int arg0" -.D1 \&.Fn funcname arg0 +.Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q +.Dl \&.Fn funcname \*qint arg0\*q +.Dl \&.Fn funcname arg0 .Bd -literal -offset indent -compact \&.Ft functype \&.Fn funcname .Ed .Pp +When referring to a function documented in another manual page, use +.Sx \&Xr +instead. See also .Sx MANUAL STRUCTURE and @@ -1879,17 +1973,17 @@ This is a multi-line version of .Sx \&Fn . Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Fo Cm funcname +.D1 Pf \. Sx \&Fo Ar funcname .Pp Invocations usually occur in the following context: .Bd -ragged -offset indent -.Pf \. Sx \&Ft Cm functype +.Pf \. Sx \&Ft Ar functype .br -.Pf \. Sx \&Fo Cm funcname +.Pf \. Sx \&Fo Ar funcname .br -.Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname +.Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname .br -\.\.\. +\&.\.\. .br .Pf \. Sx \&Fc .Ed @@ -1904,14 +1998,16 @@ See also .Sx \&Fc , and .Sx \&Ft . +.Ss \&Fr +This macro is obsolete and not implemented. .Ss \&Ft A function type. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Ft Cm functype +.D1 Pf \. Sx \&Ft Ar functype .Pp Examples: -.D1 \&.Ft int +.Dl \&.Ft int .Bd -literal -offset indent -compact \&.Ft functype \&.Fn funcname @@ -1929,8 +2025,8 @@ version provided as an argument, or a default value if no argument is provided. .Pp Examples: -.D1 \&.Fx 7.1 -.D1 \&.Fx +.Dl \&.Fx 7.1 +.Dl \&.Fx .Pp See also .Sx \&At , @@ -1950,8 +2046,8 @@ This is similar to but used for instructions rather than values. .Pp Examples: -.D1 \&.Ic hash -.D1 \&.Ic alias +.Dl \&.Ic hash +.Dl \&.Ic alias .Pp Note that using .Sx \&Bd Fl literal @@ -1972,7 +2068,7 @@ preceded by the arguments is enclosed in angle brackets. .Pp Examples: -.D1 \&.In sys/types +.Dl \&.In sys/types .Pp See also .Sx MANUAL STRUCTURE . @@ -1989,7 +2085,7 @@ and .Fl diag have the following syntax: .Pp -.D1 Pf \. Sx \&It Cm args +.D1 Pf \. Sx \&It Ar args .Pp Lists of type .Fl bullet , @@ -2026,33 +2122,29 @@ The list is the most complicated. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&It Op Cm args +.D1 Pf \. Sx \&It Ar cell Op Ar cell ... +.D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ... .Pp -The -.Cm args -are phrases, a mix of macros and text corresponding to a line column, -delimited by tabs or the special -.Sq \&Ta -pseudo-macro. -Lines subsequent the +The arguments consist of one or more lines of text and macros +representing a complete table line. +Cells within the line are delimited by tabs or by the special +.Sx \&Ta +block macro. +The tab cell delimiter may only be used within the .Sx \&It -are interpreted within the scope of the last phrase. -Calling the pseudo-macro -.Sq \&Ta -will open a new phrase scope (this must occur on a macro line to be -interpreted as a macro). -Note that the tab phrase delimiter may only be used within the +line itself; on following lines, only the +.Sx \&Ta +macro can be used to delimit cells, and +.Sx \&Ta +is only recognized as a macro when called by other macros, +not as the first macro on a line. +.Pp +Note that quoted strings may span tab-delimited cells on an .Sx \&It -line itself. -Subsequent this, only the -.Sq \&Ta -pseudo-macro may be used to delimit phrases. -Furthermore, note that quoted sections propagate over tab-delimited -phrases on an -.Sx \&It , -for example, +line. +For example, .Pp -.D1 .It \(dqcol1 ; col2 ;\(dq \&; +.Dl .It \(dqcol1 ; col2 ;\(dq \&; .Pp will preserve the semicolon whitespace except for the last. .Pp @@ -2062,10 +2154,10 @@ See also Specify a library. The syntax is as follows: .Pp -.D1 Pf \. Sx \&Lb Cm library +.D1 Pf \. Sx \&Lb Ar library .Pp The -.Cm library +.Ar library parameter may be a system library, such as .Cm libz or @@ -2079,8 +2171,8 @@ section as described in .Sx MANUAL STRUCTURE . .Pp Examples: -.D1 \&.Lb libz -.D1 \&.Lb mdoc +.Dl \&.Lb libz +.Dl \&.Lb mdoc .Ss \&Li Denotes text that should be in a literal font mode. Note that this is a presentation term and should not be used for @@ -2095,11 +2187,11 @@ and Format a hyperlink. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Lk Cm uri Op Cm name +.D1 Pf \. Sx \&Lk Ar uri Op Ar name .Pp Examples: -.D1 \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q -.D1 \&.Lk http://bsd.lv +.Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q +.Dl \&.Lk http://bsd.lv .Pp See also .Sx \&Mt . @@ -2110,21 +2202,21 @@ Synonym for Display a mathematical symbol. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Ms Cm symbol +.D1 Pf \. Sx \&Ms Ar symbol .Pp Examples: -.D1 \&.Ms sigma -.D1 \&.Ms aleph +.Dl \&.Ms sigma +.Dl \&.Ms aleph .Ss \&Mt Format a .Dq mailto: hyperlink. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Mt Cm address +.D1 Pf \. Sx \&Mt Ar address .Pp Examples: -.D1 \&.Mt discuss@manpages.bsd.lv +.Dl \&.Mt discuss@manpages.bsd.lv .Ss \&Nd A one line description of the manual's content. This may only be invoked in the @@ -2134,8 +2226,8 @@ section subsequent the macro. .Pp Examples: -.D1 \&.Sx \&Nd mdoc language reference -.D1 \&.Sx \&Nd format and display UNIX manuals +.Dl \&.Sx \&Nd mdoc language reference +.Dl \&.Sx \&Nd format and display UNIX manuals .Pp The .Sx \&Nd @@ -2192,14 +2284,16 @@ A macro used to terminate prior macro contexts. .Pp Examples: -.D1 \&.Sx \&Fl ab \&No cd \&Fl ef +.Dl \&.Sx \&Fl ab \&No cd \&Fl ef .Ss \&Ns Suppress a space. Following invocation, text is interpreted as free-form text until a macro is encountered. .Pp +This has no effect when invoked at the start of a macro line. +.Pp Examples: -.D1 \&.Fl o \&Ns \&Ar output +.Dl \&.Fl o \&Ns \&Ar output .Pp See also .Sx \&No @@ -2212,8 +2306,8 @@ version provided as an argument, or a default value if no argument is provided. .Pp Examples: -.D1 \&.Nx 5.01 -.D1 \&.Nx +.Dl \&.Nx 5.01 +.Dl \&.Nx .Pp See also .Sx \&At , @@ -2244,8 +2338,8 @@ Used when listing options to command-line utilities. Prints the argument(s) in brackets. .Pp Examples: -.D1 \&.Op \&Fl a \&Ar b -.D1 \&.Op \&Ar a | b +.Dl \&.Op \&Fl a \&Ar b +.Dl \&.Op \&Ar a | b .Pp See also .Sx \&Oo . @@ -2257,18 +2351,18 @@ any file. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Os Op Cm system Op Cm version +.D1 Pf \. Sx \&Os Op Ar system Op Ar version .Pp The optional -.Cm system +.Ar system 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 -.D1 \&.Os KTH/CSC/TCS -.D1 \&.Os BSD 4.3 +.Dl \&.Os +.Dl \&.Os KTH/CSC/TCS +.Dl \&.Os BSD 4.3 .Pp See also .Sx \&Dd @@ -2286,8 +2380,8 @@ version provided as an argument, or a default value if no argument is provided. .Pp Examples: -.D1 \&.Ox 4.5 -.D1 \&.Ox +.Dl \&.Ox 4.5 +.Dl \&.Ox .Pp See also .Sx \&At , @@ -2300,10 +2394,13 @@ and .Sx \&Ux . .Ss \&Pa A file-system path. +If an argument is not provided, the string +.Dq \(ti +is used as a default. .Pp Examples: -.D1 \&.Pa /usr/bin/mandoc -.D1 \&.Pa /usr/share/man/man7/mdoc.7 +.Dl \&.Pa /usr/bin/mandoc +.Dl \&.Pa /usr/share/man/man7/mdoc.7 .Pp See also .Sx \&Lk . @@ -2316,14 +2413,14 @@ Removes the space between its arguments. Its syntax is as follows: .Pp -.D1 Pf \. \&Pf Cm prefix suffix +.D1 Pf \. \&Pf Ar prefix suffix .Pp The -.Cm suffix +.Ar suffix argument may be a macro. .Pp Examples: -.D1 \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix +.Dl \&.Pf \e. \&Sx \&Pf \&Ar prefix suffix .Ss \&Po Multi-line version of .Sx \&Pq . @@ -2406,16 +2503,22 @@ block is used within a SEE ALSO section, a vertical sp before the rendered output, else the block continues on the current line. .Ss \&Rv -Inserts text regarding a function call's return value. -This macro must consist of the -.Fl std -argument followed by an optional -.Ar function . +Insert a standard sentence regarding a function call's return value of 0 +on success and \-1 on error, with the +.Va errno +libc global variable set on error. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Rv Fl std Op Ar function ... +.Pp If .Ar function -is not provided, the document's name as stipulated by the first +is not specified, the document's name set by .Sx \&Nm -is provided. +is used. +Multiple +.Ar function +arguments are treated as separate functions. .Pp See also .Sx \&Ex . @@ -2448,7 +2551,7 @@ By default, spacing is When switched .Cm off , no white space is inserted between macro arguments and between the -output generated from adjacent macros, but free-form text lines +output generated from adjacent macros, but text lines still get normal spacing between words and sentences. .Ss \&So Multi-line version of @@ -2583,7 +2686,12 @@ The referenced section or sub-section name must be ide enclosed argument, including whitespace. .Pp Examples: -.D1 \&.Sx MANUAL STRUCTURE +.Dl \&.Sx MANUAL STRUCTURE +.Pp +See also +.Sx \&Sh +and +.Sx \&Ss . .Ss \&Sy Format enclosed arguments in symbolic .Pq Dq boldface . @@ -2595,11 +2703,16 @@ See also .Sx \&Li , and .Sx \&Em . +.Ss \&Ta +Table cell separator in +.Sx \&Bl Fl column +lists; can only be used below +.Sx \&It . .Ss \&Tn Format a tradename. .Pp Examples: -.D1 \&.Tn IBM +.Dl \&.Tn IBM .Ss \&Ud Prints out .Dq currently under development . @@ -2608,7 +2721,7 @@ Format the UNIX name. Accepts no argument. .Pp Examples: -.D1 \&.Ux +.Dl \&.Ux .Pp See also .Sx \&At , @@ -2623,8 +2736,8 @@ and A variable name. .Pp Examples: -.D1 \&.Va foo -.D1 \&.Va const char *bar ; +.Dl \&.Va foo +.Dl \&.Va const char *bar ; .Ss \&Vt A variable type. This is also used for indicating global variables in the @@ -2643,8 +2756,8 @@ Note that this should not be confused with which is used for function return types. .Pp Examples: -.D1 \&.Vt unsigned char -.D1 \&.Vt extern const char * const sys_signame[] \&; +.Dl \&.Vt unsigned char +.Dl \&.Vt extern const char * const sys_signame[] \&; .Pp See also .Sx MANUAL STRUCTURE @@ -2654,23 +2767,27 @@ 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. +Extend the header of an +.Sx \&It +macro or the body of a partial-implicit block macro +beyond the end of the input line. +This macro originally existed to work around the 9-argument limit +of historic +.Xr roff 7 . .Ss \&Xr Link to another manual .Pq Qq cross-reference . Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Xr Cm name section +.D1 Pf \. Sx \&Xr Ar name section .Pp The -.Cm name +.Ar name and -.Cm section +.Ar section are the name and section of the linked manual. If -.Cm section +.Ar section is followed by non-punctuation, an .Sx \&Ns is inserted into the token stream. @@ -2678,9 +2795,9 @@ This behaviour is for compatibility with GNU troff. .Pp Examples: -.D1 \&.Xr mandoc 1 -.D1 \&.Xr mandoc 1 \&; -.D1 \&.Xr mandoc 1 \&Ns s behaviour +.Dl \&.Xr mandoc 1 +.Dl \&.Xr mandoc 1 \&; +.Dl \&.Xr mandoc 1 \&Ns s behaviour .Ss \&br Emits a line-break. This macro should not be used; it is implemented for compatibility with @@ -2695,10 +2812,10 @@ This macro should not be used; it is implemented for c historical manuals. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&sp Op Cm height +.D1 Pf \. Sx \&sp Op Ar height .Pp The -.Cm height +.Ar height argument must be formatted as described in .Sx Scaling Widths . If unspecified, @@ -2710,10 +2827,10 @@ troff implementations, at this time limited to GNU tro .Pq Qq groff . The term .Qq historic groff -refers to groff versions before the +refers to groff versions before 1.17, +which featured a significant update of the .Pa doc.tmac -file re-write -.Pq somewhere between 1.15 and 1.19 . +file. .Pp Heirloom troff, the other significant troff implementation accepting \-mdoc, is similar to historic groff. @@ -2723,6 +2840,16 @@ The following problematic behaviour is found in groff: .Pp .Bl -dash -compact .It +Display macros +.Po +.Sx \&Bd , +.Sx \&Dl , +and +.Sx \&D1 +.Pc +may not be nested. +\*[hist] +.It .Sx \&At with unknown arguments produces no output at all. \*[hist] @@ -2730,7 +2857,7 @@ Newer groff and mandoc print .Qq AT&T UNIX and the arguments. .It -.Sx \&Bd Fl column +.Sx \&Bl Fl column does not recognize trailing punctuation characters when they immediately precede tabulator characters, but treats them as normal text and outputs a space before them. @@ -2740,9 +2867,12 @@ does not start a new line. \*[hist] .It .Sx \&Dd -without an argument prints -.Dq Epoch . -In mandoc, it resolves to the current date. +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 .Sx \&Fl does not print a dash for an empty argument. @@ -2804,6 +2934,11 @@ can only be called by other macros, but not at the beg .Sx \&%C is not implemented. .It +Historic groff only allows up to eight or nine arguments per macro input +line, depending on the exact situation. +Providing more arguments causes garbled output. +The number of arguments on one input line is not limited with mandoc. +.It Historic groff has many un-callable macros. Most of these (excluding some block-level macros) are callable in new groff and mandoc. @@ -2871,7 +3006,11 @@ This is not supported by mandoc. .Sh SEE ALSO .Xr man 1 , .Xr mandoc 1 , +.Xr eqn 7 , +.Xr man 7 , .Xr mandoc_char 7 +.Xr roff 7 , +.Xr tbl 7 .Sh HISTORY The .Nm