Re: AM_LIBTOOLFLAGS, maude_LIBTOOLFLAGS, and LIBTOOLFLAGS

[Alexandre Duret-Lutz]

[Quoting your entire mail for the benefit of other automake-patches readers.]

>>> "Karl" == Karl Berry <address@hidden> writes:

 Karl> Although the changes you made are improvements, I have some suggestions.
 Karl> In general, it's good to avoid @ref.

 Karl> -(@pxref{Local Macros} for an example.)  Any macro which is found in a
 Karl> +(See @ref{Local Macros} for an example.)  Any macro which is found in a

 Karl> (@xref{Local Macros}, for an example.)
 Karl> [When the xref starts a whole sentence, @xref works best.]

 Karl> -tune the default, @xref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
 Karl> +tune the default, @ref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}

 Karl> @pxref{AC_PROG_TOOL, ...}.  Although I guess I still didn't make Texinfo
 Karl> manual doesn' exactly clear on this, there's nothing wrong with stuff
 Karl> *preceding* the pxref in parens; it's stuff following that is weird.

 Karl> The problem with @ref here is that in the TeX output, it will say:
 Karl> tune the default, Section M.N (The AC_PROG_...)
 Karl> without any "see".

 Karl> Also, the difference between AC_PROG_LIBTOOL and 
 Karl> The AC_PROG_LIBTOOL macro seems basically nil to me.  I usually try to

 Karl> -used, see @xref{Sources}.
 Karl> +used, see @ref{Sources}.

 Karl> Although the @ref is ok here, I think it's a little easier for the human
 Karl> reader to have parens instead of a second phrase after a comma:
 Karl> used (@pxref{Sources}).

 Karl> -to make automatic dependency tracking work @xref{Dependencies}.  In this
 Karl> +to make automatic dependency tracking work @ref{Dependencies}.  In this

 Karl> This will have the same TeX problem as above.
 Karl> ... work (@pxref{Dependencies}). ...

 Karl> Cheers,
 Karl> karl

 Karl> P.S. I hate the complex mess of Texinfo xref commands.  

And I thought I got it right... Thanks a lot!  I've installed the
appended patch.

2004-12-18  Alexandre Duret-Lutz  <address@hidden>

        * doc/automake.texi: Fix more misuses of @xref and @pxref, including
        some of the "correction" below.  Thanks to Karl Berry.

Index: doc/automake.texi
===================================================================
RCS file: /cvs/automake/automake/doc/automake.texi,v
retrieving revision 1.44.2.28
diff -u -r1.44.2.28 automake.texi
--- doc/automake.texi   17 Dec 2004 23:47:08 -0000      1.44.2.28
+++ doc/automake.texi   18 Dec 2004 09:30:59 -0000
@@ -1457,9 +1457,9 @@
 
 @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, see
address@hidden aclocal}).
+some required macros come from files local to your package (as opposed
+to macros installed in a system-wide directory, @pxref{Invoking
+aclocal}).
 
 @end ftable
 
@@ -1503,7 +1503,7 @@
 and uses @code{m4_include} instead of copying it into
 @file{aclocal.m4}.  This makes the package smaller, eases dependency
 tracking, and cause the file to be distributed automatically.
-(See @ref{Local Macros} for an example.)  Any macro which is found in a
+(@xref{Local Macros}, for an example.)  Any macro which is found in a
 system-wide directory, or via an absolute search path will be copied.
 So use @code{-I `pwd`/reldir} instead of @code{-I reldir} whenever
 some relative directory need to be considered outside the package.
@@ -3015,14 +3015,14 @@
 @cindex suffix @file{.la}, defined
 @cindex @file{.la} suffix, defined
 
-Libtool abstracts shared and static libraries into a unified
-concept henceforth called @dfn{libtool libraries}.  Libtool libraries
-are files using the @file{.la} suffix, and can designate a static
-library, a shared library, or maybe both.  Their exact nature cannot
-be determined until @file{./configure} is run: not all platforms
-support all kinds of libraries, and users can explicitly select which
+Libtool abstracts shared and static libraries into a unified concept
+henceforth called @dfn{libtool libraries}.  Libtool libraries are
+files using the @file{.la} suffix, and can designate a static library,
+a shared library, or maybe both.  Their exact nature cannot be
+determined until @file{./configure} is run: not all platforms support
+all kinds of libraries, and users can explicitly select which
 libraries should be built.  (However the package's maintainers can
-tune the default, @ref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
+tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
 macro, libtool, The Libtool Manual}.)
 
 @cindex suffix @file{.lo}, defined
@@ -3265,7 +3265,7 @@
 
 @code{EXTRA_*_SOURCES} variables are used to keep track of source
 files that might be compiled (this is mostly useful when doing
-conditional compilation using @code{AC_SUBST}, see @ref{Conditional
+conditional compilation using @code{AC_SUBST}, @pxref{Conditional
 Libtool Sources}), and the @code{nodist_} prefix means the listed
 sources are not to be distributed (@pxref{Program and Library
 Variables}).  In effect the file @file{dummy.cxx} does not need to
@@ -4441,7 +4441,7 @@
 languages, support for which will be improved based on user demand.
 
 Some limited support for adding your own languages is available via the
-suffix rule handling; see @ref{Suffixes}.
+suffix rule handling (@pxref{Suffixes}).
 
 
 @node ANSI
@@ -4756,7 +4756,7 @@
 @samp{nodist_} prefix as in @code{nodist_include_HEADERS} or
 @code{nodist_prog_SOURCES}.  If these generated headers are needed
 during the build, you must also ensure they exist before they are
-used, see @ref{Sources}.
+used (@pxref{Sources}).
 
 
 @node Data
@@ -6327,10 +6327,11 @@
 @item @code{no-dependencies}
 @cindex Option, @code{no-dependencies}
 @opindex no-dependencies
-This is similar to using @samp{--include-deps} on the command line, but
-is useful for those situations where you don't have the necessary bits
-to make automatic dependency tracking work @ref{Dependencies}.  In this
-case the effect is to effectively disable automatic dependency tracking.
+This is similar to using @samp{--include-deps} on the command line,
+but is useful for those situations where you don't have the necessary
+bits to make automatic dependency tracking work
+(@pxref{Dependencies}).  In this case the effect is to effectively
+disable automatic dependency tracking.
 
 @item @code{no-dist}
 @cindex Option, @code{no-dist}
@@ -7934,7 +7935,7 @@
 (@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
 and @code{mumble_CPPFLAGS} is the variable specific to the
 @code{mumble} target (we call this a per-target variable,
-see @ref{Program and Library Variables}).
address@hidden and Library Variables}).
 
 Automake always uses two of these variables when compiling C sources
 files.  When compiling an object file for the @code{mumble} target,
@@ -8201,7 +8202,7 @@
 We recommend against this, because this is error prone.  For instance
 if you add such a rule to the first example, it will break the day you
 decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
-compiled as @file{foo.o} instead of @file{foo-foo.o}, see @ref{renamed
+compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{renamed
 objects}).  Also in order to support dependency tracking, the two
 @file{.o}/@file{.obj} extensions, and all the other flags variables
 involved in a compilation, you will end up modifying a copy of the
@@ -8601,7 +8602,7 @@
 distributed should appear in @code{DIST_SUBDIRS}, but the manual
 describes this as a temporary ugly hack (today extra directories should
 also be listed in @code{EXTRA_DIST}, and @code{DIST_SUBDIRS} is used
-for another purpose, see @ref{Conditional Subdirectories}).
+for another purpose, @pxref{Conditional Subdirectories}).
 
 @item 1995-11-26 Automake 0.21
 


-- 
Alexandre Duret-Lutz