[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Possible problem / misunderstanding in make manual

From: Karl Berry
Subject: Re: Possible problem / misunderstanding in make manual
Date: Wed, 11 May 2011 21:27:42 GMT

    Anyone know what the make manual is doing in hello's web space?

It's a painful story.  I was hoping not to have to explain it :).

1) The Hello manual links to many other Texinfo manuals (though not the
make manual :).  Those other manuals link to many more (including make).
Probably the closure ends up being nearly all of main ones.

2) I didn't want these links to just be broken in hello.html.  So I
added .symlinks entries to make them work.  (If you look at the CVS web
repo, you will see.)  The way .symlinks is implemented now, it ends up
being another name for the page itself, rather than a redirect.  (We've
submitted work to sysadmin to change this, among many other things.)

3) Google in its infinite wisdom decided to make these "sub"manuals come
up as the first hit on things like "make manual".  So I got lots and
lots of bug reports about broken cross-manual references three manuals
away from hello.

4) This is all a consequence of cross-manual xrefs not being supported
properly in Texinfo's HTML output.  That is, makeinfo couldn't generate
a link to (say) /software/make/manual/make.html#whatever, but rather
simply make.html#whatever.  Thus the need for the .symlinks entries.

5) Patrice Dumas and I finally cooked up enough support in Texinfo to
generate proper cross-manual links.  It requires using Patrice's
unreleased texi2html/ implementation that is in Texinfo CVS.  (I can
send more details about how to do that when/if you need to.)
Standards-breaking though it is, I went with that to avoid prolonging
the cross-manual agony I was experiencing :).

6) I regenerated the Hello manual using that new code a few weeks ago.
In fact, that was the main reason for the 2.7 release, to give me an
excuse to update the manual :).  So now, the cross-manual links in
hello.html go to the real manuals; but of course I kept the .symlinks
around for the time being.  You could remove them now, or at some future
date, although the web being what it is, I suspect that would unleash a
new stream of reports about cross-manual link xxx being broken.

It's a sorry tale.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]