Subject: Re: bug#10371: Broken links in the on-line automake manual

From: Karl Berry <[email-masked]>
Date: Tue, 31 Mar 2020 19:31:41 -0600

Hi Stefano and all -- back on your report about broken urls from 2011 :) --

    Date: Mon, 26 Dec 2011 22:03:50 +0100

    Feeding the address of the on-line automake manual:
      <http://www.gnu.org/software/automake/manual/automake.html>

    to the W3C linkchecker:
      <http://validator.w3.org/checklink>

    I've found the following *broken links*:
      <http://www.gnu.org/software/automake/manual/tar.html>
      ...

The particular urls you found at that time (all are GNU manuals) are
not a problem any more, due to the Texinfo htmlxref feature we invented
to handle references from one Texinfo manual to another.
(Doc on that, for the record: https://gnu.org/s/texinfo/manual/texinfo/html_node/HTML-Xref-Configuration.html
 Current xref file: http://ftpmirror.gnu.org/texinfo/htmlxref.cnf)
So that is all fine.

However, I took the opportunity to rerun checklink on a single-file
automake.html (make AM_MAKEINFOHTMLFLAGS="--no-headers --no-split" html)
and found plenty of other problematic links in the manual (surprisingly,
there were none in automake-history.html).

I then made a few small changes to the W3C checklink script to eliminate
useless warnings and make exclude maintenance more convenience, and
called the resulting file checklinkx for (I hope) clarity. (Mostly I did
this because I hope to reuse this work for other documents and web pages
I maintain.)

The attached patch.gz fixes the urls in automake.texi, adds checklinkx
to the contrib/ subdirectory, and a new target in doc/local.mk to invoke
it for rechecking. Here's the ChangeLog entry I've got so far, for
convenience.

Comments/criticisms/suggestions/whatever? --karl
(With thanks to Jim for pre-reviewing this work and already suggesting
plenty of good improvements.)

-----------------------------------------------------------------------------
[PATCH] doc: update urls in manual and include checklinkx script.

* doc/automake.texi: update many urls; http -> https,
search.cpan.org -> metacpan.org/pod/distribution, node names, etc.
Remove sourceware.org/cgi-bin/gnatsweb.pl and
miller.emu.id.au/pmiller/books/rmch/ as these are 404
and no good replacement is evident.
s/perl/Perl/ a couple times in text for good measure.
* contrib/checklinkx: new script, a small modification of
W3C checklink <https://validator.w3.org/checklink/docs/checklink.html>
(W3C license, which is free software), starting from version 4.81
installed from CPAN:
https://metacpan.org/pod/distribution/W3C-LinkChecker/bin/checklink.pod
* doc/local.mk (checklinkx): new target to invoke it, with variables.
* Makefile.am (EXTRA_DIST): distribute it.