[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [htmlxref.cnf] Please update link to the Groff manual
From: |
G. Branden Robinson |
Subject: |
Re: [htmlxref.cnf] Please update link to the Groff manual |
Date: |
Sat, 30 Sep 2023 13:15:09 -0500 |
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 _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.
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.
> > --- htmlxref.cnf 2023-09-23 12:39:52.969683777 +0200
> > +++ htmlxref.1.cnf 2023-09-23 12:39:39.417624780 +0200
> > @@ -442,5 +442,6 @@
> > grep node ${GS}/grep/manual/html_node/
> >
> > -groff node ${GS}/groff/manual/html_node/
> > +groff mono ${GS}/groff/manual/groff.html
> > +groff node ${GS}/groff/manual/groff.html.node/
> >
> > GRUB = ${GS}/grub/manual/
May I ask where this htmlxref.cnf file comes from? What software
project houses it?
At 2023-09-30T17:34:27+0200, Thérèse Godefroy wrote:
> No idea. This is the first time I see this sort of URL.
Web crawlers seem to be finding the groff 1.23.0 documentation okay,
though I recently had to be retrained in CVS by Alfred Szmidt in how to
effectively purge the old locations, housing a now-outdated version of
the manual, from the GNU site.[6] (Unfortunately, as I recall, CVS
can't revision-track symbolic links.)
Regards,
Branden
[1] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=750202#39 [5]
[2] and DVI, though Debian decided not to ship that format in its binary
packages, judging it archaic
[3]
https://web.cvs.savannah.gnu.org/viewvc/groff/groff/manual/index.html.in?view=log
https://web.cvs.savannah.gnu.org/viewvc/groff/groff/manual/Makefile?view=log
[4] cue the hisses and catcalls from the "official GNU" color guard
[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
[6] https://lists.gnu.org/archive/html/groff/2023-08/msg00128.html
https://lists.gnu.org/archive/html/groff/2023-09/msg00001.html
signature.asc
Description: PGP signature