[groff] 01/04: Link footnote reference marks to footnote text.

[Keith Marshall]

keithmarshall pushed a commit to branch master
in repository groff.

commit e21e3d408f937aa0617518503010940976f4095f
Author: Keith Marshall <keith.d.marshall@ntlworld.com>
AuthorDate: Sat Oct 2 12:18:05 2021 +0100

    Link footnote reference marks to footnote text.
    
    * pdfmark.ms (FP): Redefine locally; replace s.tmac default.
    (FF): Do not redefine; our FP replacement macro does not use it.
    [d FS-MARK] (FS-MARK): Redefine locally; map it to...
    (pdf:fn.mark): ...this locally defined macro.
    [!d FS-MARK] (@FS): Rename s.tmac implementation as...
    (pdf:fn.record): ...this, then redefine @FS itself, to call...
    (pdf:fn.mark, pdf:fn.record): ...these, in respective order.
    (groff-1.19.1, GhostScript-8.14): Update footnote reference syntax.
    (Ghostscript-8.14, MSYS): Emulate sentence space after footnote mark.
    (*): Replace s.tmac string definition; make it equivalent to "\c",
    after renaming its original implementation as...
    (pdf:fn.index): ...this; synchronize references with changes to...
    (pdf:fn.index.count): ...this new locally defined register; it is
    auto-incremented by one, as each footnote is placed.
---
 contrib/pdfmark/ChangeLog  | 19 ++++++++++++
 contrib/pdfmark/pdfmark.ms | 73 +++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 84 insertions(+), 8 deletions(-)

diff --git a/contrib/pdfmark/ChangeLog b/contrib/pdfmark/ChangeLog
index 04aa39b..1e1479b 100644
--- a/contrib/pdfmark/ChangeLog
+++ b/contrib/pdfmark/ChangeLog
@@ -1,3 +1,22 @@
+2021-10-02  Keith Marshall  <keith.d.marshall@ntlworld.com>
+
+       Link footnote reference marks to footnote text.
+
+       * pdfmark.ms (FP): Redefine locally; replace s.tmac default.
+       (FF): Do not redefine; our FP replacement macro does not use it.
+       [d FS-MARK] (FS-MARK): Redefine locally; map it to...
+       (pdf:fn.mark): ...this locally defined macro.
+       [!d FS-MARK] (@FS): Rename s.tmac implementation as...
+       (pdf:fn.record): ...this, then redefine @FS itself, to call...
+       (pdf:fn.mark, pdf:fn.record): ...these, in respective order.
+       (groff-1.19.1, GhostScript-8.14): Update footnote reference syntax.
+       (Ghostscript-8.14, MSYS): Emulate sentence space after footnote mark.
+       (*): Replace s.tmac string definition; make it equivalent to "\c",
+       after renaming its original implementation as...
+       (pdf:fn.index): ...this; synchronize references with changes to...
+       (pdf:fn.index.count): ...this new locally defined register; it is
+       auto-incremented by one, as each footnote is placed.
+
 2021-10-01  Keith Marshall  <keith.d.marshall@ntlworld.com>
 
        Incorporate user-defined TOC leader style.
diff --git a/contrib/pdfmark/pdfmark.ms b/contrib/pdfmark/pdfmark.ms
index a4cc052..a7c0ea9 100644
--- a/contrib/pdfmark/pdfmark.ms
+++ b/contrib/pdfmark/pdfmark.ms
@@ -78,9 +78,8 @@ Publishing with GNU Troff
 .nr PO  2.5c
 .nr LL 17.0c
 .nr LT 17.0c
-.nr HY  0
-.nr FF  3
 .nr DI  5n
+.nr HY  0
 .
 .\" Within the table of contents, the width of the right-hand margin,
 .\" in which space is reserved for the display of page numbers, and the
@@ -95,6 +94,66 @@ Publishing with GNU Troff
 .nr GROWPS 4
 .nr PSINCR 1.5p
 .
+.
+.\" Implement an interface with the FS macro (from s.tmac) to facilitate
+.\" placement of footnote reference marks, with each serving as an active
+.\" pdfhref link to the associated footnote itself.
+.\"
+.de pdf:fn.mark nr
+.\" Macro to replace original duty performed by "\**"; must be invoked
+.\" at point of footnote mark placement, e.g. by FS, BEFORE recording of
+.\" the associated text within the footnote diversion is commenced.
+.\"
+.ie \\n[.$] \{\
+.   pdfhref L -D pdf:fn\\$1 -- \\$2
+.   pdfhref M -N pdf:fn\\$1r
+.   \}
+.\"
+.\" s.tmac does not publicly expose its auto-incrementing footnote index;
+.\" to avoid a dependency on an undocumented internal feature, we create
+.\" our own counter, while keeping the internal index synchronized, by
+.\" interpolating a renamed "\**", each time we increment our counter.
+.\"
+.el .\\$0 \\n+[pdf:fn.index.count] \\*[pdf:fn.index]
+.nr pdf:fn.index.count 0 1
+.rn * pdf:fn.index
+.ds * \c
+.
+.\" For versions of s.tmac which support the FS-MARK callback hook, it
+.\" is sufficient for us to answer the callback request.
+.\"
+.\" FIXME: in time, we may be able to unconditionally assume that this
+.\" callback hook will be supported...
+.\"
+.ie d FS-MARK .als FS-MARK pdf:fn.mark
+.el \{\
+.\" ...but in the interim, we may need to redefine s.tmac's FS macro,
+.\" (actually the @FS internal macro, rather than FS itself), to gain
+.\" an effect equivalent to taking control of FS-MARK, to achieve the
+.\" placement of a footnote mark as an active pdfhref link.
+.\"
+.rn @FS pdf:fn.record
+.de @FS
+.pdf:fn.mark
+.pdf:fn.record
+..
+.\}
+.\" Override s.tmac's (undocumented) footnote output hook; this emulates
+.\" the default output style for \n[FF] == 3 footnotes, with the footnote
+.\" number formatted as a pdfhref link back to the position at which the
+.\" footnote marker appears, within the document text.
+.\"
+.de FP
+.LP
+.nr pdf:fn.tag.width (u;2*\\n[FI])
+.ds pdf:fn.tag \s'-1.5p'\\$1.\s'+1.5p'
+.pdfhref M -N pdf:fn\\$1
+.in +\\n[pdf:fn.tag.width]u
+.ti -\\n[pdf:fn.tag.width]u
+.nr pdf:fn.tag.width -\\w'\\*[pdf:fn.tag]'u
+.pdfhref L -D pdf:fn\\$1r -A \\h'\\n[pdf:fn.tag.width]u'\c -- \\*[pdf:fn.tag]
+..
+.
 .\" Define a local macro to facilitate choice of style for emphasis;
 .\" by default, make it equivalent to the ms standard "I" macro.
 .\"
@@ -334,10 +393,8 @@ All of the techniques described have been tested on
 .EM both
 GNU/Linux, and on \*[Microsoft] Windows\(tm2000 operating platforms, using
 .CW groff
-.CW 1.19.1 ,\c
-.pdfhref L -D footnote1 -- \**
+.CW 1.19.1 ,\**
 .FS
-.pdfhref M footnote1
 Later versions should, and some earlier versions may, be equally suitable.
 See
 .pdfhref W \*[GROFF-WEBSITE]
@@ -346,15 +403,14 @@ for information and availability of the latest version.
 in association with
 .CW AFPL
 .CW GhostScript
-.CW 8.14 .\c
-.pdfhref L -D footnote2 -- \**
+.CW 8.14 .\**
 .FS
-.pdfhref M footnote2
 Again, other versions may be suitable.
 See
 .pdfhref W http://ghostscript.com
 for information and availability.
 .FE
+\&
 Other tools employed, which should be readily available on
 .EM any
 Unix\(tm
@@ -401,6 +457,7 @@ include those tools listed above,
 and is the package which was actually used when performing the Windows\(tm2000
 platform tests referred to in the text.
 .FE
+\&
 This list is by no means exhaustive, and should in no way be construed as an
 endorsement of any of these packages, nor to imply that other similar packages,
 which may be available, are in any way inferior to them.