From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp-2.sys.kth.se (smtp-2.sys.kth.se [130.237.32.160]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id p36DKPn1014674 for ; Wed, 6 Apr 2011 09:20:26 -0400 (EDT) Received: from mailscan-1.sys.kth.se (mailscan-1.sys.kth.se [130.237.32.91]) by smtp-2.sys.kth.se (Postfix) with ESMTP id 19E1814D7E0; Wed, 6 Apr 2011 15:20:20 +0200 (CEST) X-Virus-Scanned: by amavisd-new at kth.se Received: from smtp-2.sys.kth.se ([130.237.32.160]) by mailscan-1.sys.kth.se (mailscan-1.sys.kth.se [130.237.32.91]) (amavisd-new, port 10024) with LMTP id nI5d09lw+MzV; Wed, 6 Apr 2011 15:20:17 +0200 (CEST) X-KTH-Auth: kristaps [193.10.49.5] X-KTH-mail-from: kristaps@bsd.lv Received: from [172.16.18.84] (unknown [193.10.49.5]) by smtp-2.sys.kth.se (Postfix) with ESMTP id 321C314D7CB; Wed, 6 Apr 2011 15:20:17 +0200 (CEST) Message-ID: <4D9C6890.7060006@bsd.lv> Date: Wed, 06 Apr 2011 15:20:16 +0200 From: Kristaps Dzonsons User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.1.16) Gecko/20110303 Icedove/3.0.11 X-Mailinglist: mdocml-tech Reply-To: tech@mdocml.bsd.lv MIME-Version: 1.0 To: tech@mdocml.bsd.lv CC: Jason McIntyre Subject: Re: [PATCH] mdoc.7 tweaks. References: <4D9C3699.7080802@bsd.lv> <20110406104809.GD7870@harkle.bramka> <4D9C4B1C.9060206@bsd.lv> <20110406112651.GE7870@harkle.bramka> <4D9C4E84.7080809@bsd.lv> <20110406124016.GF7870@harkle.bramka> <4D9C677B.2010804@bsd.lv> In-Reply-To: <4D9C677B.2010804@bsd.lv> Content-Type: multipart/mixed; boundary="------------040303010903070904090600" This is a multi-part message in MIME format. --------------040303010903070904090600 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Beh, this time with the patch. --------------040303010903070904090600 Content-Type: text/plain; name="patch.mdoc.txt" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="patch.mdoc.txt" 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 --------------040303010903070904090600-- -- To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv