[groff] 04/21: groff_mdoc(7): Revise presentation of `No`.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 6746aabc30334964c796886fc42a34ac648df211
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Nov 16 10:47:39 2022 -0600

    groff_mdoc(7): Revise presentation of `No`.
    
    Content:
    * Rename subsection; drop "no-op" terminology; this macro assuredly
      performs an operation.
    * Recast explanation for clarity.
    * Replace example.  I don't think setting tabs illustrated anything
      interesting.  Instead show a more practical application and the effect
      of (not) prefixing an mdoc(7) macro name with the ineffable `\&`.
    
    Style:
    * Set subsection heading in sentence case.
    * Drop needless angle brackets around space-separated argument in
      synopsis.
    
    Markup:
    * Use an empty request between sentences.
    * Use two empty requests where vertical space is expected.
---
 tmac/groff_mdoc.7.man | 49 +++++++++++++++++++++++++++++++++++--------------
 1 file changed, 35 insertions(+), 14 deletions(-)

diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index f83c9570a..e07e817d9 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -2932,27 +2932,48 @@ and
 extended argument list macros are discussed below.
 .
 .
-.Ss "No-Op or Normal Text Macro"
+.Ss "Normal text macro"
 .
-The
-.Ql .No
-macro can be used in a macro command line for parameters that should
+.Ql \&No
+formats subsequent argument(s) normally,
+ending the effect of
+.Ql \&Em
+and similar.
+.
+Parsing is
 .Em not
-be formatted.
-Be careful to add
-.Ql \e&
-to the word
+suppressed,
+so you must prefix words like
 .Ql \&No
-if you really want that English word (and not the macro) as a parameter.
+with
+.Ql \e&
+to avoid their interpretation as
+.Xr mdoc
+macros.
+.
+.
 .Pp
-.Dl Usage: .No Ao argument Ac ...
+.Dl Usage: .No Ar argument No ...
+.
+.
 .Pp
-.Bl -tag -width ".Li .No\ test\ Ta\ with\ Ta\ tabs" -compact -offset 15n
-.It Li ".No test Ta with Ta tabs"
-.No test Ta with Ta tabs
+.Bl -tag -width ".Li .Em\ Use\ caution\ No\ here\ ." \
+-compact -offset 15n
+.It Li ".Em Use caution No here ."
+\[->]
+.Em Use caution No here .
+.It Li ".Em No dogs allowed ."
+\[->]
+.\" We cheat here to prevent a diagnostic warning.  We want to
+.\" illustrate output that may surprise the novice.
+.Em \&No No dogs allowed .
+.It Li ".Em \e&No dogs allowed ."
+\[->]
+.Em \&No dogs allowed .
 .El
-.Pp
 .
+.
+.Pp
 The default width is 12n.
 .
 .