[groff] 37/49: groff_mdoc(7): Revise "Getting started" section.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c4c6118c539edf6f1a64beed089488c23fc40a1b
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Nov 4 05:15:17 2022 -0500

    groff_mdoc(7): Revise "Getting started" section.
    
    Content:
    * Refer to mdoc(7) macros without a leading dot.  Not only are they
      generally referred to with the `Ql` macro, which quotes them, but much
      more than man(7) users, mdoc(7) writers need to grasp the fact that
      the leading dot is not part of the macro's name.
    * Dial down editorializing about how hard the roff language is to
      acquire.  mdoc ain't that easy, either, and it doesn't take long for
      this man page to show the reader why.
    * Define the term "call".
    * Add cross references to roff(7) and groff(7) pages for conceptual and
      technical background.
    * Identify (default) *roff control and escape characters as such.  I
      don't think anything is gained by obscuring this crucial information.
    * When introducing the escape character, also present the input line
      continuation escape sequence (`\newline`).
    * Correct introductory presentation of `Fn` macro to more clearly
      distinguish C language function parameters from mdoc macro parameters,
      and remove falsehood about the C standard requiring identifiers in
      function "delcarations".  ANSI didn't and the language still doesn't.
      The writer was thinking of function _definitions_.
    * Identify `\ ` as the "unadjustable space escape sequence".
    * Identify `\~` as the "unbreakable space escape sequence".  Note its
      good, but imperfect, portability.  Add example of its use to group
      words as macro arguments.
    * Point out what's wrong with the counterexample when presenting the
      specification of macro arguments.
    * Rename subsection "Trailing Blank Space Characters" to "Trailing space
      characters".
    * Drop claim that the formatter "can be confused" by trailing spaces.
      It can't.  Perhaps the author of this text was confused by troff
      syntax.  (Alternatively, mdoc's innovative approach to argument
      parsing might create problems where other macro packages would not
      have them.  Is it an accident that no other package works this way?)
    * Rename subsection "Escaping Special Characters" to "Formatting the
      backslash glyph" since that is all it is about.
    * Add subsection "Other possible pitfalls".
    * When telling people not to use the `"` character in macro arguments,
      offer a forward cross reference to "Enclosure and quoting macros".
    * Expand discussion of end-of-sentence detection and how to manage it.
    * 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).
    
    Style:
    * Set (sub)section headings in sentence case, even in cross references
      to (sub)sections not yet revised.  Forthcoming commits will make this
      consistent.
    * Eschew use of `Tn`.  We don't need to style "GNU" with it.
    * Use `Em` to introduce technical terms.  (Bafflingly, mandoc_mdoc(7) is
      much less help than I expected.  It says that `Em` is for "stress",
      not "importance", and `Sy` is for "importance or seriousness", not
      "stress".  Ergo `Em` is for when you want to...stress things that
      aren't important.  ¿Qué?  But `Em` gives the italics I wanted.)
    * Tighten.  For instance, who thought it was helpful to say "dot
      character (`.\&`)" every time it was referred to?  Introduce it once
      and then move on.  That's just one example of this page's garrulous
      approach.
    * Stop using an inline example after a colon as an excuse to avoid
      punctuating a sentence.
    * Use `Bl`'s "-compact" flag more and stop putting paragraph breaks
      after inline examples.  This moves the examples more obviously into
      the running text.  I don't see the point of the former ersatz displays
      when the package (again unlike man(7)) seems to have serviceable
      display macros.
    * Adjust "-width" of examples presented with `Bl`.
    * Drop qualifier "blank" from "blank space".  There are indeed many
      kinds of spaces--but all are blank, so the modifier expresses nothing.
    * Stop using the adverb "directly" in several different contexts to
      suggest something the author meant to express but couldn't find the
      words for.
    * Fix grammar nits (lack of pluralization and so forth).
    
    Markup:
    * Quote phrasal macro arguments to use the package more efficiently.
    * Break input lines after commas, semicolons, and colons.
---
 tmac/groff_mdoc.7.man | 374 +++++++++++++++++++++++++++++---------------------
 1 file changed, 220 insertions(+), 154 deletions(-)

diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index 2a6397dfd..0813511f1 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -149,19 +149,36 @@ The
 .Xr mdoc
 package attempts to simplify the process of writing a man page.
 .
-Theoretically,
-one should not have to learn the tricky details of
-.Tn GNU
-.Xr @g@troff @MAN1EXT@
-to use
-.Xr mdoc ;
-however,
-there are a few limitations that are unavoidable and best gotten out of
-the way.
+One need not master the
+.Xr roff
+language to write them.
 .
-And, too, be forewarned, this package is
-.Em not
-fast.
+We present some essential facts about the formatter's language below.
+.
+For further background,
+including a discussion of basic typographical concepts like
+.Dq breaking ,
+.Dq filling ,
+and
+.Dq adjustment ,
+see
+.Xr roff @MAN7EXT@ .
+.
+Occasional mention is made of typgraphical units of measurement:
+ens,
+vees,
+and
+inches,
+abbreviated
+.Dq n ,
+.Dq v ,
+and
+.Dq i ,
+respectively;
+see section
+.Sx Measurements
+of
+.Xr groff @MAN7EXT@ .
 .
 .
 .Pp
@@ -181,10 +198,14 @@ on the right.
 .
 .Ss "Macro usage"
 .
-As in
-.Tn GNU
-.Xr @g@troff ,
-a macro is called by placing a
+An
+.Xr mdoc
+.Em macro
+is
+.Em called
+by placing the
+.Xr roff
+control character,
 .Ql .\&
 (dot)
 at the beginning of a line followed by the two-
@@ -207,33 +228,42 @@ A dot followed immediately by a newline is ignored;
 this is called the
 .Em "empty request" .
 .
-To place a dot
-.Ql .\&
-at the beginning of an input line in some context other than a macro
-call,
-precede the dot with the
+To place a dot at the beginning of an input line in some context other
+than a macro call,
+precede it with the
 .Ql \e&
 escape sequence;
 this is a dummy character that is never displayed in the output.
 .
+The backslash is the
+.Xr roff
+escape character;
+it can appear anywhere and it always followed by at least one more
+character.
+.
+If followed by a newline,
+the backslash escapes the input line break,
+permitting input lines to kept to a reasonable length without affecting
+their interpretation by
+.Xr @g@troff .
+.
 .
 .Pp
-In general,
-.Tn GNU
-.Xr @g@troff
-macros accept an unlimited number of arguments,
-in contrast to other versions of
-.Xr troff
-that can't handle more than nine arguments.
+Macros in
+.Xr groff
+accept an unlimited number of arguments,
+in contrast to other
+.Xr troff Ns No s
+that often can't handle more than nine.
 .
 In limited cases,
-arguments may be continued or extended on the next line
-(see
-.Sx Extended Arguments
+arguments may be continued or extended on the next input line
+(see subsection
+.Sx "Extended arguments"
 below).
 .
 Almost all macros handle quoted arguments
-(see
+(see subsection
 .Sx "Passing space characters in an argument"
 below).
 .
@@ -251,16 +281,15 @@ text or manual domain macro name
 (and that is defined to be callable)
 will be executed or called when it is processed.
 .
-In this case the argument,
+In such cases,
+the argument,
 although the name of a macro,
-is not preceded by a
-.Ql .\&
-(dot).
+is not preceded by a dot.
 .
 This makes it possible to nest macros;
 for example,
 the option macro,
-.Ql .Op ,
+.Ql \&Op ,
 may
 .Em call
 the flag and argument macros,
@@ -269,7 +298,8 @@ and
 .Ql \&Ar ,
 to specify an optional flag with an argument.
 .
-.Bl -tag -width ".Op\ Fl\ s\ Ar\ bytes" -offset indent -compact
+.\" Use width of second example below.
+.Bl -tag -width ".Op\ \e&Fl\ s\ \e&Ar bytes" -offset indent -compact
 .It Li ".Op Fl s Ar bytes"
 \[->]
 .Op Fl s Ar bytes
@@ -291,16 +321,18 @@ and
 .Ql \&Ar
 are not interpreted as macros.
 .
-Macros whose argument lists are parsed for callable arguments are
+.
+.Pp
+In this document,
+macros whose argument lists are parsed for callable arguments are
 referred to as
 .Em parsed ,
 and those that may be called from an argument list are referred to as
-.Em callable
-throughout this document.
+.Em callable .
 .
 This is a technical
-.Em "faux pas"
-as almost all of the macros in
+.Em "faux pas" ,
+since almost all of the macros in
 .Xr mdoc
 are parsed,
 but as it is cumbersome to constantly refer to macros as being callable
@@ -318,78 +350,79 @@ macro that starts a line
 (with a leading dot)
 a
 .Em command
-if this distinction is necessary.
+if a distinction from those appearing as arguments of other macros is
+necessary.
 .
 .
 .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,
+or more space characters,
 say,
 to specify arguments to commands that expect a particular arrangement of
 items in the argument list.
 .
 Additionally,
-it makes
+quoting multi-word arguments that are to be treated the same makes
 .Xr mdoc
 work faster.
 .
 For example,
 the function command
 .Ql .Fn
-expects the first argument to be the name of a function and any
+expects its first argument to be the name of a function and any
 remaining arguments to be function parameters.
 .
-As
-.Tn ANSI\~C
-stipulates the declaration of function parameters in the parenthesized
-parameter list,
-each parameter is guaranteed to be at minimum a two word string.
-.
-For example,
+Because ANSI\~C mandates the inclusion of types
+.Em and
+identifiers in the parameter lists of function definitions,
+each
+.Ql \&Fn
+parameter after the first will be at least two words in length,
+as in
 .Fa int foo .
 .
 .
 .Pp
-There are two possible ways to pass an argument that contains an
+There are a few possible ways to pass an argument that contains an
 embedded space.
 .
-One way of passing a string containing blank spaces is to use the hard
-or unpaddable space character
+One is to use the unadjustable space escape sequence
 .Ql \e\  ,
 that is,
-a blank space preceded by the escape character
-.Ql \e .
+a space preceded by the escape character.
 .
-This method may be used with any macro but has the side effect of
-interfering with the adjustment of text over the length of a line.
+This method may be used with any macro,
+but has the side effect of not adjusting as other spaces do when an
+output line is formatted.
 .
 .Xr @g@troff
-sees the hard space as if it were any other printable character and
-cannot split the string into blank or newline separated pieces as one
-would expect.
-.
-This method is useful for arguments that are not expected to overlap a
-line boundary.
-.
-An alternative is to use
-.Ql \e\[ti] ,
-a paddable
-(i.e.,
-stretchable),
-unbreakable space
-(this is a
-.Tn GNU
-.Xr @g@troff
-extension).
+treats the unadjustable space as if it were any other printable
+character,
+and will not break a line there as it would a normal space when the
+output line is full.
+.
+This method is useful for macro arguments that are not expected to
+straddle an output line boundary.
+.
+An alternative is to use the unbreakable space escape sequence,
+.Ql \[rs]\[ti] ,
+which cannot break but does adjust.
+.
+This
+.Xr groff
+extension is widely but not perfectly portable.
 .
-The second method is to enclose the string with double quotes.
+Another method is to enclose the string with double quotes.
 .
 .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 char\e\[ti]*str"
+\[->]
+.Fn fetch char\~*str
 .It Li ".Fn fetch \[dq]char *str\[dq]"
 \[->]
 .Fn fetch "char *str"
@@ -398,10 +431,11 @@ The second method is to enclose the string with double 
quotes.
 If the
 .Ql \e
 before the space in the first example
-or double quotes in the second example
+or double quotes in the third example
 were omitted,
 .Ql .Fn
-would see three arguments.
+would see three arguments,
+and the result would contain an undesired comma.
 .
 .\" Use same width as before so it's easier to see the discrepancy.
 .Bl -tag -width ".Fn\ fetch\ \[dq]char\ *str\[dq]" -offset indent \
@@ -412,7 +446,7 @@ would see three arguments.
 .El
 .
 .
-.Pp
+.\".Pp
 .\" For an example of what happens when the parameter list overlaps a
 .\" newline boundary,
 .\" see the
@@ -420,88 +454,115 @@ would see three arguments.
 .\" section.
 .
 .
-.Ss "Trailing Blank Space Characters"
+.Ss "Trailing space characters"
 .
-.Xr @g@troff
-can be confused by blank space characters at the end of a line.
-.
-It is a wise preventive measure to globally remove all blank spaces
-from
-.Ao blank-space Ac Ns Ao end-of-line Ac
-character sequences.
-Should the need arise to use a blank character at the end of a line, it
-may be forced with an unpaddable space and the
-.Ql \e&
-escape character.
-For example,
-.Ql string\e\ \e& .
+.\" XXX: This claim of confusion is nonsense.  The formatter ignores
+.\" them.  If mdoc doesn't, that's a bug or design flaw.  It's still
+.\" good style not to have them.  Whitespace churn makes diff(1) and
+.\" revision control users unhappy.
+.\"
+.\".Xr @g@troff
+.\"can be confused by space characters at the end of a line.
 .
+It is wise to remove trailing spaces from the ends of input lines.
 .
-.Ss "Escaping Special Characters"
+Should the need arise to put a formattable space at the end of a line,
+do so with the unadjustable or unbreakable space escape sequences.
 .
-Special characters like the newline character
-.Ql \en
-are handled by replacing the
-.Ql \e
-with
-.Ql \ee
-(e.g.\&
-.Ql \een )
-to preserve the backslash.
 .
+.Ss "Formatting the backslash glyph"
 .
-.Ss "Other Possible Pitfalls"
+When you need the
+.Xr roff
+escape character
+.Ql \[rs]
+to appear in the output,
+use
+.Ql \[rs]e
+or
+.Ql \[rs][rs]
+instead.
 .
-A warning is emitted when an empty input line is found outside of
-displays
-(see below).
+Technically,
+.Ql \[rs]e
+formats the current escape character;
+it works reliably as long as no
+.Xr roff
+request is used to change it,
+which should never happen in man pages.
 .
-Use
-.Ql .sp
-instead.
+.Ql \[rs][rs]
+is a special character escape sequence that explicitly formats the
+.Dq "reverse solidus"
+(backslash) glyph.
 .
-(It is even better to use
-.Xr mdoc
-macros to avoid the usage of low-level commands.)
+.
+.Ss "Other possible pitfalls"
+.
+.Xr "groff mdoc"
+emits a warning when an empty input line is found outside of a
+.Em display ,
+a topic presented in subsection
+.Sx "Examples and displays"
+below.
 .
 .
 .Pp
-Leading spaces will cause a break and are output directly.
+Leading spaces cause a break and are formatted.
+.
 Avoid this behaviour if possible.
-Similarly, do not use more than one space character between words in an
-ordinary text line; contrary to other text formatters, they are
-.Em not
-replaced with a single space.
+.
+Similarly,
+do not put more than one space between words in an ordinary text line;
+they are not
+.Dq normalized
+to a single space as other text formatters might do.
 .
 .
 .Pp
-You can't pass
+Don't try to use the neutral double quote character
 .Ql \[dq]
-directly as an argument.
+to represent itself in an argument.
 .
-Use
+Use the special character escape sequence
 .Ql \[rs][dq]
-instead.
+to format it.
+.
+Further,
+this glyph should not be used for conventional quotation;
+.Xr mdoc
+offers several quotation macros.
+.
+See subsection
+.Sx "Enclosure and quoting macros"
+below.
 .
 .
 .Pp
-By default,
-.Xr @g@troff
-inserts two space characters after a punctuation mark ending a
-sentence;
-characters like
+The formatter attempts to detect the endings of sentences and puts the
+equivalent of two spaces between sentences on the same output line.
+.
+Characters like
 .Ql \&)
 or
-.Ql \&'
-are treated transparently,
-not influencing the sentence-ending behaviour.
+.Ql \&\[aq]
+after sentence-ending punctuation are ignored for this purpose.
 .
-To change this,
-insert
+Sometimes you will want to end an input line with a
+.Ql \&. ,
+.Ql \&? ,
+or
+.Ql \&!
+that does not end a sentence.
+.
+In a list of macro arguments,
+put
 .Ql \e&
-before or after the dot:
+before the punctuation mark.
 .
-.Bd -literal -offset indent
+Thus,
+.
+.Bd -literal -offset indent -compact
 The
 \&.Ql .
 character.
@@ -517,11 +578,9 @@ test
 test
 .Ed
 .
-.
-.Pp
 gives
 .
-.Bd -filled -offset indent
+.Bd -filled -offset indent -compact
 The
 .Ql .
 character
@@ -543,32 +602,39 @@ test
 test
 .Ed
 .
+as output.
 .
-.Pp
-As can be seen in the first and third line,
+As can be seen in the first and third lines,
 .Xr mdoc
 handles punctuation characters specially in macro arguments.
+.
 This will be explained in section
-.Sx General Syntax
+.Sx "General syntax"
 below.
-In the same way, you have to protect trailing full stops of
-abbreviations with a trailing non-printing input break:
-.Ql e.g.\e& .
+.
+Similarly,
+sentence-ending punctuation characters at the end of an input line that
+isn't an
+.Xr mdoc
+command must
+be suffixed with
+.Ql \[rs]&
+to keep them from being interpreted as sentence endings.
 .
 .
 .Pp
-A comment in the source file of a man page can be either started with
+A comment in the source file of a man page can begin with
 .Ql .\e"
-on a single line,
+at the start of an input line,
 .Ql \e"
-after some input, or
+after other input,
+or
 .Ql \e#
 anywhere
 (the last is a
-.Tn GNU
-.Xr @g@troff
+.Xr groff
 extension);
-the rest of such a line is ignored.
+the remainder of any such line is ignored.
 .
 .
 .Sh "A manual page template"
@@ -632,8 +698,8 @@ These commands identify the page and are discussed below in
 .
 .
 .Pp
-The remaining items in the template are section headers
-.Pf ( Li .Sh ) ;
+The remaining items in the template are section headings
+.Pf ( Ql \&Sh ) ;
 of which
 .Em Name ,
 .Em Synopsis ,