GNU bug report logs - #8071
Please rename automake invocation node

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 8071 in the body.
You can then email your comments to 8071 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: Reuben Thomas <rrt <at> sc3d.org>
To: bug-automake <bug-automake <at> gnu.org>
Subject: Please rename automake invocation node
Date: Thu, 17 Feb 2011 23:04:42 +0000

This is actually a bug that affects several autotools packages,
excluding autoconf, for which it's already fixed: the invocation node
is added to the info dir as "automake" which means that

info automake

goes to the invocation node, not the Top node.

autoconf calls its invocation node autoconf-invocation instead.

While on this subject; all the other autotools entitle their
invocation nodes "autofoo Invocation", whereas automake calls its
"Invoking Automake".

Checked against git head.

-- 
http://rrt.sc3d.org

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

From: Stefano Lattarini <stefano.lattarini <at> gmail.com>
To: Reuben Thomas <rrt <at> sc3d.org>
Cc: 8071 <at> debbugs.gnu.org, automake-patches <at> gnu.org
Subject: Re: bug#8071: Please rename automake invocation node
Date: Mon, 26 Dec 2011 20:34:04 +0100

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

tags 8071 patch
close 8071
thanks

Hi Reuben, sorry for the ludicrous delay.

On 02/18/2011 12:04 AM, Reuben Thomas wrote:
> This is actually a bug that affects several autotools packages,
> excluding autoconf, for which it's already fixed: the invocation node
> is added to the info dir as "automake" which means that
> 
> info automake
> 
> goes to the invocation node, not the Top node.
>
I agree that this is suboptimal and confusing.

The attached patch, applied to maint, fixes the issue.  I'm thus closing
this bug report.

> autoconf calls its invocation node autoconf-invocation instead.
> 
> While on this subject; all the other autotools entitle their
> invocation nodes "autofoo Invocation", whereas automake calls its
> "Invoking Automake".
> 
I haven't changed this, because that could break existing third-party links
to our HTML documentation (OK, that could probably be fixed with an update
to the .symlinks file in the CVS repository of the Automake web pages, but
IMHO it's not worth the hassle).

Thanks,
  Stefano

[0001-docs-fix-node-names-for-automake-and-aclocal-invocat.patch (text/x-diff, attachment)]

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

From: Eric Blake <eblake <at> redhat.com>
To: Stefano Lattarini <stefano.lattarini <at> gmail.com>
Cc: 8071 <at> debbugs.gnu.org, automake-patches <at> gnu.org,
	Reuben Thomas <rrt <at> sc3d.org>
Subject: Re: bug#8071: Please rename automake invocation node
Date: Wed, 28 Dec 2011 05:50:18 -0700

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

On 12/26/2011 12:34 PM, Stefano Lattarini wrote:
>> While on this subject; all the other autotools entitle their
>> invocation nodes "autofoo Invocation", whereas automake calls its
>> "Invoking Automake".
>>
> I haven't changed this, because that could break existing third-party links
> to our HTML documentation (OK, that could probably be fixed with an update
> to the .symlinks file in the CVS repository of the Automake web pages, but
> IMHO it's not worth the hassle).

This can be fixed by using an @anchor{} to the old name at the same
location as you switch to the new consistent node name.  The tools will
then keep the old link live by virtue of the anchor, without having to
mess with .symlinks.

-- 
Eric Blake   eblake <at> redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

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

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

From: Stefano Lattarini <stefano.lattarini <at> gmail.com>
To: Eric Blake <eblake <at> redhat.com>
Cc: 8071 <at> debbugs.gnu.org, automake-patches <at> gnu.org,
	Reuben Thomas <rrt <at> sc3d.org>
Subject: Re: bug#8071: Please rename automake invocation node
Date: Wed, 28 Dec 2011 20:33:44 +0100

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

On 12/28/2011 01:50 PM, Eric Blake wrote:
> On 12/26/2011 12:34 PM, Stefano Lattarini wrote:
>>> While on this subject; all the other autotools entitle their
>>> invocation nodes "autofoo Invocation", whereas automake calls its
>>> "Invoking Automake".
>>>
>> I haven't changed this, because that could break existing third-party links
>> to our HTML documentation (OK, that could probably be fixed with an update
>> to the .symlinks file in the CVS repository of the Automake web pages, but
>> IMHO it's not worth the hassle).
> 
> This can be fixed by using an @anchor{} to the old name at the same
> location as you switch to the new consistent node name.  The tools will
> then keep the old link live by virtue of the anchor, without having to
> mess with .symlinks.
> 
Good idea.  What about the attached patch?  I'm not very familiar with
the translation of @anchor directives in the HTML output, so I'd like an
explicit ACK before pushing.

Thanks,
  Stefano

[0001-docs-fix-paragraph-names-for-automake-and-aclocal-in.patch (text/x-diff, attachment)]

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

From: Stefano Lattarini <stefano.lattarini <at> gmail.com>
To: Eric Blake <eblake <at> redhat.com>
Cc: 8071 <at> debbugs.gnu.org, automake-patches <at> gnu.org,
	Reuben Thomas <rrt <at> sc3d.org>
Subject: Re: bug#8071: Please rename automake invocation node
Date: Fri, 30 Dec 2011 13:44:16 +0100

On 12/28/2011 08:33 PM, Stefano Lattarini wrote:
> On 12/28/2011 01:50 PM, Eric Blake wrote:
>> On 12/26/2011 12:34 PM, Stefano Lattarini wrote:
>>>> While on this subject; all the other autotools entitle their
>>>> invocation nodes "autofoo Invocation", whereas automake calls its
>>>> "Invoking Automake".
>>>>
>>> I haven't changed this, because that could break existing third-party links
>>> to our HTML documentation (OK, that could probably be fixed with an update
>>> to the .symlinks file in the CVS repository of the Automake web pages, but
>>> IMHO it's not worth the hassle).
>>
>> This can be fixed by using an @anchor{} to the old name at the same
>> location as you switch to the new consistent node name.  The tools will
>> then keep the old link live by virtue of the anchor, without having to
>> mess with .symlinks.
>>
> Good idea.  What about the attached patch?  I'm not very familiar with
> the translation of @anchor directives in the HTML output, so I'd like an
> explicit ACK before pushing.
> 
Pushed to maint now.  Let's hope I've not messed anything up.

Regards,
  Stefano

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

From: Eric Blake <eblake <at> redhat.com>
To: Stefano Lattarini <stefano.lattarini <at> gmail.com>
Cc: 8071 <at> debbugs.gnu.org, automake-patches <at> gnu.org,
	Reuben Thomas <rrt <at> sc3d.org>
Subject: Re: bug#8071: Please rename automake invocation node
Date: Fri, 30 Dec 2011 06:59:48 -0700

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

On 12/28/2011 12:33 PM, Stefano Lattarini wrote:
>> > This can be fixed by using an @anchor{} to the old name at the same
>> > location as you switch to the new consistent node name.  The tools will
>> > then keep the old link live by virtue of the anchor, without having to
>> > mess with .symlinks.
>> > 
> Good idea.  What about the attached patch?  I'm not very familiar with
> the translation of @anchor directives in the HTML output, so I'd like an
> explicit ACK before pushing.
> 

>  
> -
> -@node Invoking Automake
> +@c The anchor is required to avoid breaking existing web hyperlinks
> +@c still using the old name of this node.
> +@anchor{Invoking automake}
> +@node automake Invocation
>  @chapter Creating a @file{Makefile.in}

Autoconf has this example:

@node Specifying Target Triplets
@section Specifying target triplets
@cindex System type
@cindex Target triplet
@c This node used to be named Specifying Names.  The @anchor allows old
@c links to still work.
@anchor{Specifying Names}

I'm not sure if putting the @anchor after the @node make a difference.
If the anchor takes the old name to the previous node, then we may want
to move the anchor to appear after the @node.

-- 
Eric Blake   eblake <at> redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

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

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

From: Stefano Lattarini <stefano.lattarini <at> gmail.com>
To: Eric Blake <eblake <at> redhat.com>
Cc: 8071 <at> debbugs.gnu.org, automake-patches <at> gnu.org,
	Reuben Thomas <rrt <at> sc3d.org>
Subject: Re: bug#8071: Please rename automake invocation node
Date: Fri, 30 Dec 2011 15:07:26 +0100

On 12/30/2011 02:59 PM, Eric Blake wrote:
> On 12/28/2011 12:33 PM, Stefano Lattarini wrote:
>> -
>> -@node Invoking Automake
>> +@c The anchor is required to avoid breaking existing web hyperlinks
>> +@c still using the old name of this node.
>> +@anchor{Invoking automake}
>> +@node automake Invocation
>>  @chapter Creating a @file{Makefile.in}
> 
> Autoconf has this example:
> 
> @node Specifying Target Triplets
> @section Specifying target triplets
> @cindex System type
> @cindex Target triplet
> @c This node used to be named Specifying Names.  The @anchor allows old
> @c links to still work.
> @anchor{Specifying Names}
>
I'll happily accept a patch to have the automake manual follow the
autoconf one's lead (or I'll end up writing it myself if no one is
so kind to beat me at that :-)

> I'm not sure if putting the @anchor after the @node make a difference.
> If the anchor takes the old name to the previous node, then we may want
> to move the anchor to appear after the @node.
> 
It's a pity that, with the current infrastructure, there now is viable way
to test how a change done in the git repository will reflect on the
on-line manual :-(

Thanks,
  Stefano

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

From: Eric Blake <eblake <at> redhat.com>
To: Stefano Lattarini <stefano.lattarini <at> gmail.com>
Cc: 8071 <at> debbugs.gnu.org, automake-patches <at> gnu.org,
	Reuben Thomas <rrt <at> sc3d.org>
Subject: Re: bug#8071: Please rename automake invocation node
Date: Fri, 30 Dec 2011 07:29:13 -0700

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

On 12/30/2011 07:07 AM, Stefano Lattarini wrote:

>> I'm not sure if putting the @anchor after the @node make a difference.
>> If the anchor takes the old name to the previous node, then we may want
>> to move the anchor to appear after the @node.
>>
> It's a pity that, with the current infrastructure, there now is viable way
> to test how a change done in the git repository will reflect on the
> on-line manual :-(

I'm assuming you meant:

s/now is/is no/

but there _is_ a way:

make html
$browser dox/automake.html/index.html

lets you browse the one-page-per-node html.  Also, looking in that
directory, I see doc/automake.html/Invoking-aclocal.html with contents:

<meta http-equiv="refresh" content="0;
url=Optional.html#Invoking%20aclocal">

which means the anchor got associated with the page Optional.html,
instead of the desired aclocal-Invocation.html.

So we _do_ need to make the swap.

-- 
Eric Blake   eblake <at> redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

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

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

From: Stefano Lattarini <stefano.lattarini <at> gmail.com>
To: Eric Blake <eblake <at> redhat.com>
Cc: 8071 <at> debbugs.gnu.org, automake-patches <at> gnu.org,
	Reuben Thomas <rrt <at> sc3d.org>
Subject: Re: bug#8071: Please rename automake invocation node
Date: Fri, 30 Dec 2011 18:17:07 +0100

Hi Eric.

On 12/30/2011 03:29 PM, Eric Blake wrote:
> [SNIP]
>
> So we _do_ need to make the swap.
> 
Thanks for your explanation and testing.  Here is the patch I'll push shortly
if there is no objection.

Regards,
  Stefano

-*-*-*-

From 34feafeec134a7bdc99d1b261fd97e6c0c5ab716 Mon Sep 17 00:00:00 2001
Message-Id: <34feafeec134a7bdc99d1b261fd97e6c0c5ab716.1325265215.git.stefano.lattarini <at> gmail.com>
From: Stefano Lattarini <stefano.lattarini <at> gmail.com>
Date: Fri, 30 Dec 2011 18:13:28 +0100
Subject: [PATCH] docs: fix a couple broken anchors

* doc/automake.texi: In previous commit v1.11-605-g5f71f2b (related
to automake bug#8071), we had renamed the chapters about aclocal
and automake invocation, and added anchors to the old names as not
to break hyperlinks to our on-line manual.  Unfortunately, these
anchors had been erroneously placed *before* the relevant `@node'
commands, instead that just after, so that they ended up pointing
to the wrong chapters.  Fix this.  Since we are at it, tweak the
wording of the comments to the anchors to better match that used
in the autoconf manual.

Report and suggestion by Eric Blake.
---
 doc/automake.texi |   12 ++++++------
 1 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/doc/automake.texi b/doc/automake.texi
index e155fd1..a690b67 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -2492,11 +2492,11 @@ with different flags.  In this instance, the names of the object files
 would be chosen by automake; they would be @file{false-true.o} and
 @file{true-true.o}. (The name of the object files rarely matters.)

-@c The anchor is required to avoid breaking existing web hyperlinks
-@c still using the old name of this node.
-@anchor{Invoking automake}
 @node automake Invocation
 @chapter Creating a @file{Makefile.in}
+@c This node used to be named "Invoking automake".  This @anchor
+@c allows old links to still work.
+@anchor{Invoking automake}

 @cindex Multiple @file{configure.ac} files
 @cindex Invoking @command{automake}
@@ -3108,11 +3108,11 @@ macros installed in a system-wide directory, @pxref{aclocal Invocation}).

 @end ftable

-@c The anchor is required to avoid breaking existing web hyperlinks
-@c still using the old name of this node.
-@anchor{Invoking aclocal}
 @node aclocal Invocation
 @section Auto-generating aclocal.m4
+@c This node used to be named "Invoking automake".  This @anchor
+@c allows old links to still work.
+@anchor{Invoking aclocal}

 @cindex Invocation of @command{aclocal}
 @cindex @command{aclocal}, Invocation
-- 
1.7.7.3

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

From: Stefano Lattarini <stefano.lattarini <at> gmail.com>
To: Eric Blake <eblake <at> redhat.com>
Cc: 8071 <at> debbugs.gnu.org, automake-patches <at> gnu.org,
	Reuben Thomas <rrt <at> sc3d.org>
Subject: Re: bug#8071: Please rename automake invocation node
Date: Sat, 31 Dec 2011 09:07:55 +0100

On 12/30/2011 06:17 PM, Stefano Lattarini wrote:
> On 12/30/2011 03:29 PM, Eric Blake wrote:
>> [SNIP]
>>
>> So we _do_ need to make the swap.
>>
> Thanks for your explanation and testing.  Here is the patch I'll
> push shortly if there is no objection.
> 
Pushed now.

Regards,
  Stefano

Previous Next

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