=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.178 retrieving revision 1.197 diff -u -p -r1.178 -r1.197 --- mandoc/mdoc.7 2011/02/02 21:40:45 1.178 +++ mandoc/mdoc.7 2011/08/10 14:07:23 1.197 @@ -1,6 +1,6 @@ -.\" $Id: mdoc.7,v 1.178 2011/02/02 21:40:45 kristaps Exp $ +.\" $Id: mdoc.7,v 1.197 2011/08/10 14:07:23 kristaps 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: February 2 2011 $ +.Dd $Mdocdate: August 10 2011 $ .Dt MDOC 7 .Os .Sh NAME @@ -40,67 +40,33 @@ 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. .Pp -If the first character of a line is a space, that line is printed +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: -.Pp -.Bl -tag -width Ds -offset indent -compact -.It \&. -.Pq period -.It \&, -.Pq comma -.It \&: -.Pq colon -.It \&; -.Pq semicolon -.It \&( -.Pq left-parenthesis -.It \&) -.Pq right-parenthesis -.It \&[ -.Pq left-bracket -.It \&] -.Pq right-bracket -.It \&? -.Pq question -.It \&! -.Pq exclamation -.It \&| -.Pq 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. .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 @@ -129,18 +95,15 @@ escape followed by an indicator: B (bold), I (italic), .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 +137,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 +182,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 +241,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 -.Dl \&Xr mandoc 1 \. -.Dl \&Fl T \&Ns \&Cm ascii \. +.Dl \&.Xr mandoc 1 \&. +.Dl \&.Fl T \&Ns \&Cm ascii \&. .Sh MANUAL STRUCTURE A well-formed .Nm @@ -323,19 +283,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 +343,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 +374,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 +396,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 +452,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: @@ -606,6 +587,17 @@ The .Em Callable 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 zero-width 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, @@ -627,7 +619,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 @@ -669,11 +664,11 @@ has multiple heads. .Pp .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 -.It Sx \&Sh Ta \&No Ta \&No Ta closed by Sx \&Sh -.It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss +.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 +.It Sx \&Sh Ta \&No Ta Yes Ta closed by Sx \&Sh +.It Sx \&Ss Ta \&No Ta Yes Ta closed by Sx \&Sh , Sx \&Ss .El .Pp Note that the @@ -731,9 +726,8 @@ and/or tail .It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc .El .Ss Block partial-implicit -Like block full-implicit, but with single-line scope closed by -.Sx Reserved Characters -or end of line. +Like block full-implicit, but with single-line scope closed by the +end of the line. .Bd -literal -offset indent \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB .Ed @@ -763,10 +757,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 , -end of line, fixed argument lengths, and/or subsequent macros. +Closed by the end of the 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 , @@ -825,7 +833,7 @@ then the macro accepts an arbitrary number of argument .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 >0 .It Sx \&Lk Ta Yes Ta Yes Ta >0 @@ -856,6 +864,90 @@ then the macro accepts an arbitrary number of argument .It Sx \&br Ta \&No Ta \&No Ta 0 .It Sx \&sp Ta \&No Ta \&No Ta 1 .El +.Ss Delimiters +When a macro argument consists of one single input character +considered as a delimiter, the argument gets special handling. +This does not apply when delimiters appear in arguments containing +more than one character. +Consequently, to prevent special handling and just handle it +like any other argument, a delimiter can be escaped by prepending +a zero-width space +.Pq Sq \e& . +In text lines, delimiters never need escaping, but may be used +as normal punctuation. +.Pp +For many macros, when the leading arguments are opening delimiters, +these delimiters are put before the macro scope, +and when the trailing arguments are closing delimiters, +these delimiters are put after the macro scope. +For example, +.Pp +.D1 Pf \. \&Aq "( [ word ] ) ." +.Pp +renders as: +.Pp +.D1 Aq ( [ word ] ) . +.Pp +Opening delimiters are: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&( +left parenthesis +.It \&[ +left bracket +.El +.Pp +Closing delimiters are: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&. +period +.It \&, +comma +.It \&: +colon +.It \&; +semicolon +.It \&) +right parenthesis +.It \&] +right bracket +.It \&? +question mark +.It \&! +exclamation mark +.El +.Pp +Note that even a period preceded by a backslash +.Pq Sq \e.\& +gets this special handling; use +.Sq \e&. +to prevent that. +.Pp +Many in-line macros interrupt their scope when they encounter +delimiters, and resume their scope when more arguments follow that +are not delimiters. +For example, +.Pp +.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" +.Pp +renders as: +.Pp +.D1 Fl a ( b | c \*(Ba d ) e +.Pp +This applies to both opening and closing delimiters, +and also to the middle delimiter: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&| +vertical bar +.El +.Pp +As a special case, the predefined string \e*(Ba is handled and rendered +in the same way as a plain +.Sq \&| +character. +Using this predefined string is not recommended in new manuals. .Sh REFERENCE This section is a canonical reference of all macros, arranged alphabetically. @@ -884,8 +976,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 @@ -943,6 +1037,8 @@ Examples: .Dl \&.Ad 0x00000000 .Ss \&An Author name. +Can be used both for the authors of the program, function, or driver +documented in the manual, or for the authors of the manual itself. Requires either the name of an author or one of the following arguments: .Pp .Bl -tag -width "-nosplitX" -offset indent -compact @@ -1013,9 +1109,17 @@ If an argument is not provided, the string is used as a default. .Pp Examples: -.Dl \&.Fl o \&Ns \&Ar file1 -.Dl \&.Ar -.Dl \&.Ar arg1 , arg2 . +.Dl ".Fl o Ar file" +.Dl ".Ar" +.Dl ".Ar arg1 , arg2 ." +.Pp +The arguments to the +.Sx \&Ar +macro are names and placeholders for command arguments; +for fixed strings to be passed verbatim as arguments, use +.Sx \&Fl +or +.Sx \&Cm . .Ss \&At Formats an AT&T version. Accepts one optional argument: @@ -1024,6 +1128,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 . @@ -1033,6 +1139,7 @@ Note that these arguments do not begin with a hyphen. .Pp Examples: .Dl \&.At +.Dl \&.At III .Dl \&.At V.1 .Pp See also @@ -1061,7 +1168,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 @@ -1176,9 +1283,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 @@ -1414,6 +1522,7 @@ and Kernel configuration declaration. This denotes strings accepted by .Xr config 8 . +It is most often used in section 4 manual pages. .Pp Examples: .Dl \&.Cd device le0 at scode? @@ -1426,14 +1535,17 @@ declarations. This practise is discouraged. .Ss \&Cm Command modifiers. -Useful when specifying configuration options or keys. +Typically used for fixed strings passed as arguments, unless +.Sx \&Fl +is more appropriate. +Also useful when specifying configuration options or keys. .Pp Examples: -.Dl \&.Cm ControlPath -.Dl \&.Cm ControlMaster -.Pp -See also -.Sx \&Fl . +.Dl ".Nm mt Fl f Ar device Cm rewind" +.Dl ".Nm ps Fl o Cm pid , Ns Cm command" +.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2" +.Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa" +.Dl ".Cm LogLevel Dv DEBUG" .Ss \&D1 One-line indented display. This is formatted by the default rules and is useful for simple indented @@ -1467,17 +1579,36 @@ 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: .Dl \&.Dd $\&Mdocdate$ @@ -1672,14 +1803,21 @@ See also 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: +.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. @@ -1755,14 +1893,18 @@ 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. +This is most often used in section 2 and 3 manual pages. .Pp Examples: .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 @@ -1772,17 +1914,26 @@ Environmental variables such as those specified in Examples: .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. +This is most often used in section 1, 6, and 8 manual pages. 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 . @@ -1831,7 +1982,7 @@ See also and .Sx \&In . .Ss \&Fl -Command-line flag. +Command-line flag or option. Used when listing arguments to command-line utilities. Prints a fixed-width hyphen .Sq \- @@ -1841,10 +1992,11 @@ If the argument is a macro, a hyphen is prefixed to th output. .Pp Examples: -.Dl \&.Fl a b c -.Dl \&.Fl \&Pf a b -.Dl \&.Fl -.Dl \&.Op \&Fl o \&Ns \&Ar file +.Dl ".Nm cat Fl v No considered harmful" +.Dl ".Nm cp Fl pR Ar source ... directory" +.Dl ".Nm find Ar dir Fl type Cm d Fl name Pa CVS +.Dl ".Nm kill Fl Ar signal_number pid" +.Dl ".Nm su Fl" .Pp See also .Sx \&Cm . @@ -1853,19 +2005,24 @@ 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 are delimited by commas. If no arguments are specified, blank parenthesis are output. +In the +.Em SYNOPSIS +section, this macro starts a new output line, +and a blank line is automatically inserted between function definitions. .Pp Examples: -.Dl \&.Fn "int funcname" "int arg0" "int arg1" -.Dl \&.Fn funcname "int arg0" +.Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q +.Dl \&.Fn funcname \*qint arg0\*q .Dl \&.Fn funcname arg0 +.Pp .Bd -literal -offset indent -compact \&.Ft functype \&.Fn funcname @@ -1875,7 +2032,8 @@ When referring to a function documented in another man .Sx \&Xr instead. See also -.Sx MANUAL STRUCTURE +.Sx MANUAL STRUCTURE , +.Sx \&Fo , and .Sx \&Ft . .Ss \&Fo @@ -1884,17 +2042,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 @@ -1902,6 +2060,7 @@ Invocations usually occur in the following context: A .Sx \&Fo scope is closed by +.Sx \&Fc . .Pp See also .Sx MANUAL STRUCTURE , @@ -1909,12 +2068,18 @@ 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 +In the +.Em SYNOPSIS +section, a new output line is started after this macro. +.Pp Examples: .Dl \&.Ft int .Bd -literal -offset indent -compact @@ -1955,6 +2120,7 @@ This is similar to but used for instructions rather than values. .Pp Examples: +.Dl \&.Ic :wq .Dl \&.Ic hash .Dl \&.Ic alias .Pp @@ -1969,15 +2135,17 @@ macro is used when referring to specific instructions. An .Dq include file. -In the +When invoked as the first macro on an input line in the .Em SYNOPSIS -section (only if invoked as the line macro), the first argument is -preceded by +section, the argument is displayed in angle brackets +and preceded by .Dq #include , -the arguments is enclosed in angle brackets. +and a blank line is inserted in front if there is a preceding +function declaration. +This is most often used in section 2, 3, and 9 manual pages. .Pp Examples: -.Dl \&.In sys/types +.Dl \&.In sys/types.h .Pp See also .Sx MANUAL STRUCTURE . @@ -1994,7 +2162,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 , @@ -2031,31 +2199,27 @@ 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 .Dl .It \(dqcol1 ; col2 ;\(dq \&; .Pp @@ -2067,10 +2231,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 @@ -2100,7 +2264,7 @@ 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: .Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q @@ -2115,7 +2279,7 @@ 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: .Dl \&.Ms sigma @@ -2126,7 +2290,7 @@ Format a hyperlink. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Mt Cm address +.D1 Pf \. Sx \&Mt Ar address .Pp Examples: .Dl \&.Mt discuss@manpages.bsd.lv @@ -2246,9 +2410,11 @@ Examples: \&.Oc .Ed .Ss \&Op -Command-line option. -Used when listing options to command-line utilities. +Optional part of a command line. Prints the argument(s) in brackets. +This is most often used in the +.Em SYNOPSIS +section of section 1 and 8 manual pages. .Pp Examples: .Dl \&.Op \&Fl a \&Ar b @@ -2264,10 +2430,10 @@ 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. @@ -2306,9 +2472,9 @@ See also and .Sx \&Ux . .Ss \&Pa -A file-system path. -If an argument is not provided, the string -.Dq \(ti +An absolute or relative file system path, or a file or directory name. +If an argument is not provided, the character +.Sq \(ti is used as a default. .Pp Examples: @@ -2326,14 +2492,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: -.Dl \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix +.Dl \&.Pf \e. \&Sx \&Pf \&Ar prefix suffix .Ss \&Po Multi-line version of .Sx \&Pq . @@ -2416,16 +2582,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 . @@ -2441,6 +2613,9 @@ custom sections be used. .Pp Section names should be unique so that they may be keyed by .Sx \&Sx . +Although this macro is parsed, it should not consist of child node or it +may not be linked with +.Sx \&Sx . .Pp See also .Sx \&Pp , @@ -2458,7 +2633,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 @@ -2484,6 +2659,9 @@ rarely have sub-sections. .Pp Sub-section names should be unique so that they may be keyed by .Sx \&Sx . +Although this macro is parsed, it should not consist of child node or it +may not be linked with +.Sx \&Sx . .Pp See also .Sx \&Pp , @@ -2565,6 +2743,7 @@ The following standards are recognised: .St -xpg4 .It \-xpg4.2 .St -xpg4.2 +.It \-xpg4.3 .St -xpg4.3 .It \-xbd5 .St -xbd5 @@ -2610,6 +2789,11 @@ 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 @@ -2647,11 +2831,14 @@ This is also used for indicating global variables in t 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 +syntax when invoked as the first macro on an input line in the .Em SYNOPSIS section, else it accepts ordinary .Sx In-line syntax. +In the former case, this macro starts a new output line, +and a blank line is inserted in front if there is a preceding +function definition or include directive. .Pp Note that this should not be confused with .Sx \&Ft , @@ -2681,15 +2868,15 @@ 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. @@ -2714,10 +2901,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, @@ -2759,7 +2946,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. @@ -2769,9 +2956,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. @@ -2816,7 +3006,7 @@ In new groff and mandoc, any list may be nested by def lists will restart the sequence only for the sub-list. .It .Sx \&Li -followed by a reserved character is incorrectly used in some manuals +followed by a delimiter is incorrectly used in some manuals instead of properly quoting that character, which sometimes works with historic groff. .It @@ -2905,6 +3095,7 @@ 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 ,