[doc] fix broken anchor in install.texi

ping

We currently have a broken link in the installation docs, see below.
I've tried to fix it, but on both Fedora 15 and Debian squeeze the
docs generated by "make html" do not match the online docs because of
a different version of makeinfo (4.13 versus 4.8 usedfor the online
docs).

Can anyone with makeinfo 4.8 confirm that this fixes the broken anchor?

Or should I just commit it as obvious and revert it if the regenerated
onlinedocs aren't fixed?


On 4 October 2011 20:32, Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
> I want to commit the attached patch to install.texi, but have been
> unable to test it successfully.
>
> The problem is that the link for "x86_64-*-solaris2.1[0-9]*" in the
> Host/Target Specific notes is
> http://gcc.gnu.org/install/specific.html#x86-64-x-solaris210
> but the corresponding anchor is:
> <a name="x86-64-x-solaris2_002e10">
>
> Note the "_002e" difference, which is caused by the texinfo uref being:
> @uref{#x86-64-x-solaris210,,x86_64-*-solaris2.1[0-9]*}
> but the anchor target having an extra dot:
> @anchor{x86-64-x-solaris2.10}
>
> My patch removes that dot.
>
> I tried to test it by regenerating the HTML docs (using
> texinfo-4.13a-15 from Fedora 15), but I get different results: the dot
> is gone as expected, but every hyphen gets expanded to _002d, so none
> of the anchors work!
>
> I'm pretty sure the patch is correct but will check the link in the
> GCC onlinedocs once they're regenerated.
>
> OK to commit?
>
> 2011-10-04  Jonathan Wakely  <jwakely.gcc@gmail.com>
>
>        * doc/install.texi (Specific): Fix anchor for
>        x86_64-*-solaris2.1[0-9]*
>

On Mon, 7 Nov 2011, Jonathan Wakely wrote:
> We currently have a broken link in the installation docs, see below.
> I've tried to fix it, but on both Fedora 15 and Debian squeeze the
> docs generated by "make html" do not match the online docs because of
> a different version of makeinfo (4.13 versus 4.8 usedfor the online
> docs).
> 
> Can anyone with makeinfo 4.8 confirm that this fixes the broken anchor?
> 
> Or should I just commit it as obvious and revert it if the regenerated
> onlinedocs aren't fixed?

Jonathan, I am a bit confused because if I use the online documentation
at http://gcc.gnu.org/install/specific.html the anchor is already of the
form "sparc-sun-solaris210", that is, without the dot, and it works just
fine.

On the other hand, looking at the source code your patch has not been
applied yet.

Since your patch makes things just more conservative and robust, let's
go ahead and apply it.  Just, if there is something I missed, please
advise. :-)


As a bit of background, sadly at one point makeinfo added transformations
for special characters to replace them by hex values weirdly encoded; 
that is the _002e you are seeing: hex 2E, the ASCII dot.

For this reason I have this in wwwdocs/bin/preprocess that takes care
of restorting dashes and asterisks (at the price of breaking links to 
external documents, since we can only fix up what is under our control):

  sed -e 's/_002d/-/g' -e 's/_002a/*/g'

We might consider adding -e 's/_002e/./g', but really, just avoiding
this altogether as your patch does, seems wiser.

Thanks,
Gerald

On 13 November 2011 04:40, Gerald Pfeifer <gerald@pfeifer.com> wrote:
> On Mon, 7 Nov 2011, Jonathan Wakely wrote:
>> We currently have a broken link in the installation docs, see below.
>> I've tried to fix it, but on both Fedora 15 and Debian squeeze the
>> docs generated by "make html" do not match the online docs because of
>> a different version of makeinfo (4.13 versus 4.8 usedfor the online
>> docs).
>>
>> Can anyone with makeinfo 4.8 confirm that this fixes the broken anchor?
>>
>> Or should I just commit it as obvious and revert it if the regenerated
>> onlinedocs aren't fixed?
>
> Jonathan, I am a bit confused because if I use the online documentation
> at http://gcc.gnu.org/install/specific.html the anchor is already of the
> form "sparc-sun-solaris210", that is, without the dot, and it works just
> fine.

The list of targets at the top of the page includes
x86_64-*-solaris2.1[0-9]* which is a hyperlink to
http://gcc.gnu.org/install/specific.html#x86-64-x-solaris210

Clicking it does nothing.  It's supposed to go to this anchor:
<h3 class="heading"><a name="TOC58"></a><a
name="x86-64-x-solaris2_002e10"></a>x86_64-*-solaris2.1[0-9]*</h3>

Does clicking x86_64-*-solaris2.1[0-9]* work for you?

> On the other hand, looking at the source code your patch has not been
> applied yet.
>
> Since your patch makes things just more conservative and robust, let's
> go ahead and apply it.  Just, if there is something I missed, please
> advise. :-)

OK, I'll apply it and check the results after the docs regenerate, thanks.


> As a bit of background, sadly at one point makeinfo added transformations
> for special characters to replace them by hex values weirdly encoded;
> that is the _002e you are seeing: hex 2E, the ASCII dot.
>
> For this reason I have this in wwwdocs/bin/preprocess that takes care
> of restorting dashes and asterisks (at the price of breaking links to
> external documents, since we can only fix up what is under our control):
>
>  sed -e 's/_002d/-/g' -e 's/_002a/*/g'
>
> We might consider adding -e 's/_002e/./g', but really, just avoiding
> this altogether as your patch does, seems wiser.

Aha, that explains why when I regenerate the docs I get hundreds of
escaped characters that I don't see when looking at the onlinedocs.

On Sun, 13 Nov 2011, Jonathan Wakely wrote:
>> Jonathan, I am a bit confused because if I use the online documentation
>> at http://gcc.gnu.org/install/specific.html the anchor is already of the
>> form "sparc-sun-solaris210", that is, without the dot, and it works just
>> fine.
> The list of targets at the top of the page includes
> x86_64-*-solaris2.1[0-9]* which is a hyperlink to
> http://gcc.gnu.org/install/specific.html#x86-64-x-solaris210

Ah, my bad.  Somehow my brain automatically reads sparc when seeing
solaris. :-)

> Does clicking x86_64-*-solaris2.1[0-9]* work for you?

It does not, and your patch should fix that, indeed.  Thanks!

Gerald

On 13 November 2011 14:31, Gerald Pfeifer wrote:
> On Sun, 13 Nov 2011, Jonathan Wakely wrote:
>>> Jonathan, I am a bit confused because if I use the online documentation
>>> at http://gcc.gnu.org/install/specific.html the anchor is already of the
>>> form "sparc-sun-solaris210", that is, without the dot, and it works just
>>> fine.
>> The list of targets at the top of the page includes
>> x86_64-*-solaris2.1[0-9]* which is a hyperlink to
>> http://gcc.gnu.org/install/specific.html#x86-64-x-solaris210
>
> Ah, my bad.  Somehow my brain automatically reads sparc when seeing
> solaris. :-)

Ha, I had the same arch-blindness and didn't see you'd said sparc!

>> Does clicking x86_64-*-solaris2.1[0-9]* work for you?
>
> It does not, and your patch should fix that, indeed.  Thanks!

I've applied the patch now - thanks.