[bug #61434] [man] want support for hyperlinked paragraph tags

[G. Branden Robinson]

Follow-up Comment #5, bug#61434 (group groff):

Hi Deri,

[comment #4 comment #4:]
> [comment #3 comment #3:]
> > This was an important follow-up commit.

> > commit 52a5a89c0da9f90c83441b8eb8020344a8468686
> > Author: G. Branden Robinson 
> > Date:   Thu Feb 1 23:23:45 2024 -0600
> > 
> ...
> > Unfortunately, "pdf.tmac" doesn't
> > expose a clean abstraction for "link starts here" and "link stops
here",
> > instead implementing a hugely featured `pdfhref` macro that attempts
to
> > do everything--except support bracketing the link text in a
diversion,
> > which our man(7) design requires.


> Is this accurate?

To the best of my knowledge, yes. 
[https://git.savannah.gnu.org/cgit/groff.git/commit/?id=dc265728eee39db3bf5e2f3b09f8f124880f8f05
The GNU MT/ME and UR/UE extensions date back to 2007]; MR is much more recent,
and the design of the last is deliberately closely modeled on plan9port's
macro (originally named `IM`, I think, but they renamed it to `MR` at my
request), which in turn looks very much like the `BR` and `IR` calls people
have been writing for man page cross references forever.

So the fact that `MR` is in the shape that the `pdfhref` approach expects is
largely a happy coincidence.

But it also makes sense for the other foregoing macros to work as _they_ do. 
The link text of `MR` won't sprawl due to its nature, whereas someone might
want to hyperlink an arbitrary run of text to a URL or an email address.

[https://git.savannah.gnu.org/cgit/groff.git/commit/contrib/pdfmark/pdfmark.tmac?id=f9503b9746b93a624339d488ebb29b77a4fbf667
That `pdfhref` didn't anticipate this in 2004 is unfortunate.]

> It was true before my commit d71f9264 which enabled .MT and .UR to be
hyperlinks (both of which used diversions) and provided a means to "bracket"
the resulting text as a hotspot. Maybe the mechanism of using the pipe
character to "open" the bracket needs further promulgation,

...I'm a little uneasy with that, in part because it constitutes in-band
signaling.  What if a document author wants to hyperlink a pipe sign?  This is
unlikely in conventional prose, but what if someone has a table of punctuation
glyphs, like an ASCII code chart?  Maybe each cell in the grid could hyperlink
to (a section of) a document explaining the history of the code point.

> or perhaps we should add a pair of macros to pdf.tmac, something like:-

> .de pdflinkstart
> .  ds pdf:col \\n[.m]
> .  pdfhref \\$1 -D \\$2 "|"
> ..
> .
> .de pdflinkend
> .  nop \X'pdf: markend'\m[\\*[pdf:col]]\c
> ..


> Which could be used as:-

> .pdflinkstart W http://bbc.co.uk
> .nf
> A multi
> line hotlink (possibly from a diversion)
> .fi
> .pdflinkend


> Just a thought.

I like this much better, but you might go further and have "pdflinkstart"
employ a "markstart" command so that you don't have to impute special meaning
to "|".

I think this aspect of the pdfmark API constitutes technical debt (from a
contributor who declines to work with us any longer, moreover) and I encourage
you to develop your own ideas for _groff_ support of PDF features.

Best regards,
Branden


___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #61434] [man] want support for hyperlinked paragraph tags

[Deri James]

Follow-up Comment #4, bug#61434 (group groff):

[comment #3 comment #3:]
> This was an important follow-up commit.

> commit 52a5a89c0da9f90c83441b8eb8020344a8468686
> Author: G. Branden Robinson 
> Date:   Thu Feb 1 23:23:45 2024 -0600
> 
...
> Unfortunately, "pdf.tmac" doesn't
> expose a clean abstraction for "link starts here" and "link stops
here",
> instead implementing a hugely featured `pdfhref` macro that attempts to
> do everything--except support bracketing the link text in a diversion,
> which our man(7) design requires.

Is this accurate? It was true before my commit d71f9264 which enabled .MT and
.UR to be hyperlinks (both of which used diversions) and provided a means to
"bracket" the resulting text as a hotspot. Maybe the mechanism of using the
pipe character to "open" the bracket needs further promulgation, or perhaps we
should add a pair of macros to pdf.tmac, something like:-

.de pdflinkstart
.  ds pdf:col \\n[.m]
.  pdfhref \\$1 -D \\$2 "|"
..
.
.de pdflinkend
.  nop \X'pdf: markend'\m[\\*[pdf:col]]\c
..

Which could be used as:-

.pdflinkstart W http://bbc.co.uk
.nf
A multi
line hotlink (possibly from a diversion)
.fi
.pdflinkend

Just a thought. 


___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #61434] [man] want support for hyperlinked paragraph tags

[G. Branden Robinson]

Follow-up Comment #3, bug#61434 (group groff):

This was an important follow-up commit.


commit 52a5a89c0da9f90c83441b8eb8020344a8468686
Author: G. Branden Robinson 
Date:   Thu Feb 1 23:23:45 2024 -0600

[man]: Back away from color management concerns.

Hyperlink colors in PDF were showing a tendency to get "stuck on" when
they shouldn't, and the extra difficulty of managing nested traps (`TP`
followed by `UR`, for example) is proving tricky to sort out.  On top of
that, the man(7) package historically has no cognizance of color issues
and it's doesn't seem like a good time to start, particularly if we only
do it for the 'pdf' output device.  Unfortunately, "pdf.tmac" doesn't
expose a clean abstraction for "link starts here" and "link stops here",
instead implementing a hugely featured `pdfhref` macro that attempts to
do everything--except support bracketing the link text in a diversion,
which our man(7) design requires.

* tmac/an.tmac (an-input-trap): Set stroke color to default after
  springing `TP`'s supporting trap.

  (an*begin-hyperlink, MR): Stop saving the stroke color.

  (an*end-hyperlink, MR): Stop restoring the saved stroke color.  Set it
  to the default instead after formatting the link text.




___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #61434] [man] want support for hyperlinked paragraph tags

[G. Branden Robinson]

Update of bug#61434 (group groff):

  Status: In Progress => Fixed  
 Open/Closed:Open => Closed 
 Planned Release:None => 1.24.0 

___

Follow-up Comment #2:


commit a183afb8ab45275ea09adecd3a72c8eb7feebb21
Author: G. Branden Robinson 
Date:   Thu Feb 1 21:49:10 2024 -0600

[man]: Fix Savannah #61434.

* tmac/an.tmac: Support `UR`/`UE` and `MT`/`ME` hyperlinks as paragraph
  tags.

  (an*begin-hyperlink): Kick away the guard that prevented attempts to
  do so, now that support has been refactored in underneath it.

* tmac/groff_man.7.man.in (Hyperlink macros): De-document lack of
  support for this.  Retain caveat that if the output device lacks
  hyperlink support, the hyperlink is typeset as part of the paragraph
  body rather than the tag.  I could not see any way to achieve the
  alternative given the way this package uses traps and diversions.  We
  might make a virtue of necessity by noting that paragraph tags could
  be lengthy, and URLs often will be, and it will be hella ugly to have
  the tag break.  Furthermore, if we implement automated generation of
  link anchors based on `TP` paragraph tags, not having their
  destination URLs in the tag text means we don't have to scrape them
  out later.

* tmac/tests/an_link-macros-work-in-paragraph-tags.sh: Update test
  expectations.

* NEWS: Add item.

Fixes .




___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #61434] [man] want support for hyperlinked paragraph tags

[G. Branden Robinson]

Update of bug#61434 (group groff):

  Status:None => In Progress
 Assigned to:None => gbranden   

___

Follow-up Comment #1:

I've cracked it.

It was not easy.


___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #61434] [man] want support for hyperlinked paragraph tags

[G. Branden Robinson]

URL:
  

 Summary: [man] want support for hyperlinked paragraph tags
 Project: GNU troff
Submitted by: gbranden
Submitted on: Sat 06 Nov 2021 05:44:38 AM UTC
Category: Macro - man
Severity: 1 - Wish
  Item Group: New feature
  Status: None
 Privacy: Public
 Assigned to: None
 Open/Closed: Open
 Discussion Lock: Any
 Planned Release: None

___

Details:

See bug #61425 and related commits.

This will demand diversion juggling.




___

Reply to this item at:

  

___
  Message sent via Savannah
  https://savannah.gnu.org/