[groff] 31/40: [man]: Trivially refactor.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 126b223312dab2f5abfb7eb82f766e1865fdd63f
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Nov 11 17:31:00 2022 -0600

    [man]: Trivially refactor.
    
    * tmac/an.tmac: Trivially refactor for congruence with documentary
      terminology.  Rename strings and macros.
      - an-title                 -> an*topic
      - an-abbreviate-page-title -> an*abbreviate-page-topic
      - an-title-abbv            -> an*topic-abbv
      - an-title-string          -> an*topic-string
      - an-title-length          -> an*topic-length
      - an-title-length-prev     -> an*topic-length-prev
      - an-title-new-length      -> an*topic-new-length
      - an-page-title-style      -> an*topic-style
    
      (TH): Recast diagnostic message to refer to "section", not "volume"
      title.
---
 ChangeLog        | 15 +++++++++++
 tmac/an-ext.tmac |  2 +-
 tmac/an.tmac     | 78 ++++++++++++++++++++++++++++----------------------------
 3 files changed, 55 insertions(+), 40 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index fed930f8e..e65453993 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2022-11-11  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * tmac/an.tmac: Trivially refactor for congruence with
+       documentary terminology.  Rename strings and macros.
+       - an-title                 -> an*topic
+       - an-abbreviate-page-title -> an*abbreviate-page-topic
+       - an-title-abbv            -> an*topic-abbv
+       - an-title-string          -> an*topic-string
+       - an-title-length          -> an*topic-length
+       - an-title-length-prev     -> an*topic-length-prev
+       - an-title-new-length      -> an*topic-new-length
+       - an-page-title-style      -> an*topic-style
+       (TH): Recast diagnostic message to refer to "section", not
+       "volume" title.
+
 2022-11-11  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/an-ext.tmac: Refactor to reduce code size.  `UR` and `MT`
diff --git a/tmac/an-ext.tmac b/tmac/an-ext.tmac
index 0fb4cd7a7..e2f5c48f9 100644
--- a/tmac/an-ext.tmac
+++ b/tmac/an-ext.tmac
@@ -216,7 +216,7 @@
 .
 .
 .\" Set a man page cross reference.
-.\" .MR page-title page-section [trailing-text]
+.\" .MR page-topic page-section [trailing-text]
 .if \n(.g .ig
 .de MR
 .  nh
diff --git a/tmac/an.tmac b/tmac/an.tmac
index 401ab45a7..1d6e484cf 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -204,7 +204,7 @@
 ..
 .
 .\" Begin man page.
-.\" .TH title section[ extra1[ extra2[ extra3]]]
+.\" .TH topic section[ extra1[ extra2[ extra3]]]
 .de1 TH
 .  if ((\\n[.$] < 2) : (\\n[.$] > 5)) \
 .    an-style-warn .\\$0 expects 2 to 5 arguments, got \\n[.$]
@@ -276,8 +276,8 @@
 .  nr an-is-in-diversion 0
 .  nr an*is-in-example 0
 .
-.  ds an-title "\\$1\"
-.  if \\n[CT] .stringup an-title
+.  ds an*topic "\\$1\"
+.  if \\n[CT] .stringup an*topic
 .  ds an-section "\\$2\"
 .  ie (\\n[.$] > 4) .ds an-extra3 "\\$5\"
 .  el \{\
@@ -316,7 +316,7 @@
 .
 .  if '\\$5\\*[an-extra3]'' \{\
 .    ds an-msg .\\$0 missing fifth argument and second argument '\\$2'\"
-.    as an-msg " not a recognized manual section; specify volume title\"
+.    as an-msg " not a recognized manual section; specify its title\"
 .    an-style-warn \\*[an-msg]
 .    rm an-msg
 .  \}
@@ -326,15 +326,15 @@
 .  ps \\n[PS]u
 .  vs \\n[VS]u
 .  lt \\n[LT]u
-.  an*abbreviate-page-title
+.  an*abbreviate-page-topic
 .  \" If AT or UC is called, we will need to abbreviate again.
 .  an*abbreviate-inner-footer
 .  ev
 .
-.  \" HTML gets the title without any abbreviation, since it's metadata.
+.  \" HTML gets the topic without any abbreviation, since it's metadata.
 .  if \\n[an-is-output-html] \{\
 .    DEVTAG-TL
-.    nop \\*[an-title]
+.    nop \\*[an*topic]
 .    DEVTAG-EO-TL
 .  \}
 .
@@ -436,53 +436,53 @@
 .    tl '\\*[an*ifoot]'\\*[an-extra1]'\\*[an*ofoot]'
 ..
 .
-.\" Abbreviate the page title if it's too long for the header.  Leaves
+.\" Abbreviate the page topic if it's too long for the header.  Leaves
 .\" string an-pageref defined for use in .PT and .an-footer.  Also
-.\" leaves an-title-abbv for possible use by .PT and .BT re-definers.
+.\" leaves an*topic-abbv for possible use by .PT and .BT re-definers.
 .\" Call this only from within the header/footer environment.
-.de an*abbreviate-page-title
-.  ds an-title-abbv \\*[an-title]\" might not get abbreviated at all
-.  ds an-title-string \\*[an-title]\"
+.de an*abbreviate-page-topic
+.  ds an*topic-abbv \\*[an*topic]\" might not get abbreviated at all
+.  ds an*topic-string \\*[an*topic]\"
 .  ds an-ellipsis \|.\|.\|.\|\"
 .  \" an*page-ref-string is left unmodified for internal use, such as
 .  \" PDF bookmarks.
-.  ds an*page-ref-string \\*[an-title](\\*[an-section])\"
-.  ds an-pageref \\*[an-title-abbv](\\*[an-section])\"
+.  ds an*page-ref-string \\*[an*topic](\\*[an-section])\"
+.  ds an-pageref \\*[an*topic-abbv](\\*[an-section])\"
 .  nr an-header-width \\w'\\*[an-pageref]\\*[an-extra3]\\*[an-pageref]'
 .  while (\\n[an-header-width] >= \\n[.lt]) \{\
-.    \" The page title is too long; trim some bits out of the middle.
-.    length an-title-length \\*[an-title-string]
+.    \" The page topic is too long; trim some bits out of the middle.
+.    length an*topic-length \\*[an*topic-string]
 .    \" roff division rounds integers toward zero.  Remove an additional
 .    \" character on each side of the midpoint to account for the
 .    \" ellipsis we add later.
-.    nr an-mark1 (\\n[an-title-length] / 2 - 2)
-.    nr an-mark2 (\\n[an-title-length] / 2 + 2)
-.    ds an-prefix \\*[an-title-string]\"
-.    ds an-suffix \\*[an-title-string]\"
+.    nr an-mark1 (\\n[an*topic-length] / 2 - 2)
+.    nr an-mark2 (\\n[an*topic-length] / 2 + 2)
+.    ds an-prefix \\*[an*topic-string]\"
+.    ds an-suffix \\*[an*topic-string]\"
 .    \" Use extremum operators to ensure that the first and last
-.    \" characters of the title remain intact (in cases of pathological
+.    \" characters of the topic remain intact (in cases of pathological
 .    \" shortening).
 .    substring an-prefix 0 (\\n[an-mark1] >? 1)
-.    substring an-suffix (\\n[an-mark2] <? \\n[an-title-length] - 1) -1
-.    ds an-title-string \\*[an-prefix]\\*[an-suffix]\"
-.    ds an-title-abbv \\*[an-prefix]\\*[an-ellipsis]\\*[an-suffix]\"
-.    \" Remeasure the formatted title; give up if we made no progress.
-.    length an-title-new-length \\*[an-title-string]
-.    ie (\\n[an-title-new-length] >= \\n[an-title-length]) \
+.    substring an-suffix (\\n[an-mark2] <? \\n[an*topic-length] - 1) -1
+.    ds an*topic-string \\*[an-prefix]\\*[an-suffix]\"
+.    ds an*topic-abbv \\*[an-prefix]\\*[an-ellipsis]\\*[an-suffix]\"
+.    \" Remeasure the formatted topic; give up if we made no progress.
+.    length an*topic-new-length \\*[an*topic-string]
+.    ie (\\n[an*topic-new-length] >= \\n[an*topic-length]) \
 .      break
-.    ds an-pageref \\*[an-title-abbv](\\*[an-section])\"
+.    ds an-pageref \\*[an*topic-abbv](\\*[an-section])\"
 .    nr an-header-width \
        \\w'\\*[an-pageref]\\*[an-extra3]\\*[an-pageref]'
 .  \}
-.  ds an-pageref \\*[an-lic]\f[\\*[MF]]\\*[an-title-abbv]\\*[an-ic]\
+.  ds an-pageref \\*[an-lic]\f[\\*[MF]]\\*[an*topic-abbv]\\*[an-ic]\
 \f[R](\\*[an-section])\"
-.  rr an-title-length-prev
+.  rr an*topic-length-prev
 .  rr an-mark1
 .  rr an-mark2
 .  rm an-prefix
 .  rm an-suffix
-.  rm an-title-string
-.  rr an-title-length
+.  rm an*topic-string
+.  rr an*topic-length
 .  rr an-header-width
 .  rm an-ellipsis
 ..
@@ -1043,7 +1043,7 @@ contains unsupported escape sequence
 ..
 .
 .\" Set a man page cross reference.
-.\" .MR page-title page-section [trailing-text]
+.\" .MR page-topic page-section [trailing-text]
 .de1 MR
 .  if ((\\n[.$] < 2) : (\\n[.$] > 3)) \
 .    an-style-warn .\\$0 expects 2 or 3 arguments, got \\n[.$]
@@ -1221,7 +1221,7 @@ contains unsupported escape sequence
 .if !r CS \
 .  nr CS 0
 .
-.\" full capitalization of page title
+.\" full capitalization of page topic
 .if !r CT \
 .  nr CT 0
 .
@@ -1372,7 +1372,7 @@ contains unsupported escape sequence
 .rr an-HF-length
 .rm an-heading-style
 .
-.\" man page title font
+.\" man page topic font
 .if !d MF \
 .  ds MF I\"
 .
@@ -1380,13 +1380,13 @@ contains unsupported escape sequence
 .\" is an oblique style, append the corrections.
 .ds an-lic \" left italic correction
 .ds an-ic \" italic correction
-.ds an-page-title-style \*[MF]\"
-.substring an-page-title-style -1 -1
-.if '\*[an-page-title-style]'I' \{\
+.ds an*topic-style \*[MF]\"
+.substring an*topic-style -1 -1
+.if '\*[an*topic-style]'I' \{\
 .  as an-lic \,\"
 .  as an-ic \/\"
 .\}
-.rm an-page-title-style
+.rm an*topic-style
 .
 .if \n[cR] \
 .  an-set-up-continuous-rendering