Re: [htmlxref.cnf] Please update link to the Groff manual
On Sat, Sep 23, 2023 at 12:44:31PM +0200, Thérèse Godefroy wrote:
> Hello Gavin,
>
> The new URL of the node version is
> https://gnu.org/s/groff/manual/groff.html.node/
> And there is a mono version.
>
> A patch is attached.
>
> Best,
> Thérèse
Do you know why they made this change? They have changed their
documentation URLs which would break any links to pages of the manual.
There is no benefit to changing this that I am aware of.
The summary page appears to have been generated with the gendocs
script from gnulib, which often used the html_node naming.
https://www.gnu.org/software/groff/manual/
They might have changed this by mistake. I am trying to CC groff@gnu.org
into this email to make them aware of the problem.
> --- htmlxref.cnf 2023-09-23 12:39:52.969683777 +0200
> +++ htmlxref.1.cnf2023-09-23 12:39:39.417624780 +0200
> @@ -442,5 +442,6 @@
> grep node${GS}/grep/manual/html_node/
>
> -groffnode${GS}/groff/manual/html_node/
> +groffmono${GS}/groff/manual/groff.html
> +groffnode${GS}/groff/manual/groff.html.node/
>
> GRUB = ${GS}/grub/manual/
Re: [htmlxref.cnf] Please update link to the Groff manual
Le 30/09/2023 à 17:22, Gavin Smith a écrit : On Sat, Sep 23, 2023 at 12:44:31PM +0200, Thérèse Godefroy wrote: Hello Gavin, The new URL of the node version is https://gnu.org/s/groff/manual/groff.html.node/ And there is a mono version. A patch is attached. Best, Thérèse Do you know why they made this change? No idea. This is the first time I see this sort of URL. They have changed their documentation URLs which would break any links to pages of the manual. There is no benefit to changing this that I am aware of. [...]
Re: [htmlxref.cnf] Please update link to the Groff manual
Hi Gavin & Thérèse, At 2023-09-30T16:22:32+0100, Gavin Smith wrote: > On Sat, Sep 23, 2023 at 12:44:31PM +0200, Thérèse Godefroy wrote: > > Hello Gavin, > > > > The new URL of the node version is > > https://gnu.org/s/groff/manual/groff.html.node/ > > And there is a mono version. > > > > A patch is attached. > > > > Best, > > Thérèse > > Do you know why they made this change? They have changed their > documentation URLs which would break any links to pages of the manual. > There is no benefit to changing this that I am aware of. > > The summary page appears to have been generated with the gendocs > script from gnulib, which often used the html_node naming. > > https://www.gnu.org/software/groff/manual/ > > They might have changed this by mistake. I am trying to CC groff@gnu.org > into this email to make them aware of the problem. Answering these questions may put me at risk of having my idiocy called out by Gavin again.[1] Nevertheless... 1. Why did we make this change? Ingo Schwarze and I thoroughly revised groff's doc/doc.am file because it had accreted over many years in a way that was unsystematic and difficult to understand. It furthermore frequently neglected to adequately declare dependencies, causing problems for highly parallelized builds. (Indeed, we're still shaking some bugs out of this post-1.23.0, thanks to the efforts of Alexander Kanavin--but these have nothing to do with groff's Texinfo manual in any form.) Moreover, I had noticed that production of groff's Texinfo manual was complicated yet more by build-time dependencies, both mandatory and optional. I wanted to reduce the impact of those dependencies and also ensure that users of groff's distribution archive had ready access to groff's Texinfo manual--which I heavily revised in the years between groff 1.22.4 and 1.23.0--in several formats, including PDF and HTML, even if they were missing the dependencies necessary to build them. This seems to have worked out well for most consumers, who at the OS distribution level seem mainly concerned with patching groff to do questionable things with man pages. For Debian, which patches groff more extensively and also troubles itself to correspondingly update the documentation to reflect its changes, this change paid no dividend; it needs to keep the "heavy" dependency on a full TeX system to regenerate the groff Texinfo manual for PDF[2] from its source file. The change in question is this one, about 3,175 commits ago. https://git.savannah.gnu.org/cgit/groff.git/commit/?id=d79c3f3a4a19f7bf616a69558c4d3ce13690f441 The ChangeLog entry, and doc.am file comments at the line 311 hunk, are worth your attention--if you care to know what I was thinking. 2. "They have changed their documentation URLs which would break any links to pages of the manual. There is no benefit to changing this that I am aware of." You're speaking of the following hunk from the diff. -# This will generate both html split into several files and html doc -# in a single file. +# Generate HTML, both split into several files, and as a single file. +# 'html' and its installation counterpart 'install-html' are standard +# Automake targets. +EXTRA_DIST += doc/groff.html doc/groff.html.node +MAINTAINERCLEANFILES += doc/groff.html doc/groff.html.node 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). 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
Re: [htmlxref.cnf] Please update link to the Groff manual
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
Re: [htmlxref.cnf] Please update link to the Groff manual
Hi,
Gavin Smith wrote on Sat, Sep 30, 2023 at 08:10:01PM +0100:
> On Sat, Sep 30, 2023 at 01:15:09PM -0500, G. Branden Robinson wrote:
>> 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.
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:
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
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. 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?
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.
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.
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.
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.
Yours,
Ingo
Re: [htmlxref.cnf] Please update link to the Groff manual
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 proba
