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

[G. Branden Robinson]

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