[groff] 36/38: [mdoc]: Simplify `Ql` macro behavior.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 855fa0c3f36f2a7df8a020aa84297192ed9606b2
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Mar 24 01:48:31 2024 -0500

    [mdoc]: Simplify `Ql` macro behavior.
    
    * tmac/mdoc/doc-ditroff (Ql): Rip out most of the logic (counting and
      measuring arguments), replacing it with a save and restore of the font
      family to temporarily use the Courier family.  The new behavior is:
      when formatting for terminals, `Ql`'s arguments are quoted; when
      formatting for typesetters, its arguments are set in Courier.  In
      practice, it does not seem difficult to distinguish even single
      characters in Courier from those in Times.  (If it is, an _explicit_
      quoting macro like `Sq` or `Dq` should be used.)
    
    * tmac/groff_mdoc.7.man (Enclosure and Quoting Macros) <Ql>:
    * NEWS: Document this.
    
    See, e.g., <https://savannah.gnu.org/bugs/index.php?61276>.
    
    Also tighten wording and favor active voice over passive.
---
 ChangeLog             | 18 +++++++++++++++++
 NEWS                  |  6 ++++++
 tmac/groff_mdoc.7.man | 20 +++++++++----------
 tmac/mdoc/doc-ditroff | 53 +++++----------------------------------------------
 4 files changed, 39 insertions(+), 58 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 6c7fccca5..592861b41 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,21 @@
+2024-03-24  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [mdoc]: Simplify `Ql` macro behavior.
+
+       * tmac/mdoc/doc-ditroff (Ql): Rip out most of the logic
+       {counting and measuring arguments}, replacing it with a save and
+       restore of the font family to temporarily use the Courier
+       family.  The new behavior is: when formatting for terminals,
+       `Ql`'s arguments are quoted; when formatting for typesetters,
+       its arguments are set in Courier.  In practice, it does not seem
+       difficult to distinguish even single characters in Courier from
+       those in Times.  (If it is, an _explicit_ quoting macro like
+       `Sq` or `Dq` should be used.)
+       * tmac/groff_mdoc.7.man (Enclosure and Quoting Macros) <Ql>:
+       * NEWS: Document this.
+
+       See, e.g., <https://savannah.gnu.org/bugs/index.php?61276>.
+
 2024-03-24  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/mdoc/doc-ditroff (Dl): Refactor.  Instead of using the
diff --git a/NEWS b/NEWS
index 28ba61bc7..062ac5cfb 100644
--- a/NEWS
+++ b/NEWS
@@ -194,6 +194,12 @@ o The doc (mdoc) macro package now performs font family 
switches
   customize the font used to render nearly any mdoc(7) macro; this
   mechanism has been in place since 1992.
 
+o The doc (mdoc) macro package's `Ql` macro now operates more simply; it
+  no longer (ever) quotes its arguments when formatting for typesetters.
+  In practice, it does not seem difficult to distinguish even single
+  characters in Courier from those in Times.  (If it is, an _explicit_
+  quoting macro like `Sq` or `Dq` should be used.)
+
 o The doc (mdoc) macro package's `Lk`, `Mt`, and `Xr` macros now produce
   hyperlinks on HTML, PDF, and terminal devices.  See above regarding
   hyperlink support being enabled by default.
diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index e637f31a9..390a61c80 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -2878,7 +2878,8 @@ Quote     Open    Close   Function        Result
 \&.Dq  .Do     .Dc     Double Quote    \[lq]string\[rq]
 \&.Eq  .Eo     .Ec     Enclose String (in XY)  XstringY
 \&.Pq  .Po     .Pc     Parenthesis Enclosure   (string)
-\&.Ql                  Quoted Literal  \[lq]string\[rq] or string
+\&.Ql                  Quoted or Literal       \[lq]string\[rq] or \
+\f[CR]string\f[]
 \&.Qq  .Qo     .Qc     Straight Double Quote   "string"
 \&.Sq  .So     .Sc     Single Quote    \[oq]string\[cq]
 .TE
@@ -2912,24 +2913,23 @@ The default width value is 12n for both macros.
 .It Li .Eq
 The first and second arguments of this macro are the opening and
 closing strings respectively, followed by the arguments to be enclosed.
+.
 .It Li .Ql
-The quoted literal macro behaves differently in
+The quoted-or-literal macro behaves differently in
 .Xr troff \" mode
 and
 .Xr nroff \" mode
 modes.
 .
-If formatted with
+When formatting with
 .Xr @g@nroff @MAN1EXT@ ,
-a quoted literal is always quoted.
+.Xr mdoc
+quotes the arguments.
 .
-If formatted with
+With
 .Xr @g@troff ,
-an item is only quoted if the width of the item is less than three
-constant-width characters.
-.
-This is to make short strings more visible where the font change to
-literal (constant-width) is less noticeable.
+.Xr mdoc
+sets them in a constant-width font.
 .
 .
 .Pp
diff --git a/tmac/mdoc/doc-ditroff b/tmac/mdoc/doc-ditroff
index 83b3629bd..30a7a2f54 100644
--- a/tmac/mdoc/doc-ditroff
+++ b/tmac/mdoc/doc-ditroff
@@ -237,19 +237,12 @@
 .\" NS   quoted literal define
 .\" NS
 .\" NS modifies:
-.\" NS   doc-argXXX
-.\" NS   doc-arg-count
-.\" NS   doc-arg-ptr
 .\" NS   doc-macro-name
-.\" NS   doc-spaceXXX
-.\" NS   doc-typeXXX
 .\" NS   doc-quote-left
 .\" NS   doc-quote-right
 .\" NS
 .\" NS local variables:
-.\" NS   doc-reg-Ql
-.\" NS   doc-reg-Ql1
-.\" NS   doc-reg-Ql2
+.\" NS   doc-saved-family-Ql
 .\" NS
 .\" NS width register 'Ql' set in doc-common
 .
@@ -264,48 +257,12 @@
 .      doc-report-usage .Ql argument ...
 .  \}
 .
-.  nr doc-reg-Ql (\n[doc-arg-ptr] + 1)
-.  doc-get-arg-width \n[doc-reg-Ql]
-.
-.  \" don't use quotes if we have more than two succeeding string
-.  \" arguments
-.  nr doc-reg-Ql +1
-.  if (\n[doc-arg-count] >= \n[doc-reg-Ql]) \
-.    if (\n[doc-type\n[doc-reg-Ql]] == 2) \
-.      nr doc-width 3
+.    ds doc-saved-family-Ql \n[.fam]
 .
-.  \" make a difference in quotation style for strings longer
-.  \" than two characters
-.  ie (\n[doc-width] > 2) \
-.    Li
-.  el \{\
-.    ie \n[doc-arg-ptr] \{\
-.      \" we replace 'Ql' with 'Li'
-.      ds doc-arg\n[doc-arg-ptr] Li
-.      nr doc-arg-ptr -1
-.    \}
-.    el \{\
-.      \" if .Ql has been called directly, we must shift all elements in
-.      \" the argument vector to the right so that we can insert 'Li'
-.      nr doc-reg-Ql \n[doc-arg-count]
-.      nr doc-reg-Ql1 (\n[doc-arg-count] + 1)
-.      while \n[doc-reg-Ql] \{\
-.        rn doc-arg\n[doc-reg-Ql] doc-arg\n[doc-reg-Ql1]
-.        rnn doc-type\n[doc-reg-Ql] doc-type\n[doc-reg-Ql1]
-.        rn doc-space\n[doc-reg-Ql] doc-space\n[doc-reg-Ql1]
-.        nr doc-reg-Ql -1
-.        nr doc-reg-Ql1 -1
-.      \}
-.      ds doc-arg1 Li
-.      nr doc-type1 1
-.      ds doc-space1
-.      nr doc-arg-count +1
-.    \}
+.    ds doc-quote-left \F[C]
+.    ds doc-quote-right \F[\*[doc-saved-family-Ql]]
 .
-.    ds doc-quote-left "\*[doc-left-singlequote]
-.    ds doc-quote-right "\*[doc-right-singlequote]
-.    doc-enclose-string
-.  \}
+.    doc-enclose-string \$@
 ..
 .ec
 .