Re: [PATCH] mdoc.7 tweaks.

[Kristaps Dzonsons <kristaps@bsd.lv>]

[-- 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