[groff] 31/49: groff_mdoc(7): Revise introductory subsections.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit fa57adaf0b437315805d6cc326414c9abfb654b2
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Nov 3 09:59:07 2022 -0500

    groff_mdoc(7): Revise introductory subsections.
    
    Content:
    * Say something good about mdoc; its semantic emphasis has prevented the
      effloresence of inconsistent style markup exhibited by man(7) pages.
    * 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.
    * Introduce right-arrow notation convention so we can present examples
      more compactly.
    * Stop referring to a dot in a laborious manner.
    * Convert inline examples to use new arrow convention.
    * Refer to "words", not "strings".  "Strings" are a roff language
      element that we should not introduce in inappropriate contexts.
    * Break input lines after commas.
    * Wrap long input lines.
    
    Style:
    * In summary-description, mark up "roff" with `Xr`.
    * Cross reference groff(1) man page in introduction.
    * Set subsection headings in sentence case and update `Sx` cross refs.
    * Tighten wording.
---
 tmac/groff_mdoc.7.man | 167 +++++++++++++++++++++++++++-----------------------
 1 file changed, 91 insertions(+), 76 deletions(-)

diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index 0c2df57b2..0e098f45a 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -55,7 +55,8 @@
 .Sh Name
 .
 .Nm groff_mdoc
-.Nd compose BSD-style manual (man) pages with GNU roff
+.Nd compose BSD-style manual (man) pages with GNU
+.Xr roff
 .
 .
 .Sh Synopsis
@@ -68,15 +69,15 @@
 The GNU implementation of the
 .Xr mdoc
 macro package is part of the
-.Xr groff
+.Xr groff @MAN1EXT@
 document formatting system.
 .
 .Xr mdoc
 is a
-.Em content Ns -based
+.Em content-
 and
 .Em domain Ns -based
-formatting package designed for writing
+formatting package for writing
 .Ux
 manual pages with
 .Xr @g@troff @MAN1EXT@ .
@@ -85,36 +86,37 @@ Its predecessor,
 the
 .Xr man 7
 package,
-addressed page layout leaving the manipulation of fonts and other
-typesetting details to the individual author.
+primarily addressed page layout concerns,
+leaving the selection of fonts and other typesetting details to the
+individual author.
+.
+This discretion has led to divergent styling practices among authors
+using it.
 .
 In
 .Xr mdoc ,
 page layout macros make up the
 .Em "page structure domain"
-which consists of macros for titles,
-section headers,
+that comprises macros for titles,
+section headings,
 displays,
 and lists\[em]essentially items which affect the physical position of
 text on a formatted page.
 .
-In addition to the page structure domain,
-there are two more domains,
-the
-.Em manual
-domain and the
-.Em general
-text domain.
-The general text domain is defined as macros which perform tasks such as
-quoting or emphasizing pieces of text.
-.
-The manual domain is defined as macros that are a subset of the day to
-day informal language used to describe commands,
-routines and related
+The
+.Em "general text domain"
+contains macros to perfom tasks such as quoting or styling text.
+.
+The
+.Em "manual domain"
+defines macros corresponding to the terminology used by practitioners
+in discussion of
 .Ux
-files.
+commands,
+routines,
+and files.
 .
-Macros in the manual domain handle command names,
+Manual domain macros distinguish
 command-line arguments and options,
 function names,
 function parameters,
@@ -123,8 +125,8 @@ variables,
 cross references to other manual pages,
 and so on.
 .
-These domain items have value for both the author and the future user of
-the manual page.
+These terms are meaningful both to the author and the readers of a
+manual page.
 .
 It is hoped that the resulting increased consistency of the man page
 corpus will enable easier translation to future documentation tools.
@@ -162,7 +164,22 @@ And, too, be forewarned, this package is
 fast.
 .
 .
-.Ss "Macro Usage"
+.Pp
+We present many examples in this document;
+for brief ones,
+we may use an arrow notation that illustrates input on the left and
+output as rendered by
+.Xr mdoc
+on the right.
+.
+.Bl -tag -width ".Dq\ man page" -offset indent -compact
+.It Li ".Dq man page"
+\[->]
+.Dq man page
+.El
+.
+.
+.Ss "Macro usage"
 .
 As in
 .Tn GNU
@@ -190,16 +207,14 @@ A dot followed immediately by a newline is ignored;
 this is called the
 .Em "empty request" .
 .
-To place a
+To place a dot
 .Ql .\&
-(dot character) at the beginning of an input line in some context other
-than a macro invocation,
-precede the
-.Ql .\&
-(dot) with the
+at the beginning of an input line in some context other than a macro
+call,
+precede the dot with the
 .Ql \e&
-escape sequence which causes a non-printing input break,
-and is never displayed in the output.
+escape sequence;
+this is a dummy character that is never displayed in the output.
 .
 .
 .Pp
@@ -219,7 +234,7 @@ below).
 .
 Almost all macros handle quoted arguments
 (see
-.Sx Passing Space Characters in an Argument
+.Sx "Passing space characters in an argument"
 below).
 .
 .
@@ -254,42 +269,44 @@ and
 .Ql \&Ar ,
 to specify an optional flag with an argument.
 .
-For example,
-.\"Bl -tag -width ".Op Fl s Ar bytes" -offset indent
-.D1 Op Fl s Ar bytes
-.\"It Op Fl s Ar bytes
-is produced by
-.Ql ".Op Fl s Ar bytes" .
-.\"El
+.Bl -tag -width ".Op\ Fl\ s\ Ar\ bytes" -offset indent -compact
+.It Li ".Op Fl s Ar bytes"
+\[->]
+.Op Fl s Ar bytes
+.El
 .
 To prevent a word from being interpreted as a macro name,
 precede it with the escape sequence
 .Ql \e& .
 .
-.\"Bl -tag -width ".Op \&Fl s \&Ar bytes" -offset indent
-.\"It Op \&Fl s \&Ar bytes
-.D1 Op \&Fl s \&Ar bytes
-is produced by
-.Ql ".Op \e&Fl s \e&Ar bytes" .
-.\"El
+.Bl -tag -width ".Op\ \e&Fl\ s\ \e&Ar bytes" -offset indent -compact
+.It Li ".Op \e&Fl s \e&Ar bytes"
+\[->]
+.Op \&Fl s \&Ar bytes
+.El
 .
-Here the strings
+Here the words
 .Ql \&Fl
 and
 .Ql \&Ar
 are not interpreted as macros.
-Macros whose argument lists are parsed for callable arguments are referred
-to as
-.Em parsed
-and macros which may be called from an argument list are referred to as
+.
+Macros whose argument lists are parsed for callable arguments are
+referred to as
+.Em parsed ,
+and those which may be called from an argument list are referred to as
 .Em callable
 throughout this document.
+.
 This is a technical
-.Em faux pas
+.Em "faux pas"
 as almost all of the macros in
 .Xr mdoc
-are parsed, but as it was cumbersome to constantly refer to macros as
-being callable and being able to call other macros, the term parsed
+are parsed,
+but as it is cumbersome to constantly refer to macros as being callable
+and being able to call other macros,
+the term
+.Dq parsed
 has been used.
 .
 .
@@ -304,7 +321,7 @@ a
 if this distinction is necessary.
 .
 .
-.Ss "Passing Space Characters in an Argument"
+.Ss "Passing space characters in an argument"
 .
 Sometimes it is desirable to give as an argument a string containing one
 or more blank space characters,
@@ -368,33 +385,31 @@ extension).
 .
 The second method is to enclose the string with double quotes.
 .
-.
-.Pp
-For example:
-.
-.Bl -tag -width ".Fn fetch char\ *str" -offset indent
-.It Fn fetch char\ *str
-is created by
-.Ql ".Fn fetch char\e *str"
-.It Fn fetch "char *str"
-can also be created by
-.Ql ".Fn fetch \[dq]char *str\[dq]"
+.Bl -tag -width ".Fn\ fetch\ \[dq]char\ *str\[dq]" -offset indent \
+-compact
+.It Li ".Fn fetch char\e *str"
+\[->]
+.Fn fetch char\ *str
+.It Li ".Fn fetch \[dq]char *str\[dq]"
+\[->]
+.Fn fetch "char *str"
 .El
 .
-.
-.Pp
 If the
 .Ql \e
 before the space in the first example
 or double quotes in the second example
 were omitted,
 .Ql .Fn
-would see three arguments,
-and the result would be:
-.
-.
-.Pp
-.Dl Fn fetch char *str
+would see three arguments.
+.
+.\" Use same width as before so it's easier to see the discrepancy.
+.Bl -tag -width ".Fn\ fetch\ \[dq]char\ *str\[dq]" -offset indent \
+-compact
+.It Li ".Fn fetch char *str"
+\[->]
+.Fn fetch char *str
+.El
 .
 .
 .Pp