[groff] 01/02: [ms]: Support user-defined TOC leader style.

[Keith Marshall]

keithmarshall pushed a commit to branch master
in repository groff.

commit 3f916952393d5779f5e2acd49f9f1af908217d79
Author: Keith Marshall <keith.d.marshall@ntlworld.com>
AuthorDate: Fri Oct 1 10:25:49 2021 +0100

    [ms]: Support user-defined TOC leader style.
    
    * tmac/s.tmac (toc*leader-char): Rename it as...
    (TC-LEADER): ...this; within PX, leave it unchanged, if predefined.
    (TC-MARGIN): New numeric register; if predefined, leave it unchanged,
    otherwise define as \w'000'; use it instead of hard-wired definition,
    within PX; cf. <https://savannah.gnu.org/bugs/?61157>.
    
    * tmac/groff_ms.7.man (TC_LEADER, TC_MARGIN): Document them.
---
 ChangeLog           | 12 ++++++++++++
 tmac/groff_ms.7.man | 50 +++++++++++++++++++++++++++++++++++++++++++++++++-
 tmac/s.tmac         |  7 ++++---
 3 files changed, 65 insertions(+), 4 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 8d9aac8..84c4f3f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2021-10-01  Keith Marshall  <keith.d.marshall@ntlworld.com>
+
+       [ms]: Support user-defined TOC leader style.
+
+       * tmac/s.tmac (toc*leader-char): Rename it as...
+       (TC-LEADER): ...this; within PX, leave it unchanged, if predefined.
+       (TC-MARGIN): New numeric register; if predefined, leave it unchanged,
+       otherwise define as \w'000'; use it instead of hard-wired definition,
+       within PX; cf. <https://savannah.gnu.org/bugs/?61157>.
+
+       * tmac/groff_ms.7.man (TC_LEADER, TC_MARGIN): Document them.
+
 2021-09-28  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [pic]: Update input file name correctly.
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 2dcb21c..45125ff 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -321,6 +321,10 @@ Other settings
 Parameter      Definition      Effective       Default
 _
 \[rs]n[MINGW]  Minimum gutter width    next page       2n
+\[rs]n[TC_MARGIN]      TOC page number margin width    next PX call\
+       \[rs]w'000'
+\[rs][TC_LEADER]       TOC leader character    next PX call\
+       .\[rs]h'1m'
 _
 .TE
 .
@@ -344,6 +348,20 @@ The \[lq]gutter\[rq] affected by
 .B \[rs]n[MINGW]
 is the gap between columns in multiple-column page arrangements.
 .
+The
+.B TC_MARGIN
+register,
+and the
+.B TC_LEADER
+special character,
+take effect when printing any table of contents,
+which has been assembled using the
+.BR XS ,
+.BR XA ,
+and
+.B XE
+macros.
+.
 .
 .\" ====================================================================
 .SS "Fractional point sizes"
@@ -1734,7 +1752,14 @@ Use the
 macro to print the table of contents at the end of the document,
 resetting the page number to\~\c
 .B i
-(Roman numeral\~1).
+(Roman numeral\~1);
+(note that the
+.B TC
+macro ultimately calls the
+.B PX
+macro,
+to print the table of contents,
+after resetting the page number).
 .
 .
 .P
@@ -1765,6 +1790,29 @@ specified by the
 .B \[rs]*[TOC]
 string.
 .
+.P
+You may control the style of the leaders,
+which extend each table of contents entry to fill the output line,
+to the beginning of the right side page margin field
+in which the page number is printed,
+by defining the
+.B TC_LEADER
+special character,
+(typically a combination of the
+.RB \[lq] . \[rq]
+glyph,
+and a specification for any space which is desired
+between adjacent leader dots).
+.
+.P
+You may adjust the width of the right-aligned page margin field,
+in which the page number is printed,
+(and which effectively increases
+the width of the right side page margin),
+by setting the
+.B TC_MARGIN
+register.
+.
 .
 .\" ====================================================================
 .SH "Differences from AT&T \f[I]ms\f[]"
diff --git a/tmac/s.tmac b/tmac/s.tmac
index 5ebc504..7bdbfdd 100644
--- a/tmac/s.tmac
+++ b/tmac/s.tmac
@@ -1751,9 +1751,10 @@ along with this program.  If not, see 
<http://www.gnu.org/licenses/>.
 .      ps
 .\}
 .nf
-.char \[toc*leader-char] .\h'1m'
-.lc \[toc*leader-char]
-.ta (u;\\n[.l]-\\n[.i]-\w'000') (u;\\n[.l]-\\n[.i])R
+.if !r TC-MARGIN .nr TC-MARGIN \w'000'
+.if !c \[TC-LEADER] .char \[TC-LEADER] .\h'1m'
+.ta (u;\\n[.l]-\\n[.i]-\\n[TC-MARGIN]) (u;\\n[.l]-\\n[.i])R
+.lc \[TC-LEADER]
 .sp 2
 .toc*div
 .par@reset