[groff] 42/49: groff_mdoc(7): Revise "Conventions" section.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit ce32810390500bba3fb52192c02b6578b2d0d907
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Nov 4 21:10:30 2022 -0500

    groff_mdoc(7): Revise "Conventions" section.
    
    Content:
    * Drop discussion of angle brackets.  They should only be necessary when
      space doesn't separate parameters.
    * Make examples more realistic for experienced Unix users with a
      hypothetical "ztar" command and an actual "ls" one.
    * Recast discussion of implicit and explicit widths for
      comprehensibility.
    
    Style:
    * Perform a Kemper notectomy.
    * Stop using `Ic` where `Li` seems more appropriate.
    * Use `Bl`'s "-compact" flag; stop putting paragraph breaks after inline
      examples.
    * Tighten wording.
    
    Markup:
    * Break input lines after commas.
    * Use an empty request between sentences.
    * Annotate a weirdness in `Bl` behavior (possibly poor understanding on
      my part).
---
 tmac/groff_mdoc.7.man | 106 +++++++++++++++++++++++++++++---------------------
 1 file changed, 62 insertions(+), 44 deletions(-)

diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index 115b3bfc1..e08b4d2d4 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -716,74 +716,92 @@ we use them to illustrate the use of page structure 
domain macros.
 .
 .Sh Conventions
 .
-In the description of all macros below, optional arguments are put into
-brackets.
+In the descriptions of macros below,
+square brackets surround optional arguments.
+.
 An ellipsis
 .Pf ( Sq ... )
-represents zero or more additional arguments.
-Alternative values for a parameter are separated with
-.Ql | .
-If there are alternative values for a mandatory parameter, braces are used
-(together with
-.Ql | )
-to enclose the value set.
-Meta-variables are specified within angles.
+represents repetition of the preceding argument zero or more times.
 .
+Alternative values of a parameter are separated with
+.Ql | .
 .
-.Pp
-Example:
+If a mandatory parameter can take one of several alternative values,
+use braces to enclose the set,
+with spaces and
+.Ql |
+separating the items.
 .
-.Bl -tag -width 6n -offset indent
-.It Li .Xx Xo
-.Aq foo
-.Brq bar1 | bar2
-.Op \-test1 Op \-test2 | \-test3
-.No ...
+.\" XXX: Angle brackets should only be necessary when space doesn't
+.\" separate parameters.
+.\" .
+.\" Metasyntactic variables are specified within angle brackets.
+.\"Bl -tag -width 6n -offset indent -compact
+.Bl -tag -offset indent -compact
+.It Nm ztar Xo
+.Brq Cm c | Cm x
+.Op Fl w Op Fl y | Fl z
+.Op Fl f Ar archive
+.Ar member No ...
 .Xc
 .El
 .
-.
-.Pp
 Except where explicitly stated,
-all macros are parsed and callable.
+all
+.Xr mdoc
+macros are parsed and callable.
 .
 .
 .Pp
-Note that a macro takes effect up to the next nested macro.
+Most macros affect subsequent arguments until another macro or a newline
+is encountered.
 .
 For example,
-.Ql ".Ic foo Aq bar"
+.Sq Li ".Li ls Bq Ar file"
 doesn't produce
-.Sq Ic "foo <bar>"
-but rather
-.Sq Ic foo Aq bar .
+.Sq Li "ls [file]" ,
+but
+.Sq Li ls Bq Ar file .
 .
 Consequently,
 a warning message is emitted for most commands if the first argument is
-a macro itself since it cancels the effect of the calling command
-completely.
-.
-.Sq Ic "foo <bar>"
-is produced by
-.Ql ".Ic \[dq]foo <bar>\[dq]" .
+itself a macro,
+since it cancels the effect of the preceding one.
+.
+On rare occasions,
+you might want to format a word along with surrounding brackets as a
+literal.
+.
+.\" XXX: Why do we need the extra "\ " for the width parameter?  Without
+.\" it, the line breaks before the arrow on a 78n terminal.  But there
+.\" should be room anyway...bug?
+.Bl -tag -width "Li\ \[dq]ls\ [file]\[dq]\ " -offset indent -compact
+.It Li ".Li \[dq]ls [file]\[dq]"
+\[->]
+.Li "ls [file]"
+.Em "# list any files named e, f, i, or l"
+.El
 .
 .
 .Pp
-Most macros have a default width value that can be used to specify a
-label width
-.Pf ( Fl width )
-or offset
-.Pf ( Fl offset )
-for the
-.Ql .Bl
-and
-.Ql .Bd
-macros.
-It is recommended not to use this rather obscure feature to avoid
-dependencies on local modifications of the
+Many macros possess an implicit width,
+used when they are contained in lists and displays.
+.
+If you avoid relying on these default measurements,
+you escape potential conflicts with site-local modifications of the
 .Xr mdoc
 package.
 .
+Explicit
+.Fl width
+and
+.Fl offset
+arguments to the
+.Ql \&Bl
+and
+.Ql \&Bd
+macros are preferable.
+.
 .
 .Sh "Title macros"
 .