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

[G. Branden Robinson]

Hi Ingo,

At 2023-09-30T22:07:44+0200, Ingo Schwarze wrote:
> Now that i see this bumpy ride explained at length, i realize the
> link on this overview page of mine is currently broken, too:
> 
>   https://mandoc.bsd.lv/links.html
> 
> First paragraph, first line, second link ("manual").
> Rather prominently featured because, well, groff is important.
> 
> Here are a few more links to the established URI, in alphabetical order:

Ah, hmm, this sucks, and I reckon I should see what can be done to get a
symlink restored.

>   https://forums.freebsd.org/threads/converting-a-man-page-with-pandoc.36706/
>   https://git.pwmt.org/pwmt/zathura/-/issues/258
>   https://github.com/asciidoctor/asciidoctor/issues/3992
>   https://github.com/jgm/pandoc/issues/5019
>   https://lists.defectivebydesign.org/archive/html/groff/2020-10/msg00066.html
>   https://lwn.net/Articles/912260/
>   https://news.ycombinator.com/item?id=36066812
>   https://perldoc.perl.org/Pod::Perldoc::ToMan.txt
>   https://unix.stackexchange.com/questions/623970/writing-vietnamese-in-groff
>   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.

I wonder if the author would find the situation in 1.23.0 improved.
Incidentally, I recently became concerned myself with the question of
changing the paper format mid-document.[1]

>   https://www.illumos.org/issues/9367
>   https://www.reddit.com/r/groff/comments/gbfsx4/page_number_position/
>   ...
> 
> In general, i think keeping URIs stable makes sense unless there
> are *very* strong reasons for changing them - for example, forceful
> loss of control over the domain name. or finding out that the old name
> violated a relevant standard.

Neither of those apply here, certainly.

> Isn't making a resource available in the long term at least half the
> purpose of a URI in the first place, if not more than half?

I doubt it's the practice of even as many as half the pages on the web.
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.

whitehouse.gov is fairly notorious for being massively purged every time
there's a change of administration.  Self-important managers think
that's a virtue, not a vice, and emulate it in their own organizations.
This approach is popular with the sort of mind that models every
conflict as zero-sum, and suspects any alternative incentive structure
of being communism[2].

Our domain is different, as is the general direction of the ambition of
our personnel, and we should certainly do better if we can.  But I think
the DOI is supposed to be the solution to the longevity problem you
identify.[3]

> Besides, i don't see how a directory name on a public webserver
> could possibly be related to internal file naming conventions
> in autotools makefiles.

If you solve the problem in the simplest possible way, with make and cp,
the relationship seems pretty clear to me.

> Argumably,
> 
>   https://www.gnu.org/software/groff/manual/html_node/
> 
> is even better than
> 
>   https://www.gnu.org/software/groff/manual/groff.html.node/
> 
> because it's more concise (a virtue in URIs) and less redundant (a
> vice in URIs) without lacking any information.  The part of the path
> "groff/manual/groff" doen't really make much sense.

It can make sense if groff provides more than one manual (or document).

Looking in our doc/ directory, I see a few candidates.

automake.mom
grnexmpl.me
groff.texi
meintro.me.in
meintro_fr.me.in
meref.me.in
ms.ms
pic.ms

...and that doesn't include groff-man-pages.pdf.  Or Damian McGuckin's
work-in-progress on a new eqn manual.  Or the manual that someone should
certainly write about use of GNU refer(1).

I've been working for a while on paring the groff Texinfo manual's scope
down to something it can reasonably accomplish, and I'm very nearly
where I hoped to end up.  (There is a bit more I want to do with the
survey of full-service macro packages, though I think I want to retain
the comprehensive survey of ms, in a reversal from my thoughts in 2021.)

https://savannah.gnu.org/bugs/?60061

> Arguably, even /software/groff/manual/html_node/ is excessively
> wordy, but making it more concise and easier to remember is not
> a sufficient reason for changing it and breaking links.

No, and that's not why I changed it.  Orthogonality and similarity (to
the names of groff's Texinfo manual in other output formats) were.

> Probably it's best to go back to the link that has been in use for
> at least a decade - and for extra safety, maybe leave the longer
> path in place as an alias for a number of years before checking that
> no links to it remain on the web, then deleting the longer alias.

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.

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2023-07/msg00076.html
[2] Since the end of the Cold War, the identity of the eternal enemy is
    less firmly moored, but when the communist menace does not avail,
    one can always lead such people around with the adjective
    "un-XXXican", where "XXX" is the person's country of origin.
[3] https://en.wikipedia.org/wiki/Digital_object_identifier

signature.asc
Description: PGP signature