Re: getting more out of man pages with less(1)

[Steffen Nurpmeso]

Hello.

 |> Good idea.  I've further changed the Subject: to reflect the flow of the
 |> discussion.
 ...
 |> I also wonder if the pager wars are basically over and less(1) won them.
 |
 |That's certainly what I thought...
 ..

Ever since less(1) started supporting OSC 8 "Hyperlinks in
Terminal Emulators" as of version 566 i wanted to rewrite my
mdocmx(7) extension to be based upon the OSC 8 sequences that now
become more and more common.

So the last two days i finally made the great and implemented
OSC 8 for my mdoxmx macro package extension, as well as for grotty
v1.22.3 and less v586.  Yay.
grotty was a bit hard because i wanted to implement all sorts of
OSC 8 things, even those they did not invent there in that github
repo, like document-local anchors and document-local "URI"s (i
used the usual "#REF" syntax used by eg HTML).

  +    // Place a document-local anchor; arg(s): 1=ID
  +    // (An OSC8 sequence without URI and INNER-TEXT.)
  +    {"anchor", sizeof("anchor") -1, a_ANCHOR, 1},
  +    // Link with inner text; arg(s): 1=URI, 2=INNER-TEXT
  +    {"link", sizeof("link") -1, a_LINK, 2},
  +    // Reference a document-local anchor; arg(s): 1=ID [2=INNER-TEXT]
  +    // If INNER-TEXT is missing ID is reused for that.
  +    {"link-anchor", sizeof("link-anchor") -1, a_LINK_ANCHOR, 2},
  +    // Reference a manual page; arg(s): 1=NAME 2=SECTION-NR [3=ID]
  +    // ID is optional, SECTION is manual section (eg "idle 2 55", "vi 1p").
  +    // This ends up as "man://NAME.SECTION", the inner text will be ID if ID
  +    // was given, otherwise "NAME(ID)".
  +    {"link-manual\0", sizeof("link-manual") -1, a_LINK_MANUAL, 3},
  +    // Link with externally controlled inner text; arg(s): 1=URI
  +    {"link-start", sizeof("link-start") -1, a_LINK_START, 1},
  +    // No arguments
  +    {"link-end", sizeof("link-end") -1, a_LINK_END, 0}

Eg \X'tty osc8 link-anchor 50' or \X'tty osc8 link-manual awk 79'.
The latter ends up like (here in blue as my mdocmx does it):

  awk(1)^[[34m[^[]8;id=79;man://awk.1^[\79^[]8;;^[\]^[[0m

So for example (here formatted by my mdocmx macro extension):

  SEE ALSO
       awk(1)[79], ...

then in less(1) with the OSC 8 anchor-search patch, typing ^A:

  [OSC 8 anchor]:

then typing 79 and return and one sees

  Read external manual: !man 1 awk

and if you return return again that comes up.
One could think about dropping link-manual and simply offering
a $LESS_BROWSER or so hook, but like this some security checks can
be applied more easily.  (Only fewest yet.)

I pushed the git mail-patch boxes to the git repo of my roff clone
that is still awaiting any actions.  On Monday i will apply some
more content checking on the link-manual content in less(1) (in
grotty we already check cisprint before we create the OSC
8 sequence).

The nice thing with OSC 8 is that generators like docbook or so
could simply enwrap things like

  .BR cat (1)

with \X'tty: osc8 link-start cat 1' and \X'tty: osc8 link-end'.
For my search patch for less(1) however this would not work out.
For now the less(1) OSC 8 search patch requires an id= though.

A nice sunday i wish from Germany.

--steffen
|
|Der Kragenbaer,                The moon bear,
|der holt sich munter           he cheerfully and one by one
|einen nach dem anderen runter  wa.ks himself off
|(By Robert Gernhardt)