Re: We have OSC 8 terminal hyperlink support now

[Alejandro Colomar (man-pages)]

Hi, Brandem!

On 10/6/21 2:53 PM, G. Branden Robinson wrote:
> Hi, Alex!
>
> At 2021-10-02T20:08:03+0200, Alejandro Colomar (man-pages) wrote:
> > On 10/2/21 7:45 PM, G. Branden Robinson wrote:
> > > > > There is the question of what to do if a man page cross
> > > > > reference is ambiguous,
> >
> > Nothing, IMO.
> >
> > Even if the man page cross reference is invalid (maybe an uninstalled
> > page).
>
> Okay.  I've been trying (so far without success) to imagine how we might
> improve the experience of man page lookup now that we have this
> supplementary communications channel open to us.
>
> > > $ printf 'Read \033]8;;man:grotty(1)\033\\grotty(1)\033]8;;\033\\!\n'
> >
> > Hmm, the XFCE terminal just printed plain text.  However, I installed
> > gnome-terminal, and it even opened the man page in pdf!  Wow!
>
> For me, it didn't produce PDF, but you could be forgiven for thinking so
> at first glance thanks to variations in type size among other things.
> It appears that the GNOME help application (yelp?) is taking grotty(1)'s

Ahh yep, it was yelp(1).

> output and putting seasoning on it, using the SGR escape sequences in
> part and, I surmise, some assumptions about man page structure, to draw
> other structural inferences.  I'm reasonably confident about this
> because (1) if you view the groff_char(7) man page this way, you can see
> the page disclosing "utf8" as the output driver in running text, and (2)
> this is a well-trodden approach that has been taken by others, include
> Michael Kerrisk's own HTML man page converter that he uses on man7.org
> (and which I would dearly like to get my hands on so I can suggest
> improvements--but when last I asked him, he seemed shy of sharing it).
>
> We don't have PDF URL support hooked into the MR macro yet, but I want
> it.  I would be dead chuffed to see terminals launching evince(1) or
> some other PDF viewer to browse man pages in.[1]

I'm not sure I know what you have in mind, but maybe a derivative of the 
pdfman() function we have in <scripts/bash_aliases> in the man-pages 
repo would do that.

The current implementation is:

function pdfman()
{
        if (($# != 1)); then
                >&2 echo "Usage: ${FUNCNAME[0]} <man-page.n>";
                return ${EX_USAGE};
        fi;

        local tmp="$(mktemp -t "${1##*/}.XXXXXX")";

        <${1} \
        man -Tps -l - \
        |ps2pdf - - \
        >${tmp};
        xdg-open ${tmp};
}

But that opens man pages by filename, not by page name and section. 
With some small simplification it could do that:

function pdfman()
{
        if (($# == 0)); then
                >&2 echo "Usage: ${FUNCNAME[0]} [man options] [[section] page ...] 
...";
                return ${EX_USAGE};
        fi;

        local tmp="$(mktemp -t "${1##*/}.XXXXXX")";

        man -Tps $@ \
        | ps2pdf - - \
        > ${tmp};
        xdg-open ${tmp};
}

Is this close enough to a terminal opening a man page in your PDF reader 
of choice? :-)

I reported the bug about xdg-open not opening man pages the other day, 
and they rejected the bug because it's xfce's fault for not having a 
default application that opens man pages and I should install yelp(1). 
Then I thought of packaging this for debian.


> > > No, groff has even less responsibility than that.  Its job is to
> > > format a URI correctly and inform the output device, by whatever
> > > means it supports, that it is receiving one.  That's what OSC 8 is
> > > for EMCA-48-supporting terminals.
> > >
> > > Is this clearer?
> >
> > Yes, this is clearer, and better than what I thought.  But then I
> > understand even less why there's any need to disambiguate.  It should
> > be the terminal emulator that opens the link the one that
> > disambiguates it (or maybe it will call another utility like open(1)
> > which should then do the job).  The URI man:open is perfect as is, and
> > the URI man:open(2) is also perfect.  groff has zero responsibility
> > about the URI, and that includes zero responsibility about what it
> > means, or even if it points to a valid document.
>
> I'm certainly not going to complain if people say that the MR+OSC 8
> solution is complete enough to be viable (and valuable), but I think
> it's healthy to remain critical enough about it that we're receptive to
> potential further improvements, especially if we can do them in a
> backward-compatible way.  (Though since these features just landed, if
> they need to change in an _in_compatible way, now is the best time for
> it to happen.)

Okay.  My concern was about not rewriting the functionality of man(1) in 
another program, but if there may be some special benefit of doing so, 
of course.


> Regards,
> Branden
>
> [1] I review groff's man pages in PDF all the time, and it's why I also
>      want to add ms(7)-style keep support (KS, KE) support to man(7).
>      Unlike the MR feature, these macros could be utterly ignored by man
>      page writers (and even re-defined as empty macros) without losing
>      any page content.  But with them, the widow/orphan problem is
>      solvable.  One of my related nefarious ideas is to enhance the
>      paragraph macros to achieve window/orphan avoidance automatically.
>      The central observation is that you always know by the beginning of
>      the fourth output line of any paragraph where you can break it.[2]
>      If it's four lines long or longer, break it after the second line.
>      If it's three lines or fewer, hold the entire thing over to the next
>      page if it won't fit on the current one.
>
> [2] There remains the "orphan word" problem, but it's less painful if
>      the orphan line problem is also solved, and resolving it, as far as
>      I know, requires paragraph-at-a-time setting like Bertrand has been
>      working on.


--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/