[PATCH] mdoc.7 tweaks.

[PATCH] mdoc.7 tweaks.

[Kristaps Dzonsons]

[-- Attachment #1: Type: text/plain, Size: 772 bytes --]

Hi,

The following patch clarifies some grey areas and fixes some errors in 
mdoc.7.

(1) Properly escaping "." (in several areas).
(2) Non-macro lines properly referred as "text lines" (earlier referred 
to as "free-form", "non-macro", "other", etc.).
(3) The language in the "font scopes" \f section improved.
(4) Note that a comma should be added to multiple `Nm's in SYNOPSIS.
(5) Note ordering of SYNOPSIS section stuff.
(6) Add more info on DESCRIPTION syntax.
(7) Bl can also contain a HEAD.
(8) Make some `Cm' -> `Ar' (jmc, I'm not 100% sure whether it's the 
other way round: I use the `Ar' when documenting either the parameters 
to a macro, like `\&Os Op Ar osname' or the parameters to a macro 
argument, e.t., `\&Rv \-std Op Ar utility')

Thoughts?

Kristaps

[-- Attachment #2: patch.mdoc.txt --]
[-- Type: text/plain, Size: 9945 bytes --]

Index: mdoc.7
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc.7,v
retrieving revision 1.184
diff -u -r1.184 mdoc.7
--- mdoc.7	1 Apr 2011 19:50:49 -0000	1.184
+++ mdoc.7	6 Apr 2011 09:44:54 -0000
@@ -40,25 +40,25 @@
 .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
+Text lines 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 @@
 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 @@
 .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 @@
 .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 @@
 \&.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 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 @@
 \&.Nd a one line description
 .Ed
 .Pp
+When listing multiple
+.Sq \&Nm
+names, comma-separate all but the last.
+.Pp
 The
 .Sx \&Nm
 macro(s) must precede the
@@ -386,16 +388,18 @@
 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 @@
 \&.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 @@
 .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 @@
 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 @@
 .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 @@
 .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
@@ -1430,7 +1451,7 @@
 Switch debugging mode.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Db Cm on | off
+.D1 Pf \. Sx \&Db Ar on | off
 .Pp
 This macro is ignored by
 .Xr mandoc 1 .
@@ -1851,9 +1872,9 @@
 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 @@
 .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 @@
 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 @@
 .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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 .
@@ -2449,14 +2470,14 @@
 Switches the spacing mode for output generated from macros.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Sm Cm on | off
+.D1 Pf \. Sx \&Sm Ar 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 @@
 .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 @@
 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,

Re: [PATCH] mdoc.7 tweaks.

[Kristaps Dzonsons]

[-- Attachment #1: Type: text/plain, Size: 822 bytes --]

Jason, thanks for your feedback.  Enclosed is a corrected patch with the 
exception of the following:

>> -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 :
>
> you should use Sx to refer to other section names.

We don't have section documentation `Ss'd, so I can't refer back to them 
as such.  The reason being that we stipulate (in both `Ss' and `Sh' 
documentation) that names should be unique, so I can't `Ss NAME'.

On the other hand, I agree that `Em' is not a good choice.  Do you have 
another suggestion?  (Note that using `It Em NAME' to document and refer 
to per-section documentation has long since irritated me.)

Thanks,

Kristaps

[-- Attachment #2: patch.mdoc.txt --]
[-- Type: text/plain, Size: 9682 bytes --]

Index: mdoc.7
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc.7,v
retrieving revision 1.184
diff -u -r1.184 mdoc.7
--- mdoc.7	1 Apr 2011 19:50:49 -0000	1.184
+++ mdoc.7	6 Apr 2011 11:08:35 -0000
@@ -40,25 +40,25 @@
 .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 @@
 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 @@
 .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 @@
 .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 @@
 \&.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 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 @@
 \&.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 @@
 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 @@
 \&.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 @@
 .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 @@
 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 @@
 .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 @@
 .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 @@
 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 @@
 .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 @@
 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 @@
 .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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 .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 @@
 .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 @@
 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,

Re: [PATCH] mdoc.7 tweaks.

[Kristaps Dzonsons]

>>>> Jason, thanks for your feedback.  Enclosed is a corrected patch with the
>>>> exception of the following:
>>>>
>>>>>> -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 :
>>>>>
>>>>> you should use Sx to refer to other section names.
>>>>
>>>> We don't have section documentation `Ss'd, so I can't refer back to them
>>>> as such.  The reason being that we stipulate (in both `Ss' and `Sh'
>>>> documentation) that names should be unique, so I can't `Ss NAME'.
>>>>
>>>> On the other hand, I agree that `Em' is not a good choice.  Do you have
>>>> another suggestion?  (Note that using `It Em NAME' to document and refer
>>>> to per-section documentation has long since irritated me.)
>>>>
>>>
>>> hmm. we really only have Em and Sy to play around with in cases like
>>> this. i guess it's just a matter of preference. i have none in
>>> particular...
>>
>> How about `Ss NAME Section' or something similar?  Anything but
>> standalone NAME.  In fact, I'd far prefer something like this than an
>> opaque `Sy NAME' or whatnot.  Thoughts?
>
> i think that would just look messy. you could try, but i'm not
> convinced. many things don;t fit specific macros very well - i don;t see
> the point of worrying about it.

Jason (note re-posting to tech@),

Enclosed is a patch (the prior has been committed) that does just this 
and makes the `Em's used for table headers be `Sy'.  It also notes the 
difference between a "manual section" and a "section" (in my opinion, we 
should really change the term "manual section" to "category" or something).

This uses the schema of "XXXX section" for section documentation, and 
allows the manual to refer directly to this documentation.  Quite handy.

Thoughts?  If you're ambivalent, I note that this makes linked output 
(-T[x]html and -Tpdf/-Tps, which I'd like to implement) much more 
reference-friendly.

Kristaps
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: [PATCH] mdoc.7 tweaks.

[Kristaps Dzonsons]

[-- Attachment #1: Type: text/plain, Size: 31 bytes --]

Beh, this time with the patch.

[-- Attachment #2: patch.mdoc.txt --]
[-- Type: text/plain, Size: 14349 bytes --]

Index: mdoc.7
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc.7,v
retrieving revision 1.185
diff -u -r1.185 mdoc.7
--- mdoc.7	6 Apr 2011 11:39:25 -0000	1.185
+++ mdoc.7	6 Apr 2011 13:08:58 -0000
@@ -274,7 +274,16 @@
 A well-formed
 .Nm
 document consists of a document prologue followed by one or more
-sections.
+sections
+.Po
+note: the term
+.Qq manual section
+refers to the manual category as labelled in
+.Sx \&Dt ,
+while
+.Qq section
+refers to a section wthin the manual document itself
+.Pc .
 .Pp
 The prologue, which consists of the
 .Sx \&Dd ,
@@ -285,16 +294,18 @@
 .Pp
 The first section (sections are denoted by
 .Sx \&Sh )
-must be the NAME section, consisting of at least one
+must be the
+.Sx NAME section ,
+consisting of at least one
 .Sx \&Nm
 followed by
 .Sx \&Nd .
 .Pp
 Following that, convention dictates specifying at least the
-.Em SYNOPSIS
+.Sx SYNOPSIS section
 and
-.Em DESCRIPTION
-sections, although this varies between manual sections.
+.Sx DESCRIPTION section ,
+although this varies between manual sections.
 .Pp
 The following is a well-formed skeleton
 .Nm
@@ -307,7 +318,7 @@
 \&.Nm foo
 \&.Nd a description goes here
 \&.\e\*q .Sh LIBRARY
-\&.\e\*q For sections 2, 3, & 9 only.
+\&.\e\*q For manual sections 2, 3, & 9 only.
 \&.\e\*q Not used in OpenBSD.
 \&.Sh SYNOPSIS
 \&.Nm foo
@@ -320,17 +331,17 @@
 \&.\e\*q .Sh IMPLEMENTATION NOTES
 \&.\e\*q Not used in OpenBSD.
 \&.\e\*q .Sh RETURN VALUES
-\&.\e\*q For sections 2, 3, & 9 only.
+\&.\e\*q For manual sections 2, 3, & 9 only.
 \&.\e\*q .Sh ENVIRONMENT
-\&.\e\*q For sections 1, 6, 7, & 8 only.
+\&.\e\*q For manual sections 1, 6, 7, & 8 only.
 \&.\e\*q .Sh FILES
 \&.\e\*q .Sh EXIT STATUS
-\&.\e\*q For sections 1, 6, & 8 only.
+\&.\e\*q For manual sections 1, 6, & 8 only.
 \&.\e\*q .Sh EXAMPLES
 \&.\e\*q .Sh DIAGNOSTICS
-\&.\e\*q For sections 1, 4, 6, 7, & 8 only.
+\&.\e\*q For manual sections 1, 4, 6, 7, & 8 only.
 \&.\e\*q .Sh ERRORS
-\&.\e\*q For sections 2, 3, & 9 only.
+\&.\e\*q For manual sections 2, 3, & 9 only.
 \&.\e\*q .Sh SEE ALSO
 \&.\e\*q .Xr foobar 1
 \&.\e\*q .Sh STANDARDS
@@ -345,9 +356,7 @@
 The sections in an
 .Nm
 document are conventionally ordered as they appear above.
-Sections should be composed as follows:
-.Bl -ohang -offset Ds
-.It Em NAME
+.Ss NAME section
 The name(s) and a one line description of the documented material.
 The syntax for this as follows:
 .Bd -literal -offset indent
@@ -360,7 +369,6 @@
 Multiple
 .Sq \&Nm
 names should be separated by commas.
-.Pp
 The
 .Sx \&Nm
 macro(s) must precede the
@@ -371,9 +379,9 @@
 .Sx \&Nm
 and
 .Sx \&Nd .
-.It Em LIBRARY
+.Ss LIBRARY section
 The name of the library containing the documented material, which is
-assumed to be a function in a section 2, 3, or 9 manual.
+assumed to be a function in manual section 2, 3, or 9.
 The syntax for this is as follows:
 .Bd -literal -offset indent
 \&.Lb libarm
@@ -381,12 +389,12 @@
 .Pp
 See
 .Sx \&Lb .
-.It Em SYNOPSIS
+.Ss SYNOPSIS section
 Documents the utility invocation syntax, function call syntax, or device
 configuration.
 .Pp
-For the first, utilities (sections 1, 6, and 8), this is
-generally structured as follows:
+For manual sections 1, 6, and 8, commands should be ordered
+alphabetically:
 .Bd -literal -offset indent
 \&.Nm bar
 \&.Op Fl v
@@ -398,38 +406,28 @@
 \&.Op Ar
 .Ed
 .Pp
-Commands should be ordered alphabetically.
-.Pp
-For the second, function calls (sections 2, 3, 9):
+For manual sections 2, 3, and 9, functions, includes, variables, and
+macros should be ordered as follows C header-file conventions:
 .Bd -literal -offset indent
 \&.In header.h
-\&.Vt extern const char *global;
 \&.Ft "char *"
 \&.Fn foo "const char *src"
 \&.Ft "char *"
 \&.Fn bar "const char *src"
+\&.Vt extern const char *global;
 .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):
+And for manual section 4, devices should be ordered alphabetically:
 .Bd -literal -offset indent
 \&.Cd \*qit* at isa? port 0x2e\*q
 \&.Cd \*qit* at isa? port 0x4e\*q
 .Ed
 .Pp
-Manuals not in these sections generally don't need a
-.Em SYNOPSIS .
+Manuals not in these manual sections generally don't need this section.
 .Pp
 Some macros are displayed differently in the
-.Em SYNOPSIS
-section, particularly
+.Sx SYNOPSIS section ,
+particularly
 .Sx \&Nm ,
 .Sx \&Cd ,
 .Sx \&Fd ,
@@ -465,9 +463,9 @@
 or
 .Sx \&Ss
 macro or the end of an enclosing block, whichever comes first.
-.It Em DESCRIPTION
-This begins with an expansion of the brief, one line description in
-.Em NAME :
+.Ss DESCRIPTION section
+This begins with an expansion of the brief, one line description in the
+.Sx NAME section :
 .Bd -literal -offset indent
 The
 \&.Nm
@@ -485,17 +483,17 @@
 .Ed
 .Pp
 Manuals not documenting a command won't include the above fragment.
-.It Em IMPLEMENTATION NOTES
+.Ss IMPLEMENTATION NOTES section
 Implementation-specific notes should be kept here.
 This is useful when implementing standard functions that may have side
 effects or notable algorithmic implications.
-.It Em RETURN VALUES
+.Ss RETURN VALUES section
 This section documents the
-return values of functions in sections 2, 3, and 9.
+return values of functions in manual sections 2, 3, and 9.
 .Pp
 See
 .Sx \&Rv .
-.It Em ENVIRONMENT
+.Ss ENVIRONMENT section
 Lists the environment variables used by the utility,
 and explains the syntax and semantics of their values.
 The
@@ -504,75 +502,74 @@
 .Pp
 See
 .Sx \&Ev .
-.It Em FILES
+.Ss FILES section
 Documents files used.
 It's helpful to document both the file name and a short description of how
 the file is used (created, modified, etc.).
 .Pp
 See
 .Sx \&Pa .
-.It Em EXIT STATUS
+.Ss EXIT STATUS section
 This section documents the
-command exit status for section 1, 6, and 8 utilities.
-Historically, this information was described in
-.Em DIAGNOSTICS ,
+command exit status for manual sections 1, 6, and 8.
+Historically, this information was described in the
+.Sx DIAGNOSTICS section ,
 a practise that is now discouraged.
 .Pp
 See
 .Sx \&Ex .
-.It Em EXAMPLES
+.Ss EXAMPLES section
 Example usages.
 This often contains snippets of well-formed, well-tested invocations.
 Make sure that examples work properly!
-.It Em DIAGNOSTICS
+.Ss DIAGNOSTICS section
 Documents error conditions.
-This is most useful in section 4 manuals.
-Historically, this section was used in place of
-.Em EXIT STATUS
-for manuals in sections 1, 6, and 8; however, this practise is
+This is most useful in manual section 4.
+Historically, this section was used in place of the
+.Sx EXIT STATUS section
+for manual sections 1, 6, and 8; however, this practise is
 discouraged.
 .Pp
 See
 .Sx \&Bl
 .Fl diag .
-.It Em ERRORS
-Documents error handling in sections 2, 3, and 9.
+.Ss ERRORS section
+Documents error handling in manual sections 2, 3, and 9.
 .Pp
 See
 .Sx \&Er .
-.It Em SEE ALSO
+.Ss SEE ALSO section
 References other manuals with related topics.
 This section should exist for most manuals.
-Cross-references should conventionally be ordered first by section, then
-alphabetically.
+Cross-references should conventionally be ordered first by manual
+section, then alphabetically.
 .Pp
 See
 .Sx \&Xr .
-.It Em STANDARDS
+.Ss STANDARDS section
 References any standards implemented or used.
 If not adhering to any standards, the
-.Em HISTORY
-section should be used instead.
+.Sx HISTORY section
+should be used instead.
 .Pp
 See
 .Sx \&St .
-.It Em HISTORY
+.Ss HISTORY section
 A brief history of the subject, including where support first appeared.
-.It Em AUTHORS
+.Ss AUTHORS section
 Credits to the person or persons who wrote the code and/or documentation.
 Authors should generally be noted by both name and email address.
 .Pp
 See
 .Sx \&An .
-.It Em CAVEATS
+.Ss CAVEATS section
 Common misuses and misunderstandings should be explained
 in this section.
-.It Em BUGS
+.Ss BUGS section
 Known bugs, limitations, and work-arounds should be described
 in this section.
-.It Em SECURITY CONSIDERATIONS
+.Ss SECURITY CONSIDERATIONS section
 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,
@@ -598,7 +595,7 @@
 closes it out.
 .Pp
 The
-.Em Callable
+.Sy Callable
 column indicates that the macro may also be called by passing its name
 as an argument to another macro.
 If a macro is not callable but its name appears as an argument
@@ -609,14 +606,14 @@
 .Sq Fl \&Sh .
 .Pp
 The
-.Em Parsed
+.Sy Parsed
 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
+.Sy Scope
 column, if applicable, describes closure rules.
 .Ss Block full-explicit
 Multi-line scope closed by an explicit closing macro.
@@ -633,7 +630,7 @@
 .Ed
 .Pp
 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXX"
-.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
+.It Sy Macro Ta Sy Callable Ta Sy Parsed Ta Sy 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
@@ -666,7 +663,7 @@
 .Ed
 .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 Sy Macro Ta Sy Callable Ta Sy Parsed Ta Sy 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
@@ -680,8 +677,8 @@
 .Sx Block full-implicit
 macro only when invoked as the first macro
 in a
-.Em SYNOPSIS
-section line, else it is
+.Sx SYNOPSIS section
+line, else it is
 .Sx In-line .
 .Ss Block partial-explicit
 Like block full-explicit, but also with single-line scope.
@@ -702,7 +699,7 @@
 .Ed
 .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 Sy Macro Ta Sy Callable Ta Sy Parsed Ta Sy 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
@@ -737,7 +734,7 @@
 .Ed
 .Pp
 .Bl -column "MacroX" "CallableX" "ParsedX" -compact -offset indent
-.It Em Macro Ta Em Callable Ta Em Parsed
+.It Sy Macro Ta Sy Callable Ta Sy Parsed
 .It Sx \&Aq  Ta    Yes      Ta    Yes
 .It Sx \&Bq  Ta    Yes      Ta    Yes
 .It Sx \&Brq Ta    Yes      Ta    Yes
@@ -758,8 +755,8 @@
 .Sx Block partial-implicit
 only when invoked as the first macro
 in a
-.Em SYNOPSIS
-section line, else it is
+.Sx SYNOPSIS section
+line, else it is
 .Sx In-line .
 .Ss In-line
 Closed by
@@ -778,7 +775,7 @@
 .Ed
 .Pp
 .Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -compact -offset indent
-.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments
+.It Sy Macro Ta Sy Callable Ta Sy Parsed Ta Sy 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
@@ -959,11 +956,10 @@
 The effect of selecting either of the
 .Fl split
 modes ends at the beginning of the
-.Em AUTHORS
-section.
+.Sx AUTHORS section .
 In the
-.Em AUTHORS
-section, the default is
+.Sx AUTHORS section ,
+the default is
 .Fl nosplit
 for the first author listing and
 .Fl split
@@ -1561,7 +1557,7 @@
 .Oo
 .Ar title
 .Oo
-.Ar section
+.Ar manual section
 .Op Ar volume | arch
 .Oc
 .Oc
@@ -1574,7 +1570,7 @@
 .Dq UNKNOWN
 if unspecified.
 It should be capitalised.
-.It Ar section
+.It Ar manual section
 The manual section.
 This may be one of
 .Ar 1
@@ -1615,7 +1611,7 @@
 if unspecified.
 .It Ar volume
 This overrides the volume inferred from
-.Ar section .
+.Ar manual section .
 This field is optional, and if specified, must be one of
 .Ar USD
 .Pq users' supplementary documents ,
@@ -1819,7 +1815,7 @@
 Most often, the
 .Sx \&Fa
 macro is used in the
-.Em SYNOPSIS
+.Sx SYNOPSIS section
 within
 .Sx \&Fo
 section when documenting multi-line function prototypes.
@@ -1989,11 +1985,11 @@
 .Dq include
 file.
 In the
-.Em SYNOPSIS
-section (only if invoked as the line macro), the first argument is
+.Sx SYNOPSIS section ,
+if invoked as the line macro and if the first argument is
 preceded by
 .Dq #include ,
-the arguments is enclosed in angle brackets.
+the arguments are enclosed in angle brackets.
 .Pp
 Examples:
 .Dl \&.In sys/types
@@ -2098,8 +2094,8 @@
 invocation; or a custom library, in which case the library name is
 printed in quotes.
 This is most commonly used in the
-.Em SYNOPSIS
-section as described in
+.Sx SYNOPSIS section
+as described in
 .Sx MANUAL STRUCTURE .
 .Pp
 Examples:
@@ -2152,8 +2148,8 @@
 .Ss \&Nd
 A one line description of the manual's content.
 This may only be invoked in the
-.Em SYNOPSIS
-section subsequent the
+.Sx SYNOPSIS section
+subsequent the
 .Sx \&Nm
 macro.
 .Pp
@@ -2181,8 +2177,8 @@
 .Sx \&Nm
 macro expects a single argument, the name of the manual page.
 Usually, the first invocation happens in the
-.Em NAME
-section of the page.
+.Sx NAME section
+of the page.
 The specified name will be remembered and used whenever the macro is
 called again without arguments later in the page.
 The
@@ -2190,8 +2186,8 @@
 macro uses
 .Sx Block full-implicit
 semantics when invoked as the first macro on an input line in the
-.Em SYNOPSIS
-section; otherwise, it uses ordinary
+.Sx SYNOPSIS section ;
+otherwise, it uses ordinary
 .Sx In-line
 semantics.
 .Pp
@@ -2204,8 +2200,8 @@
 .Ed
 .Pp
 In the
-.Em SYNOPSIS
-of section 2, 3 and 9 manual pages, use the
+.Sx SYNOPSIS section
+of manual sections 2, 3 and 9, use the
 .Sx \&Fn
 macro rather than
 .Sx \&Nm
@@ -2825,7 +2821,7 @@
 .It
 .Sx \&In
 ignores additional arguments and is not treated specially in the
-.Em SYNOPSIS .
+.Sx SYNOPSIS section .
 \*[hist]
 .It
 .Sx \&It