deri pushed a commit to branch master in repository groff. commit d71f9264f8c187aee1161f27cda7d42c4ad7065e Author: Deri James <d...@chuzzlewit.myzen.co.uk> AuthorDate: Fri Jan 26 15:47:28 2024 +0000
.MT/.ME and .UR/.UE hyperlinking for pdf output Our documentation groff_man.7 documents that these requests are for hyperlinks. The .pdfhref W command expects the hotspot text to be passed as a parameter, but these pairs of requests enclose the required text. To solve this conundrum if the given hyperlink text to the .pdfhref request is the single pipe character "|" then mark all following text sent for output as the hotspot, terminate the hotspot on receipt of \X'pdf: markend' escape. This new facility is only available using -T pdf, not using -T ps and the pdfmark macros. Note the advice in the gropdf man page to use \X'pdf: marksuspend' and \X'pdf: markrestart' to protect any headers and footers becoming part of the hotspot in case the hyperlinked text crosses a page boundary. * tmac/an.tmac: add code to use .pdfhref W for these hyperlinks and protect against crossing page boundaries. * tmac/pdf.tmac: if the given text for a hyperlink consists of a single pipe character "|", start the hotspot and only terminate when \X'pdf: markend' is received. --- ChangeLog | 23 +++++++++++++++++++++++ tmac/an.tmac | 12 +++++++++--- tmac/pdf.tmac | 9 ++++++--- 3 files changed, 38 insertions(+), 6 deletions(-) diff --git a/ChangeLog b/ChangeLog index 7c42add2e..19d9b6a80 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,26 @@ +2024-01-26 Deri James <d...@chuzzlewit.myzen.co.uk> + + Our documentation groff_man.7 documents that these requests are + for hyperlinks. The .pdfhref W command expects the hotspot text + to be passed as a parameter, but these pairs of requests enclose + the required text. To solve this conundrum if the given + hyperlink text to the .pdfhref request is the single pipe + character "|" then mark all following text sent for output as + the hotspot, terminate the hotspot on receipt of \X'pdf: + markend' escape. This new facility is only available using -T + pdf, not using -T ps and the pdfmark macros. Note the advice in + the gropdf man page to use \X'pdf: marksuspend' and \X'pdf: + markrestart' to protect any headers and footers becoming part of + the hotspot in case the hyperlinked text crosses a page + boundary. + + * tmac/an.tmac: add code to use .pdfhref W for these hyperlinks + and protect against crossing page boundaries. + + * tmac/pdf.tmac: if the given text for a hyperlink consists of + a single pipe character "|", start the hotspot and only + terminate when \X'pdf: markend' is received. + 2024-01-25 G. Branden Robinson <g.branden.robin...@gmail.com> [troff]: Trivially refactor (trap Booleans). diff --git a/tmac/an.tmac b/tmac/an.tmac index a60eb888f..cfedbe28b 100644 --- a/tmac/an.tmac +++ b/tmac/an.tmac @@ -587,6 +587,7 @@ contains unsupported escape sequence . PT . ev . ns +. if '\\*[.T]'pdf' .pdfmarkrestart .. . .\" Schedule a page break when the next output line is written (not @@ -598,6 +599,7 @@ contains unsupported escape sequence .\" Prepare the footer for a page of the document. .de1 an-footer . if \\n[an-suppress-header-and-footer] .return +. if '\\*[.T]'pdf' .pdfmarksuspend . ev an*env-header-and-footer . ie \\n[cR] \ . ds an*ofoot "\\*[an-pageref]\" @@ -1106,6 +1108,7 @@ contains unsupported escape sequence . if (\\n[an*is-in-link-text-diversion] & \\n[an*do-hyperlink]) \{\ . \" Start diversion in a new environment. . ev an*link-text-env +. if \\n[an*is-output-pdf] \&\m[\\*[PDFHREF.TEXT.COLOUR]]\c . di an*link-text-div . ll (\\n[an*saved-line-length]u - \\n[an*saved-indentation]u) . \} @@ -1129,9 +1132,9 @@ contains unsupported escape sequence . ie \\n[dn] \{\ . if \\n[an*is-output-html] \ . nop \X^html:<a href="\\*[an*prefix]\\*[an*hyperlink]">^\c -. if \\n[an*is-output-pdf] \ -. pdfhref W -D \\*[an*prefix]\\*[an*hyperlink] -- \ -\\*[an*hyperlink]\c +. if \\n[an*is-output-pdf] \{\ +. pdfhref W -D \\*[an*prefix]\\*[an*hyperlink] -- "|" +. \} . if \\n[an*is-output-terminal] \ . nop \X^tty: link \\*[an*prefix]\\*[an*hyperlink]^\c . \" Strip off the final newline of the diversion and emit it. @@ -1142,6 +1145,8 @@ contains unsupported escape sequence . nop \X^html:</a>^\c . if \\n[an*is-output-terminal] \ . nop \X^tty: link^\c +. if \\n[an*is-output-pdf] \ +. nop \X'pdf: markend'\m[\\*[pdf:curcol]]\c . \} . \" If there was no link text, format URI as its own link text. We . \" don't add angle brackets here. @@ -1336,6 +1341,7 @@ contains unsupported escape sequence . .nr an*can-hyperlink 0 .if ( \n[an*is-output-html] \ + : \n[an*is-output-pdf] \ : \n[an*is-output-terminal]) \ . nr an*can-hyperlink 1 . diff --git a/tmac/pdf.tmac b/tmac/pdf.tmac index 68d5557e0..54175434f 100644 --- a/tmac/pdf.tmac +++ b/tmac/pdf.tmac @@ -383,7 +383,7 @@ am solely responsible for any bugs I may have introduced into this file. .\" blue components of the colour specification in the RGB colour .\" domain, which is shared by "groff" and the PDF readers. .\" -.ds PDFHREF.COLOUR 0.35 0.00 0.60 +.ds PDFHREF.COLOUR 0.00 0.35 0.60 .defcolor pdf:href.colour rgb \*[PDFHREF.COLOUR] .\" .\" "PDFHREF.TEXT.COLOUR", on the other hand, is simply defined @@ -680,6 +680,7 @@ am solely responsible for any bugs I may have introduced into this file. .\" And now, we have no further use for "pdf*href.link". .\" .rm pdf*href.link +.nr pdf:href.pipe 0 .\" .\" If the user specified any "link prefix" text, (using the "-P text" .\" option), then emit it BEFORE processing the "link text" itself. @@ -713,10 +714,12 @@ am solely responsible for any bugs I may have introduced into this file. . \" text positions. . \" \#. if dPDFHREF.COLOUR .defcolor pdf:href.colour rgb \\*[PDFHREF.COLOUR] +. ds pdf:curcol \\n[.m] . nr pdf:bm.width \\w'\\*[PDFHREF.DESC]' +. if '\\*[PDFHREF.DESC]'|' .nr pdf:href.pipe 1 . nop \&\m[\\*[PDFHREF.TEXT.COLOUR]]\c . device pdf: markstart \\n[rst] \\n[rsb] \\n[PDFHREF.LEADING] \\*[pdf:href.link] -. nop \&\\*[PDFHREF.DESC]\X'pdf: markend'\m[]\c +. if !\\n[pdf:href.pipe] .nop \&\\*[PDFHREF.DESC]\X'pdf: markend'\m[\\*[pdf:curcol]]\c . \" . \" Clean up the temporary registers and strings, used to . \" compute the "hot-spot" bounds, and format the reference, @@ -733,7 +736,7 @@ am solely responsible for any bugs I may have introduced into this file. .\" And then, if the user specified any affixed text, (using the .\" "-A text" option), we tack it on at the end. .\" -.nop \&\\*[pdf:href-A] +.if !\\n[pdf:href.pipe] .nop \&\\*[pdf:href-A] .. .\" Macro "pdf*href-I" is used for one time initialisation of special .\" "pdfhref" features; (currently, only the above page trap hook is _______________________________________________ Groff-commit mailing list Groff-commit@gnu.org https://lists.gnu.org/mailman/listinfo/groff-commit