diff options
| -rw-r--r-- | mdoc.7 | 143 |
1 files changed, 82 insertions, 61 deletions
@@ -40,25 +40,25 @@ 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 , @@ -102,8 +102,9 @@ Use of reserved terms is described in 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 @@ -132,18 +133,15 @@ escape followed by an indicator: B (bold), I (italic), R (Roman), or P .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 -.Sq \ef -are only valid within the font scope of the macro. -If +If a macro opens a font scope after calling +.Sq \ef , +such as with +.Sx \&Bf , +the .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 @@ -177,9 +175,9 @@ 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 macro lines, whitespace delimits arguments and is discarded. @@ -199,7 +197,7 @@ Thus, the following produces \&.Op "Fl a" .Ed .Pp -In free-form mode, quotes are regarded as opaque text. +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: @@ -270,8 +268,8 @@ 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 @@ -359,6 +357,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 @@ -386,16 +388,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 @@ -406,6 +410,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 @@ -454,9 +466,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,7 +622,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 @@ -1040,7 +1061,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 @@ -1157,7 +1178,7 @@ and .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. +Line breaks in text lines are unaffected. The syntax is as follows: .Pp .D1 Pf \. Sx \&Bk Fl words @@ -1851,9 +1872,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 @@ -1882,15 +1903,15 @@ 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 @@ -1911,7 +1932,7 @@ and A function type. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Ft Cm functype +.D1 Pf \. Sx \&Ft Ar functype .Pp Examples: .Dl \&.Ft int @@ -1992,7 +2013,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 , @@ -2065,14 +2086,14 @@ 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 +.Ar libz or -.Cm libpam , +.Ar libpam , in which case a small library description is printed next to the linker invocation; or a custom library, in which case the library name is printed in quotes. @@ -2098,7 +2119,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 @@ -2113,7 +2134,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 @@ -2124,7 +2145,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 @@ -2262,10 +2283,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. @@ -2324,14 +2345,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 . @@ -2452,11 +2473,11 @@ Its syntax is as follows: .D1 Pf \. Sx \&Sm Cm on | off .Pp By default, spacing is -.Cm on . +.Ar on . When switched -.Cm off , +.Ar 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 @@ -2679,15 +2700,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. @@ -2712,10 +2733,10 @@ This macro should not be used; it is implemented for compatibility with 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, |