[groff] 38/49: groff_mdoc(7): Revise § "A manual page template".

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit fc6691ce0a5e9201e68948b290f0608e3ba56ca1
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Nov 4 05:35:56 2022 -0500

    groff_mdoc(7): Revise § "A manual page template".
    
    Content:
    * Rename the section to use the term "man page", from "manual page".
    * Recast introduction.  The template is for mdoc(7) pages specifically.
    * Nest the bracketing of successive optional macro arguments.
    * Revise man page sectioning template, in part to conform with
      groff_man(7) terminology.
      - "document-title" -> "page-topic"
      - Hyphenate metasyntactic variable phrases.
      - Use "or" in metasyntactic variable phrases.
      - "name" -> "page-topic"
      - "one line description of name" -> "summary-description"
      - Revise heading/section number inclusion recommendations.
        * Drop parenthesized explanations of heading meanings.  They are
          presented later.
        * Admit "Environment" to section 3.  User space libraries frequently
          consult the process environment.
        * Remove "Environment" and "Diagnostics" from section 7.  They
          _might_ be warranted there, but uncommonly.  Anything that calls
          getenv() or putenv() or writes to the standard error stream will
          be implemented by something that likely should have a man page in
          another section.
    * Recast introduction to title macros.
    * Present `Dd`, `Dt`, and `Os` macro names without leading dot.
    * When cross referencing with `Sx`, identify target heading as "section"
      or "subsection" as appropriate.  A savvy reader can use this
      information to find such headings more reliably with pagers (because
      section headings are set flush left while subsections are indented)
      and editors (because they use different macros).
    * Use `Sx`, not `Em`, to cross reference section headings, even
      hypothetical ones.
    * Say 'section "headings"', not "headers".  The header is formatted at
      the top of the page and is the counterpart of the footer.  A "heading"
      organizes paragraphs.
    * Undocument "Synopsis" as a mandatory section heading.  It's not
      necessarily applicable in sections 5 or 7, for instance.
    * Speak of the "manual domain", not "content macros".  The latter
      appears to be synonymous with the former and this page already dumps
      copious amounts of bespoke jargon onto the reader.
    
    Style:
    * Illustrate use of quoted multi-word arguments with `Sh` macro calls.
    * Stop using a colon as an excuse to not end a sentence.
    * Quote phrasal macro arguments to use the package more efficiently.
    * Break input lines after commas, semicolons, and colons.
---
 tmac/groff_mdoc.7.man | 74 +++++++++++++++++++++++++--------------------------
 1 file changed, 36 insertions(+), 38 deletions(-)

diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index 0813511f1..8fc593df8 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -637,43 +637,41 @@ extension);
 the remainder of any such line is ignored.
 .
 .
-.Sh "A manual page template"
+.Sh "A man page template"
 .
-The body of a man page is easily constructed from a basic template:
+Use
+.Xr mdoc
+to construct a man page from the following template.
 .
 .Bd -literal -offset indent
 \&.\e" The following commands are required for all man pages.
 \&.Dd date
-\&.Dt document-title [section number] [architecture/volume]
-\&.Os [package or operating system] [version/release]
+\&.Dt page-topic [section-number [volume-name]]
+\&.Os [package-or-operating system [version-or-release]]
 \&.Sh Name
-\&.Nm name
-\&.Nd one line description of name
-\&.\e" This next command is for sections 2 and 3 only.
+\&.Nm page-topic
+\&.Nd summary-description
+\&.\e" The next heading is used in sections 2 and 3.
 \&.\e" .Sh Library
+\&.\e" The next heading is used in sections 1-4, 6, 8, and 9.
 \&.Sh Synopsis
 \&.Sh Description
-\&.\e" The following commands should be uncommented and
-\&.\e" used where appropriate.
-\&.\e" .Sh Implementation notes
-\&.\e" This next command is for sections 2, 3, and 9 only
-\&.\e"     (function return values).
-\&.\e" .Sh Return values
-\&.\e" This next command is for sections 1, 6, 7, and 8 only.
+\&.\e" Uncomment and populate the following sections where appropriate.
+\&.\e" .Sh \[dq]Implementation notes\[dq]
+\&.\e" The next heading is used in sections 2, 3, and 9.
+\&.\e" .Sh \[dq]Return values\[dq]
+\&.\e" The next heading is used in sections 1, 3, 6, and 8.
 \&.\e" .Sh Environment
 \&.\e" .Sh Files
-\&.\e" This next command is for sections 1, 6, and 8 only
-\&.\e"     (command return values to the shell).
-\&.\e" .Sh Exit status
+\&.\e" The next heading is used in sections 1, 6, and 8.
+\&.\e" .Sh \[dq]Exit status\[dq]
 \&.\e" .Sh Examples
-\&.\e" This next command is for sections 1, 4, 6, 7, 8, and 9 only
-\&.\e"     (fprintf/stderr type diagnostics).
+\&.\e" The next heading is used in sections 1, 4, 6, 8, and 9.
 \&.\e" .Sh Diagnostics
 \&.\e" .Sh Compatibility
-\&.\e" This next command is for sections 2, 3, 4, and 9 only
-\&.\e"     (settings of the errno variable).
+\&.\e" The next heading is used in sections 2, 3, 4, and 9.
 \&.\e" .Sh Errors
-\&.\e" .Sh See also
+\&.\e" .Sh \[dq]See also\[dq]
 \&.\e" .Sh Standards
 \&.\e" .Sh History
 \&.\e" .Sh Authors
@@ -684,36 +682,36 @@ The body of a man page is easily constructed from a basic 
template:
 .
 .Pp
 The first items in the template are the commands
-.Ql .Dd ,
-.Ql .Dt ,
+.Ql \&Dd ,
+.Ql \&Dt ,
 and
-.Ql .Os ;
-the document date,
-the document title and section of the manual the page belongs in,
-and either the project or package supplying the page or the operating
-system it is developed or modified for.
+.Ql \&Os .
 .
-These commands identify the page and are discussed below in
-.Sx Title macros .
+These correspond to the document date;
+the page topic and section of the manual to which the page belongs;
+and the project or package supplying the page,
+or the operating system for which it is developed.
+.
+These commands identify the page and are discussed below in section
+.Sx "Title macros" .
 .
 .
 .Pp
 The remaining items in the template are section headings
 .Pf ( Ql \&Sh ) ;
 of which
-.Em Name ,
-.Em Synopsis ,
+.Sx Name
 and
-.Em Description
+.Sx Description
 are mandatory.
 .
-The headers are discussed in
+These headings are discussed in section
 .Sx "Page structure domain" ,
-after presentation of
+which follows section
 .Sx "Manual domain" .
 .
-Several content macros are used to demonstrate page layout macros; reading
-about content macros before page layout macros is recommended.
+Familiarize yourself with manual domain macros first;
+we use them to illustrate the use of page layout domain macros.
 .
 .
 .Sh Conventions