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

[Gavin Smith]

On Sat, Sep 30, 2023 at 01:15:09PM -0500, G. Branden Robinson wrote:
>     At the time I wrote that, I was unaware that "html_node", spelled
>     thus, was a solidified and inflexible convention of GNU
>     documentation.  (Where is this documented?)  We resolved the problem
>     for ourselves, using the new names, on the GNU web page for groff's
>     manuals, which you cited.
> 
>     https://www.gnu.org/software/groff/manual/
> 
>     As for why I chose the name I did, that was simply an ab initio
>     selection for congruence with "groff.pdf", "groff.txt", "groff.dvi",
>     "groff.info*", and "groff.html" (the "one big page" version).

It's no problem for us to change htmlxref.cnf to refer to wherever you
are putting the manual.  It is not that html_node is better than any
other name for a directory, other than that is the name that was used
before, so the name that would be used in pre-existing hyperlinks.


> 3.  "The summary page appears to have been generated with the gendocs
>     script from gnulib, which often used the html_node naming."
> 
>     That's not exactly correct.  The pre-groff 1.23.0 version of that
>     page may well have been--it seems likely given some of its
>     wording--but none of the infrastructure for producing it
>     was checked in anywhere.  I was unaware of the existence of this
>     script, and so used a template HTML file and make(1) to generate the
>     proper HTML file indexing (some of) the available documentation.[3]
> 
>     I'd prefer to stick with the template/Makefile approach, since it
>     was straightforward to enhance the page to link our collected groff
>     man pages document[4]...unless someone can tell me gnulib's
>     "gendocs" is flexible enough to do what I want easily.  (I think it
>     a kindness to warn people what the file sizes will be.  Also, when
>     Deri James's gropdf improvements are merged for groff 1.24, the file
>     size of groff-man-pages.pdf should come _way_ down.)
> 
>     And, as groff's PDF story further improves, there are additional
>     manuals I'd like to link thence, like our ms(7) manual, our me(7)
>     introduction and reference manuals, and so on.

I see, I'd assumed it was from gendocs.sh as the format is similar.  I'm
not recommending that you use gendocs.sh and what you have seems just as
good.

> May I ask where this htmlxref.cnf file comes from?  What software
> project houses it?

htmlxref.cnf is distributed with Texinfo and is also to be downloaded
from https://ftp.gnu.org/gnu/texinfo/.  It gives URLs of Texinfo
manuals on the World Wide Web.  texi2any uses this file when generating
hyperlinks to other Texinfo manuals.  It's there to make inter-manual
links work, which is an oft forgotten and neglected topic.

> 4.  "They might have changed this by mistake."
> 
>     Sort of.  I find the "html_node" name uglier, but if there's popular
>     demand to switch it (back), I can see doing that for groff 1.24.

We'll change htmlxref.cnf to whichever URLs you decide to use going forward.

If there are no links to the groff Texinfo HTML manuals anywhere on the
web, it doesn't matter, but it is likely there are at least some somewhere.

If we change it now to the new location, and then you change it back
afterwards, then any new links generated in the meantime will end up
pointing to the wrong place.  So please advise what you would have us
do.

> [5] Incidentally, "GROFF_SGR" (cf. "GROFF_NO_SGR") is now dead for real
>     in Debian testing/unstable.
> 
>     "Adopt upstream's use of SGR escape sequences for man/mdoc (LP:
>     #610609).  I turned these off for Debian in 2002 because pagers
>     didn't cope well at the time, but it's now 21 years later and things
>     have changed; SGR escape sequences resolve some ambiguity (see
>     #963490) and are required for new features such as clickable
>     hyperlinks."
> 
>     https://tracker.debian.org/media/packages/g/groff/changelog-1.23.0-2
> 

Interesting.  I hadn't known about this.

https://salsa.debian.org/debian/groff/-/commit/f0a34f20ff772f692255b7e32a05630c639f75a8
https://bugs.launchpad.net/ubuntu/+source/groff/+bug/610609