[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
