GNU bug report logs - #9872
hello project web page includes libc and autotools manuals?

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 9872 in the body.
You can then email your comments to 9872 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: karl <at> freefriends.org (Karl Berry)
To: bob <at> proulx.com, jself <at> gnu.org, oneingray <at> gmail.com, ivan <at> gray.siamics.net, 
	virtualboxjames <at> gmail.com, nospam76 <at> gmail.com
Cc: bug-hello <at> gnu.org, bug-libtool <at> gnu.org
Subject: Re: hello project web page includes libc and autotools manuals?
Date: Tue, 25 Oct 2011 23:16:18 GMT

There were several messages on several lists about the crazy url's
relating to cross references from one Texinfo manual to another, like
http://www.gnu.org/software/libtool/manual/emacs/

I've explained this a number of times in a number of places, but
apparently not enough times and not the right places :).

The bad news is that there is no good way to fix this immediately.
We'll just have to keep living with these weird url's, as we have been
for many years already.

The good news is that the next release of Texinfo does fix this in the
right way, such that cross-manual references will end up going to the
real manual, as in
http://www.gnu.org/software/emacs/manual/etc...

I hope that we will make the first pretest for the next Texinfo within a
few days, perhaps next week.  At that point, it should be feasible to
use it to (re)generate HTML, if nothing else.  It would also be very
helpful testing from my Texinfo-maintainer perspective :).

I've been using the development Texinfo to create the HTML for new
versions of the GNU Coding Standards and Maintainer Information (and of
the latest GNU Hello release), so at least the thing is basically
functional.

Of course, another (ugly) option is to post-process the generated HTML
to change the links.  If anyone cares, I can send the scripts I used to
do that before the new Texinfo was far enough along.

Best,
karl

Message #8 received at 9872 <at> debbugs.gnu.org (full text, mbox):

From: Mike Frysinger <vapier <at> gentoo.org>
To: karl <at> freefriends.org
Cc: 9872 <at> debbugs.gnu.org, bob <at> proulx.com
Subject: Re: hello project web page includes libc and autotools manuals?
Date: Wed, 17 Jan 2024 07:36:35 +0000 (UTC)

On Tue, 25 Oct 2011 23:16:18 +0000, karl <at> freefriends.org wrote:
> There were several messages on several lists about the crazy url's
> relating to cross references from one Texinfo manual to another, like
> http://www.gnu.org/software/libtool/manual/emacs/
>
> I've explained this a number of times in a number of places, but
> apparently not enough times and not the right places :).
>
> The bad news is that there is no good way to fix this immediately.
> We'll just have to keep living with these weird url's, as we have been
> for many years already.
>
> The good news is that the next release of Texinfo does fix this in the
> right way, such that cross-manual references will end up going to the
> real manual, as in
> http://www.gnu.org/software/emacs/manual/etc...
>
> I hope that we will make the first pretest for the next Texinfo within a
> few days, perhaps next week.  At that point, it should be feasible to
> use it to (re)generate HTML, if nothing else.  It would also be very
> helpful testing from my Texinfo-maintainer perspective :).
>
> I've been using the development Texinfo to create the HTML for new
> versions of the GNU Coding Standards and Maintainer Information (and of
> the latest GNU Hello release), so at least the thing is basically
> functional.
>
> Of course, another (ugly) option is to post-process the generated HTML
> to change the links.  If anyone cares, I can send the scripts I used to
> do that before the new Texinfo was far enough along.

from what i can tell, there's no action required for libtool here ?

we aren't including any manuals in the libtool site.  those URIs work
because we've setup syminks, not because we copied content over.

$ cd htdocs/libtool/manual
$ cat .symlinks
/software/autoconf/manual/html_node     autoconf
/software/autoconf/manual/autoconf.html autoconf.html
/software/autoconf/manual/autoconf.pdf  autoconf.pdf
/software/automake/manual/html_node     automake
/software/automake/manual/automake.html automake.html
/software/automake/manual/automake.pdf  automake.pdf
/software/emacs/manual/html_node/emacs	emacs
/software/emacs/manual/html_mono/emacs.html emacs.html
/software/emacs/manual/emacs.pdf	emacs.pdf
/software/libc/manual/html_node         libc
/software/libc/manual/html_mono/libc.html libc.html
/software/libc/manual/pdf/libc.pdf      libc.pdf

$ curl http://www.gnu.org/software/libtool/manual/emacs/
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>302 Found</title>
</head><body>
<h1>Found</h1>
<p>The document has moved <a href="http://www.gnu.org/savannah-checkouts/gnu/emacs/manual/html_node/emacs/">here</a>.</p>
<hr>
<address>Apache/2.4.29 Server at www.gnu.org Port 80</address>
</body></html>
-mike

Message #11 received at 9872 <at> debbugs.gnu.org (full text, mbox):

From: Karl Berry <karl <at> freefriends.org>
To: vapier <at> gentoo.org
Cc: 9872 <at> debbugs.gnu.org, bob <at> proulx.com
Subject: Re: hello project web page includes libc and autotools manuals?
Date: Wed, 17 Jan 2024 14:55:36 -0700

    from what i can tell, there's no action required for libtool here ?

Only if you want to get rid of your symlinks.

    we aren't including any manuals in the libtool site.  those URIs work
    because we've setup syminks, not because we copied content over.

Texinfo has supported cross-manual references "correctly" for a decade
now (version 5.0, ca.2013). The control file is named htmlxref.cnf
(should already be in any Texinfo installation).

I don't think you have to do anything special; the cross-manual xrefs
should just come out referring to the manuals on their own project page.
The implementation is described here:
https://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#HTML-Xref

We never implemented links for PDFs, though, which I see you're making
symlinks for. Is that so if someone clicks on a link in libtool.pdf
(reading online) which goes to emacs.pdf, it works? That is not a case
that was relevant in the past, but I imagine it could be added (not by me).

Thanks,
Karl

Message #14 received at 9872 <at> debbugs.gnu.org (full text, mbox):

From: Mike Frysinger <vapier <at> gentoo.org>
To: Karl Berry <karl <at> freefriends.org>
Cc: 9872 <at> debbugs.gnu.org, bob <at> proulx.com
Subject: Re: hello project web page includes libc and autotools manuals?
Date: Wed, 17 Jan 2024 18:46:42 -0500

[Message part 1 (text/plain, inline)]

On 17 Jan 2024 14:55, Karl Berry wrote:
>     from what i can tell, there's no action required for libtool here ?
> 
> Only if you want to get rid of your symlinks.

i don't think it costs us anything, so i'm not really worried

>     we aren't including any manuals in the libtool site.  those URIs work
>     because we've setup syminks, not because we copied content over.
> 
> Texinfo has supported cross-manual references "correctly" for a decade
> now (version 5.0, ca.2013). The control file is named htmlxref.cnf
> (should already be in any Texinfo installation).
> 
> I don't think you have to do anything special; the cross-manual xrefs
> should just come out referring to the manuals on their own project page.
> The implementation is described here:
> https://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#HTML-Xref

i guess it's a question of, have all the broken manuals been regenerated, and
do we care if older local archives are broken ?  what about older versions of
manuals too ?
https://www.gnu.org/software/automake/manual/index-full.html

> We never implemented links for PDFs, though, which I see you're making
> symlinks for. Is that so if someone clicks on a link in libtool.pdf
> (reading online) which goes to emacs.pdf, it works? That is not a case
> that was relevant in the past, but I imagine it could be added (not by me).

not sure why the links are there, but they were added explicitly:
revision 1.2
date: 2011-01-29 05:59:55 -0500;  author: rwild;  state: Exp;  lines: +6 -3;  commitid: AjTk1baMH0tAo96v;
* manual/.symlinks: Reorder symlinks.  Add links to PDF versions
of other manuals.
Prompted by report from Jim Warhol against Autoconf.
-mike

[signature.asc (application/pgp-signature, inline)]

Message #17 received at 9872 <at> debbugs.gnu.org (full text, mbox):

From: Karl Berry <karl <at> freefriends.org>
To: vapier <at> gentoo.org
Cc: 9872 <at> debbugs.gnu.org, bob <at> proulx.com
Subject: Re: hello project web page includes libc and autotools manuals?
Date: Thu, 18 Jan 2024 15:55:07 -0700

    i don't think it costs us anything, so i'm not really worried

Agreed. Closing this bug.
But for the record will reply to your other comments.

    i guess it's a question of, have all the broken manuals been regenerated, 

I would hope so, by now, but I haven't checked.

    do we care if older local archives are broken ?

I don't :).

    what about older versions of manuals too ?
    https://www.gnu.org/software/automake/manual/index-full.html

Well, Automake does not have any .symlinks for other manuals, so I
assume there are plenty of broken cross-manual links, but no one has
complained. Although I don't think that means much of anything.

In general, my theory on such cross-manual references is that for
decades it was essentially random whether it worked or not ... and it
mostly didn't. Which is why Patrice and I invented the htmlxref.cnf
system in the first place. So I can't get too excited about worrying
about previous attempts. It's not like it's terribly difficult to just
visit the other manual and find the node in question.

Anyway, doing nothing sounds like a good solution to me :). --best, karl.

Message #25 received at 9872 <at> debbugs.gnu.org (full text, mbox):

From: Mike Frysinger <vapier <at> gentoo.org>
To: Karl Berry <karl <at> freefriends.org>
Cc: 9872 <at> debbugs.gnu.org, bob <at> proulx.com
Subject: Re: hello project web page includes libc and autotools manuals?
Date: Thu, 18 Jan 2024 19:54:58 -0500

[Message part 1 (text/plain, inline)]

On 18 Jan 2024 15:55, Karl Berry wrote:
>     i don't think it costs us anything, so i'm not really worried
> 
> Agreed. Closing this bug.
> But for the record will reply to your other comments.
> 
>     i guess it's a question of, have all the broken manuals been regenerated, 
> 
> I would hope so, by now, but I haven't checked.
> 
>     do we care if older local archives are broken ?
> 
> I don't :).
> 
>     what about older versions of manuals too ?
>     https://www.gnu.org/software/automake/manual/index-full.html
> 
> Well, Automake does not have any .symlinks for other manuals, so I
> assume there are plenty of broken cross-manual links, but no one has
> complained. Although I don't think that means much of anything.

i meant, do old automake manuals have the broken links and refer to the
libtool links ?  to answer my own question, i grepped the automake tree
and all https://www.gnu.org/software/libtool/... links are to manual/,
nothing else.

just to be clear, was the problem they were referring to libtool all
the time ?  or was it they would use the current URI base to point to
a diff project ?  so the .symlinks file would only be for libtool's
own manuals, or were other projects also routing via those links ?

i thought it was the latter.  if it's the former, killing the symlinks
now sounds fine.
-mike

[signature.asc (application/pgp-signature, inline)]

Message #28 received at 9872 <at> debbugs.gnu.org (full text, mbox):

From: Karl Berry <karl <at> freefriends.org>
To: vapier <at> gentoo.org, 9872 <at> debbugs.gnu.org
Subject: Re: hello project web page includes libc and autotools manuals?
Date: Sat, 20 Jan 2024 15:40:39 -0700

Mike, I'm not entirely sure what you meant by your other questions, but
the answer to:

    were other projects also routing via those links ?

is no. The .symlinks within gnu.org/s/libtool/manual were/are
essentially only used by libtool's manuals, within
gnu.org/s/automake/manual only by automake's manuals, etc.

Well, I guess I'm not sure what happened when a cross-referenced manual
referred to yet another external manual, but that's not a case I was
ever worried about (or saw reported).

The basic problem was that a cross-manual link would end up with a url
like "libtool within automake"
 gnu.org/s/automake/manual/libtool/somenode.html.
Hence the .symlinks entry, to make that resolve.

But I'm confused now, because looking at even the earliest automake
manual, https://www.gnu.org/software/automake/manual/1.0/automake.html
the xref to the autoconf manual in the introduction has the good url:
https://www.gnu.org/software/autoconf/manual/autoconf.html#Top

instead of something like the bad ("autoconf within automake") url:
https://www.gnu.org/software/automake/manual/autoconf/autoconf.html#Top

that I would have expected, and surely what was generated with
automake-1.0 or other early-ish releases.

Maybe someone regenerated all the automake manuals at some point.
I don't know, but I have no other explanation.

Best,
Karl

Message #31 received at 9872 <at> debbugs.gnu.org (full text, mbox):

From: Mike Frysinger <vapier <at> gentoo.org>
To: Karl Berry <karl <at> freefriends.org>
Cc: 9872 <at> debbugs.gnu.org
Subject: Re: hello project web page includes libc and autotools manuals?
Date: Sat, 20 Jan 2024 19:56:57 -0500

[Message part 1 (text/plain, inline)]

On 20 Jan 2024 15:40, Karl Berry wrote:
>     were other projects also routing via those links ?
> 
> is no. The .symlinks within gnu.org/s/libtool/manual were/are
> essentially only used by libtool's manuals

ok, i've deleted them now then as current libtool manuals do not use them.
-mike

[signature.asc (application/pgp-signature, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.