[CCing groff list and Mark Nudelman so he can correct me if I have mischaracterized less(1)'s development history]
Steffen,
At 2026-03-21T14:31:56+0100, Steffen Nurpmeso wrote:
> *OR*. Thomas Dickey could implement OSC-8 links in just that way i
> just mentioned, in the -dump mode, at least. That would be cool, if
> the ^O series of less(1) would work in that mode. It is, btw, a shame
> that groff did not accept my mdocmx(7) extension,
Your extension was not accepted into groff because the consensus of
developers was against incorporating it. I had issues with it, Ingo
Schwarze had issues with it,[0] and literally no one besides yourself
spoke in favor of it.
I've noticed that you've gone around various mailing lists and other
Internet fora painting me as a villain and yourself a persecuted victim,
predicated specifically (but perhaps not exclusively) on this rejection
of your feature proposal. So let's review some facts.
When you pitched "mdocmx" to the groff list in November 2014, you got
_no response_. The only follow-up messages on the subject for at least
a year are from you.[1] This is over two years before I began
participating in groff development. Perhaps you can come up with some
creative explanation of how I was manipulating then-maintainer Werner
Lemberg like a puppet even back then.
That manipulation would have had to extend to the next groff maintainer,
Bertrand Garrigues, who also did not incorporate your patch. Bertrand
remained maintainer until September 2024, though to be fair, due to
external factors, he was unable to allocate much time to groff
development after he made the 1.22.4 release in December 2018.
Setting aside conspiracy theories, let's evaluate the technical merits,
or lack thereof, of your proposed patches.
1. Your patch addressed only the mdoc(7) package, and not the more
widely used man(7) package. It was consequently an incomplete
solution for achieving hyperlinks between man pages, which may be
written using either package.
2. Your patch was _gigantic_.
$ diffstat -w72 ~/Documents/groff-1_22_3.diff
src/devices/grotty/tty.cpp | 126 +++++++++--
tmac/doc-common | 403 ++++++++++++++++++++++++++++++++++++-
tmac/doc-syms | 22 +-
tmac/doc.tmac | 94 +++++---
4 files changed, 578 insertions(+), 67 deletions(-)
3. Your patch appears to have been entangled with other objectives you
had for the code. It was conceptually overbroad, too, despite its
myopic focus only on the mdoc(7) package. For example, why does one
need a "multiplexer" just to associate URL data with man page cross
references? How does this new concept aid the man page author to
think about and employ cross references?
4. Your proposed changes to the grotty(1) output driver program for
terminal devices were ugly and difficult to understand.
Your introduction of a `__C` macro to abbreviate function calls is
horrendous. Usage of preprocessor macros for anything other than
header file inclusion and compile-time feature selection is non-
idiomatic in C++. If you were to claim that you were uneasy that
the `tty_printer` class's `add_char()` member function demands so
many arguments, I'd agree. This aspect of groff's driver API seems
designed with insufficient consideration of the output of characters
to the stream that wouldn't exist in a text formatting context.
(Rather, they are not _glyphs_, but abstract characters passed to a
device extension command and interpreted specially by the device.)
There are at least two alternative approaches to coping with such
awkwardness, each of which is superior to yours.
a. Use the existing member function's interface as-is, and if
that results in sequences of lengthy function calls, so be it.
A person reviewing the code can recognize and consider the
desirability of updating groff's driver API to accommodate the
needs of device extension commands.
b. Do the aforementioned API redesign as a prerequisite.
Ultimately we got hyperlinked man page cross references as OSC 8 support
because I implemented them. I did not need to add macros to the
packages except in one case: `MR` for man(7), which as Ingo noted, works
very much like mdoc(7)'s `Xr`, but which I modeled on a Plan 9 troff
innovation (which initially carried a different name, but they renamed
it at my suggestion).[2] Ultrix man(7) had an `MS` macro for this same
purpose.[3] Three independent implementations converged on an almost
identical design. Why? Because in each case the designers valued
simplicity. That is not a virtue exhibited by your patches.
None of this is to say that the problem was trivially easy to solve.
The patch I eventually implemented for mdoc(7) was not small.[4]
commit d063402936c3e339a158f33225b41a47eff5c17d
Author: G. Branden Robinson <[email protected]>
Date: Sun Feb 25 18:15:09 2024 -0600
...
tmac/doc.tmac | 280 ++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 227 insertions(+), 53 deletions(-)
However, compared to yours it was more general. It supported hyperlinks
not just for terminals, but for PDF as well. In fact, more than a few
lines added by the above patch simply stubbed out hyperlink support
devices other than the foregoing as no-ops. This was to keep the
details of hyperlink support as cleanly separated from mdoc(7)'s own
interface macros as I could manage. Applying Yourdon/Constantine
terminology raised in a recent groff thread,[5] this approach to ensure
"loose coupling" between the mdoc macro interface employed by man page
authors, and the characteristics of devices rendering a man page.
I had already implemented OSC 8 support in grotty(1) for groff 1.23.0,
released July 2023. It, too, was a substantial code change.
commit ab73e8189988d15bae12a82c6b3eb07948eda1d7
Author: G. Branden Robinson <[email protected]>
Date: Fri Oct 1 20:43:30 2021 +1000
[grotty]: Add OSC 8 hyperlink support.
* src/devices/grotty/tty.cpp: Do it. Define `OSC` (Operating System
Command) and `ST` (String Terminator) preprocessor symbols for these
ECMA-48 (ISO 6429) character sequences.
(tty_printer::simple_add_char): Add stripped-down alternative to
`add_char()` member function for cases where we want to use many
defaults because we're writing a device control command, not rendering
a glyph. (A function like `add_char()` that take 8 arguments of
varying types is a code smell--phew!)
(tty_printer::special): Call `special_link()` member function if the
device control command is `link`.
(tty_printer::special_link): Add new member function to generate OSC 8
hyperlinks.
* src/devices/grotty/grotty.1.man: Document it. Observe in multiple
places that disablement of SGR escape sequences disables OSC 8 too.
* src/devices/grotty/tests/osc8_works.sh: Test it.
* src/devices/grotty/grotty.am (TESTS, grotty_TESTS): Run test.
(EXTRA_DIST): Ship test.
* NEWS: Add item.
Fixes <https://savannah.gnu.org/bugs/?60666>. Thanks to Steffen
Nurpmeso for supplying a proof-of-concept. (I went with my own
implementation, though, so blame me if it breaks.)
src/devices/grotty/tty.cpp | 95 +++++++++++++++++++++++++++++++++++++-
1 file changed, 93 insertions(+), 2 deletions
Our changes to grotty were of comparable size.
$ diffstat -w72 /tmp/tty.cpp.steffen.diff
tty.cpp | 126 ++++++++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 104 insertions(+), 22 deletions(-)
I invite anyone to opine on their relative merits.
https://lists.gnu.org/archive/html/groff/2014-11/txtrjL4VjYkPh.txt
https://cgit.git.savannah.gnu.org/cgit/groff.git/commit/src/devices/grotty/tty.cpp?id=ab73e8189988d15bae12a82c6b3eb07948eda1d7
> i could not live without OSC-8 links, so i need local patch; however,
> less(1) has finally accepted it, after over a decade,
I speculate that the delay arises from either or both of two factors.
First, it appears that Mark Nudelman didn't so much "accept" your patch
as reimplement it.
Compare:
https://lists.gnu.org/archive/html/groff/2014-11/txtpqqEYBFUyl.txt
https://github.com/gwsw/less/commit/0f810ef16781bf0f59690be63af876bddabf68bf
I can understand why he did so. Much of your code, commentary, and
naming practices are unclearly motivated. Why would less(1) care about
your proposed mdocmx(7) extension macro package and *roff preprocessor?
less(1) operates on text files (sometimes containing escape sequences).
By the time less(1) processes its input, evidence of what produced the
OSC 8 escape sequences arguments is long gone unless deliberately
embedded as a form of advertising.
"Advertising" is what your rhetoric around mdocmx(7) resembles.
> and it is just rocking to have URL-style navigation within less(1)!
I agree that it is useful. less's support neatly escapes at least two
problems: (a) there's no terminfo(3) capability disclosing availability
of the feature to applications, and (b) Thomas Dickey has expressed
resistance to implementing support for OSC 8 in xterm(1). (Some of his
reasons and concerns, I understand and share.)
I have expressed appreciation for your advocacy of this feature.
https://github.com/gwsw/less/issues/248#issuecomment-3393341550
I note that you have chosen to repay this appreciation with tiresomely
repeated complaints implying your unfair treatment by the groff
development team.
So let me be blunt and reach the second factor that I think frustrates
acceptance of your patches. Your code contributions might find a better
reception, and your goals might take less than a decade before being
achieved through implementation by others, if the quality of your
contributions were better.
> |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)
I urge you to spend at least as much effort on improving your
ability as a programmer as the moon bear, a mainstay of your email
signature for many years, occupies in wanking himself off.
--Branden
[0] https://lists.gnu.org/archive/html/groff/2022-06/msg00118.html
[1] https://lists.gnu.org/archive/html/groff/2014-11/index.html#00281
https://lists.gnu.org/archive/html/groff/2014-11/index.html
https://lists.gnu.org/archive/html/groff/2014-12/index.html
https://lists.gnu.org/archive/html/groff/2015-04/index.html
[2]
https://github.com/9fans/plan9port/commit/d32deab17bfffa5bffc5fab3e6577558e40888c5
[3]
https://www.gnu.org/software/groff/manual/groff.html.node/Optional-man-extensions.html#Ultrix_002dspecific-man-macros
[4]
https://cgit.git.savannah.gnu.org/cgit/groff.git/commit/tmac/doc.tmac?id=d063402936c3e339a158f33225b41a47eff5c17d
[5] https://lists.gnu.org/archive/html/groff/2026-03/msg00101.html
signature.asc
Description: PGP signature
