[groff] 26/49: [mdoc]: Make `Sx` use quotes, not italics.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit fe7d7872093a8bc02f987458bba0b9e585f2dc91
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Nov 3 08:38:04 2022 -0500

    [mdoc]: Make `Sx` use quotes, not italics.
    
    [mdoc]: Make `Sx` macro perform quotation, not italicization.  It's
    thorougly inconsistent with English composition practices to refer to
    (sub)section titles within a document as if they were major works.
    
    * tmac/doc.tmac (Sx): Implement.
    
    * tmac/mdoc/doc-ditroff (doc-Sx-font):
    * tmac/mdoc/doc-nroff (doc-Sx-font): Delete.
    
    * tmac/groff_mdoc.7.man (Section Cross References): Rename...
      ((Sub)section cross references): ...to this.  Recognize existence of
      `Ss` macro, curiously overlooked before.
    
    * NEWS: Add item.
---
 ChangeLog             | 15 +++++++++++++++
 NEWS                  |  4 ++++
 tmac/doc.tmac         | 18 ++++++++++++++++--
 tmac/groff_mdoc.7.man | 16 +++++++++++-----
 tmac/mdoc/doc-ditroff |  1 -
 tmac/mdoc/doc-nroff   |  1 -
 6 files changed, 46 insertions(+), 9 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 41a83740b..107934ce8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2022-11-03  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [mdoc]: Make `Sx` macro perform quotation, not italicization.
+       It's thorougly inconsistent with English composition practices
+       to refer to (sub)section titles within a document as if they
+       were major works.
+
+       * tmac/doc.tmac (Sx): Implement.
+       * tmac/mdoc/doc-ditroff (doc-Sx-font):
+       * tmac/mdoc/doc-nroff (doc-Sx-font): Delete.
+       * tmac/groff_mdoc.7.man (Section Cross References): Rename...
+       ((Sub)section cross references): ...to this.  Recognize
+       existence of `Ss` macro, curiously overlooked before.
+       * NEWS: Add item.
+
 2022-11-03  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [mdoc]: Drop now-unused `doc-pageref` string.  It was nowhere
diff --git a/NEWS b/NEWS
index efd81c819..1413a49da 100644
--- a/NEWS
+++ b/NEWS
@@ -307,6 +307,10 @@ o The groff_man(7) man page documenting the groff 
implementation of the
 o The doc (mdoc) macro package now honors the `C`, `HY`, `IN`, and `SN`
   registers as the an (man) package does.
 
+o The doc (mdoc) macro package now renders man page (sub)section cross
+  references cited with the `Sx` macro by quoting them instead of
+  setting them in italics.
+
 o The e (me) macro package has changed its support for output line
   numbering with the `n1` and `n2` macros to resolve several bugs in the
   previous implementation.  The `n1` macro now accepts an optional `C`
diff --git a/tmac/doc.tmac b/tmac/doc.tmac
index 1a627e47d..b08fe5c63 100644
--- a/tmac/doc.tmac
+++ b/tmac/doc.tmac
@@ -4443,9 +4443,23 @@
 .\" NS   cross section reference
 .\" NS
 .\" NS width register 'Sx' set in doc-common
+.\"
+.\" TODO: This duplicates the definition of `Dq`; figure out how to
+.\" simply wrap that macro if possible.  (It's not trivial to do so
+.\" because of mdoc's design feature of recursively calling macro
+.\" arguments as macros.)
+.
+.eo
+.de Sx
+.  if !\n[doc-arg-count] \
+.    ds doc-macro-name Sx
+.
+.  ds doc-quote-left "\*[Lq]
+.  ds doc-quote-right "\*[Rq]
 .
-.als Sx doc-generic-macro
-.ds doc-Sx-usage section_header
+.  doc-enclose-string \$@
+..
+.ec
 .
 .
 .\" NS doc-end-column-list macro
diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index a537361f5..a97b5beee 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -2822,20 +2822,26 @@ is identical to
 .Ql .No .
 .
 .
-.Ss "Section Cross References"
+.Ss "(Sub)section cross references"
 .
-The
+Use the
 .Ql .Sx
-macro designates a reference to a section header within the same document.
+macro to cite a (sub)section heading within the given document.
+.
+.
 .Pp
-.Dl Usage: .Sx Ao section reference Ac ...
+.Dl Usage: .Sx Ao section-reference Ac ...
+.
+.
 .Pp
 .Bl -tag -width ".Li .Sx\ Files" -offset 15n
 .It Li ".Sx Files"
+.\"\[->]
 .Sx Files
 .El
-.Pp
 .
+.
+.Pp
 The default width is 16n.
 .
 .
diff --git a/tmac/mdoc/doc-ditroff b/tmac/mdoc/doc-ditroff
index c7d5620eb..f43bf84dd 100644
--- a/tmac/mdoc/doc-ditroff
+++ b/tmac/mdoc/doc-ditroff
@@ -73,7 +73,6 @@
 .ds doc-Pa-font \f[I]
 .ds doc-Sh-font \f[B]
 .ds doc-Sy-font \f[B]
-.ds doc-Sx-font \f[B]
 .ds doc-Tn-font \f[R]
 .ds doc-Va-font \f[I]
 .ds doc-Xr-font \f[I]
diff --git a/tmac/mdoc/doc-nroff b/tmac/mdoc/doc-nroff
index d292fd23b..35deab386 100644
--- a/tmac/mdoc/doc-nroff
+++ b/tmac/mdoc/doc-nroff
@@ -65,7 +65,6 @@
 .ds doc-Pa-font \f[I]
 .ds doc-Sh-font \f[B]
 .ds doc-Sy-font \f[B]
-.ds doc-Sx-font \f[I]
 .ds doc-Tn-font \f[R]
 .ds doc-Va-font \f[I]
 .ds doc-Xr-font \f[I]