bugGNU roff - Bugs: bug #61434, [man] want support for hyperlinked...

 
 

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

Submitter:  G. Branden Robinson <gbranden>
Submitted:  Sat 06 Nov 2021 05:44:38 AM UTC
   
 
Category:  Macro man Severity:  1 - Wish
Item Group:  Feature change Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.24.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Fri 02 Feb 2024 06:47:59 PM UTC, comment #5: 

Hi Deri,

comment #4:

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


> > commit 52a5a89c0da9f90c83441b8eb8020344a8468686
> > Author: G. Branden Robinson <g.branden.robinson@gmail.com>
> > 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.  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.

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

G. Branden Robinson <gbranden>
Group administrator
Fri 02 Feb 2024 03:00:14 PM UTC, comment #4: 

comment #3:

> This was an important follow-up commit.


> commit 52a5a89c0da9f90c83441b8eb8020344a8468686
> Author: G. Branden Robinson <g.branden.robinson@gmail.com>
> 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.

Deri James <deri>
Group Member
Fri 02 Feb 2024 08:56:04 AM UTC, comment #3: 

This was an important follow-up commit.


commit 52a5a89c0da9f90c83441b8eb8020344a8468686
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
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.


G. Branden Robinson <gbranden>
Group administrator
Fri 02 Feb 2024 04:49:30 AM UTC, comment #2: 


commit a183afb8ab45275ea09adecd3a72c8eb7feebb21
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
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 <https://savannah.gnu.org/bugs/?61434>.


G. Branden Robinson <gbranden>
Group administrator
Fri 02 Feb 2024 03:35:05 AM UTC, comment #1: 

I've cracked it.

It was not easy.

G. Branden Robinson <gbranden>
Group administrator
Sat 06 Nov 2021 05:44:38 AM UTC, original submission:  

See bug #61425 and related commits.

This will demand diversion juggling.

G. Branden Robinson <gbranden>
Group administrator

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by deri (Posted a comment)
  • -email is unavailable- added by gbranden (known to be interested)
  • -email is unavailable- added by gbranden (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 6 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2024-02-02 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.24.0
    2024-02-02 gbranden Carbon-Copy- Added -email is unavailable-
    2024-02-02 gbranden StatusNone In Progress
        Assigned toNone gbranden

    Back to the top

    Powered by Savane 3.13-4448.
    Corresponding source code