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
>From 5f71f2b5b631f59f9244ec2ef93d6705a76aa917 Mon Sep 17 00:00:00 2001
Message-Id: <5f71f2b5b631f59f9244ec2ef93d6705a76aa917.1325100516.git.stefano.lattar...@gmail.com>
From: Stefano Lattarini <stefano.lattar...@gmail.com>
Date: Wed, 28 Dec 2011 20:28:29 +0100
Subject: [PATCH] docs: fix paragraph names for automake and aclocal
invocations
All the other autotools entitle their invocation nodes
"autofoo Invocation", whereas automake used to call its
"Invoking Automake" and "Invoking aclocal". So let's
try to be more consistent.
This change is related to automake bug#8071.
Suggestion by Reuben Thomas and Eric Blake.
* doc/automake.texi (Invoking Automake): Node renamed ...
(automake Invocation): ... to this.
(Invoking aclocal): Node renamed ...
(aclocal Invocation): ... to this.
Add proper @anchor directives to avoid breaking existing web
hyperlinks still using the old names of the renamed nodes.
---
doc/automake.texi | 41 ++++++++++++++++++++++++-----------------
1 files changed, 24 insertions(+), 17 deletions(-)
diff --git a/doc/automake.texi b/doc/automake.texi
index 86879d1..bd8ffbe 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -45,8 +45,8 @@ section entitled ``GNU Free Documentation License.''
@dircategory Individual utilities
@direntry
-* aclocal-invocation: (automake)Invoking aclocal. Generating aclocal.m4.
-* automake-invocation: (automake)Invoking Automake. Generating Makefile.in.
+* aclocal-invocation: (automake)aclocal Invocation. Generating aclocal.m4.
+* automake-invocation: (automake)automake Invocation. Generating Makefile.in.
@end direntry
@titlepage
@@ -99,7 +99,7 @@ section entitled ``GNU Free Documentation License.''
* Autotools Introduction:: An Introduction to the Autotools
* Generalities:: General ideas
* Examples:: Some example packages
-* Invoking Automake:: Creating a Makefile.in
+* automake Invocation:: Creating a Makefile.in
* configure:: Scanning configure.ac, using aclocal
* Directories:: Declaring subdirectories
* Programs:: Building programs and libraries
@@ -178,7 +178,7 @@ Scanning @file{configure.ac}, using @command{aclocal}
* Requirements:: Configuration requirements
* Optional:: Other things Automake recognizes
-* Invoking aclocal:: Auto-generating aclocal.m4
+* aclocal Invocation:: Auto-generating aclocal.m4
* Macros:: Autoconf macros supplied with Automake
Auto-generating aclocal.m4
@@ -2492,13 +2492,17 @@ 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.)
-
-@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}
@cindex Multiple @file{configure.ac} files
@cindex Invoking @command{automake}
@cindex @command{automake}, invoking
+@cindex Invocation of @command{automake}
+@cindex @command{automake}, invocation
To create all the @file{Makefile.in}s for a package, run the
@command{automake} program in the top level directory, with no
@@ -2729,7 +2733,7 @@ easier. These macros can automatically be put into your
@menu
* Requirements:: Configuration requirements
* Optional:: Other things Automake recognizes
-* Invoking aclocal:: Auto-generating aclocal.m4
+* aclocal Invocation:: Auto-generating aclocal.m4
* Macros:: Autoconf macros supplied with Automake
@end menu
@@ -3099,16 +3103,19 @@ appear as dependencies in @file{Makefile} rules.
@code{m4_include} is seldom used by @file{configure.ac} authors, but
can appear in @file{aclocal.m4} when @command{aclocal} detects that
-some required macros come from files local to your package (as opposed
-to macros installed in a system-wide directory, @pxref{Invoking
-aclocal}).
+some required macros come from files local to your package (as opposed to
+macros installed in a system-wide directory, @pxref{aclocal Invocation}).
@end ftable
-
-@node Invoking aclocal
+@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
+@cindex Invocation of @command{aclocal}
+@cindex @command{aclocal}, Invocation
@cindex Invoking @command{aclocal}
@cindex @command{aclocal}, Invoking
@@ -3291,7 +3298,7 @@ All warnings are output by default.
@vindex WARNINGS
The environment variable @env{WARNINGS} is honored in the same
-way as it is for @command{automake} (@pxref{Invoking Automake}).
+way as it is for @command{automake} (@pxref{automake Invocation}).
@end table
@@ -9523,7 +9530,7 @@ will be suppressed.
@cindex Option, @option{-W@var{category}}
@cindex Option, @option{--warnings=@var{category}}
These options behave exactly like their command-line counterpart
-(@pxref{Invoking Automake}). This allows you to enable or disable some
+(@pxref{automake Invocation}). This allows you to enable or disable some
warning categories on a per-file basis. You can also setup some warnings
for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
in your @file{configure.ac}.
@@ -10138,7 +10145,7 @@ variable expansion @samp{$(@var{var1}$(V))}. Do not use the
@command{make} implementations that do not support it. The
@option{silent-rules} option turns off warnings about recursive variable
expansion, which are in turn enabled by @option{-Wportability}
-(@pxref{Invoking Automake}).
+(@pxref{automake Invocation}).
@vindex @code{AM_V_GEN}
@vindex @code{AM_V_at}
@@ -10358,7 +10365,7 @@ These overriding semantics make it possible to fine tune some default
settings of Automake, or replace some of its rules. Overriding
Automake rules is often inadvisable, particularly in the topmost
directory of a package with subdirectories. The @option{-Woverride}
-option (@pxref{Invoking Automake}) comes in handy to catch overridden
+option (@pxref{automake Invocation}) comes in handy to catch overridden
definitions.
Note that Automake does not make any distinction between rules with
@@ -10806,7 +10813,7 @@ autoreconf -vfi
@end example
The use of @option{--force-missing} ensures that auxiliary tools will be
-overridden by new versions (@pxref{Invoking Automake}).
+overridden by new versions (@pxref{automake Invocation}).
It is important to regenerate all these files each time Automake is
upgraded, even between bug fixes releases. For instance, it is not
--
1.7.7.3
