Re: [htmlxref.cnf] Please update link to the Groff manual

[Ingo Schwarze]

[dropping the external Cc:s to avoid boring uninvolved parties]

Hi Branden,

G. Branden Robinson wrote on Sat, Sep 30, 2023 at 03:59:13PM -0500:
> At 2023-09-30T22:07:44+0200, Ingo Schwarze wrote:

>>   https://uu.diva-portal.org/smash/get/diva2:1189607/FULLTEXT01.pdf

> This link was of particular interest.  It praised groff 1.22.3's small
> size and high speed, but expressed significant frustration with its
> documentation.

That's very weird because the quality of groff documentation was
already excellent, and way above the average quality of software
documentation, even before you started working on it.  Werner Lemberg
and others did an outstanding job on it.  Groff 1.22.3 documentation
is definitely orders of magnitude better than LaTeX documentation -
and yes, i have worked a lot with LaTeX, including professionally
in academic settings.  LaTeX documentation is scattered all over the
place, almost impossible to search through, of widely varying quality
depending on the component, and the system as a whole is generally
almost impossible to use without refering to non-free sources
like Lamport's books - which i generally remember as aiming for a
loose tutorial-style approach, lacking the completeness, rigour, and
conciseness that you get when you use the groff texinfo manual together
with the relevant manual pages.  Yes, criticising the fragmentation
between the texinfo manual and the manual pages is a valid point, but
a very minor one, given that we are only talking about two sources.
For LaTeX, fragmentation of documentation is much worse.

> I wonder if the author would find the situation in 1.23.0 improved.

I doubt that.  I think the author is simply not used to working with
good documentation, just like he is clearly unexperienced with
software in general.  I mean, blaming groff for lower portability
because Microsoft Windows 10 does not install Perl and Ghostscript
by default?  That's just ridiculous.

The point isn't that you should take this particular person seriously -
to the contrary, you probably shouldn't worry too much about what he says.

The point is that the URI is in use across a wide array of media
from diverse sources.

> Plenty of organizations rotate in new director-level IT or "digital
> presence" managers who decree a change in CMSes just so they can say
> how "impactful" they are on their CVs.

That commercial organizations generally do lots of stupid things that
are not in the public interest (nor in their own interest really)
isn't all that surprising.  As you say, no need to emulate
corporate stupidity in the free software world, right?

> I concede that having a working "/html_node/" URL by hook or by crook
> (or by symlink) is probably a good idea given the list of URLs linking
> to it that you presented above.

Sure, you can keep both URIs indefinitely if you want.

There are samll downsides to having multiple redundant URIs for
the same resource, like higher maintenance effort and more potential
for confusion among users, so i generally try to keep the best URI
and slowly phase out the others (which usually takes many years)
but that's probably not a big deal.

With a URI component as firmly entrenched as /html_node/, phasing out
is likely no longer possible, even if you have a decade to spare for
the transition time, but for the newish /groff.html.node/, phasing
out may still be possible if you care about consistency.

Yours,
  Ingo