Re: automake 1.9.5 minor doc updates

[Alexandre Duret-Lutz]

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

 Karl> In reading through some of the current automake manual, I found a few
 Karl> small items, see diff below.  

Thanks.  Most of these were already fixed in CVS.  
I'm installing the patch below on HEAD and branch-1-9.

Note that I prefer to point people to
http://www.gnu.org/software/texinfo/ instead of the viewcvs url
you suggested because 
  1) that is the URL embedded in the file and
  2) this way we don't have to update the Automake manual each time
     texinfo.tex is moved to another place (as just happened)

The texinfo.tex link at http://www.gnu.org/software/texinfo/
still points to ...gnulib/config/texinfo.tex, which no longer
exists.

 Karl> The Hello code is in flux, so I didn't bother to update
 Karl> that.

Don't.  As we have already discussed this section will disappear.

 Karl> Node: Uniform
 Karl> For instance, installation of HTML files is part of Automake, you
 Karl> could use this to install raw HTML documentation:
 Karl> htmldir = $(prefix)/html
 Karl> html_DATA = automake.html

 Karl> I don't understand this.  

I bet you don't.  It used to read ``For instance, until
installation of ...''.  Somehow ``until'' disappeared.

 Karl> Does the user really have to define htmldir?

Presently, yes.

 Karl> Isn't that defined by default now?  

Only CVS Autoconf defines it.  But that's enough to warrant a
rewrite of this example, so it doesn't confuse people when
Autoconf 2.60 is eventually released.


2005-03-30  Alexandre Duret-Lutz  <address@hidden>

        * doc/automake.texi (Uniform): Use xmldir instead of htmldir as
        example, since the GCS now define htmldir.
        (Auxiliary Programs): Mention config-ml.in and symlink-tree.
        Give a URL for texinfo.tex.
        (Public macros): Sort alphabetically, and move obsolete macros...
        (Obsolete macros): ... here.
        Prompted by Karl Berry.

Index: doc/automake.texi
===================================================================
RCS file: /cvs/automake/automake/doc/automake.texi,v
retrieving revision 1.110
diff -u -r1.110 automake.texi
--- doc/automake.texi   29 Mar 2005 23:41:28 -0000      1.110
+++ doc/automake.texi   30 Mar 2005 19:44:44 -0000
@@ -149,6 +149,7 @@
 Autoconf macros supplied with Automake
 
 * Public macros::               Macros that you can use.
+* Obsolete macros::             Macros that you should stop using.
 * Private macros::              Macros that you should not use.
 
 Directories
@@ -587,14 +588,12 @@
 is valid if a variable of the same name with @samp{dir} appended is
 defined (e.g., @samp{zardir}).
 
address@hidden HTML installation, example
-
-For instance, installation of HTML files is part of Automake, you could
-use this to install raw HTML documentation:
+For instance, the following snippet will install @file{file.xml} into
address@hidden(datadir)/xml}.
 
 @example
-htmldir = $(prefix)/html
-html_DATA = automake.html
+xmldir = $(datadir)/xml
+xml_DATA = file.xml
 @end example
 
 @cindex @samp{noinst_} primary prefix, definition
@@ -696,6 +695,11 @@
 @file{Makefile} can do its work properly.  There are a fairly large
 number of them, and we list them here.
 
+Although all of these files are distributed and installed with
+Automake, a couple of them are maintained separately.  The Automake
+copies are updated before each release, but we mention the original
+source in case you need more recent versions.
+
 @table @code
 @item ansi2knr.c
 @itemx ansi2knr.1
@@ -714,10 +718,15 @@
 support new architectures and fix probes broken by changes in new
 kernel versions.  Each new release of Automake comes with up-to-date
 copies of these programs.  If your copy of Automake is getting old,
-You are encouraged to fetch the latest versions of these files from
+you are encouraged to fetch the latest versions of these files from
 @url{http://savannah.gnu.org/cvs/?group=config} before making a
 release.
 
address@hidden config-ml.in
+This file is not a program, it is a @file{configure} fragment used for
+multilib support (@pxref{Multilibs}).  This file is maintained in the
+GCC tree at @url{http://gcc.gnu.org/cvs.html}.
+
 @item depcomp
 This program understands how to run a compiler so that it will
 generate not only the desired output but also dependency information
@@ -753,9 +762,17 @@
 @item py-compile
 This is used to byte-compile Python scripts.
 
address@hidden symlink-tree
+This program duplicates a tree of directories, using symbolic links
+instead of copying files.  Such operation is performed when building
+multilibs (@pxref{Multilibs}).  This file is maintained in the GCC
+tree at @url{http://gcc.gnu.org/cvs.html}.
+
 @item texinfo.tex
-Not a program, this file is required for @samp{make dvi}, @samp{make ps}
-and @samp{make pdf} to work when Texinfo sources are in the package.
+Not a program, this file is required for @samp{make dvi}, @samp{make
+ps} and @samp{make pdf} to work when Texinfo sources are in the
+package.  The latest version can be downloaded from
address@hidden://www.gnu.org/software/texinfo/}.
 
 @item ylwrap
 This program wraps @command{lex} and @command{yacc} and ensures that,
@@ -2317,6 +2334,7 @@
 
 @menu
 * Public macros::               Macros that you can use.
+* Obsolete macros::             Macros that you should stop using.
 * Private macros::              Macros that you should not use.
 @end menu
 
@@ -2326,21 +2344,6 @@
 @subsection Public macros
 
 @table @code
address@hidden AM_CONFIG_HEADER
address@hidden AM_CONFIG_HEADER
-Automake will generate rules to automatically regenerate the config
-header.  This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
-today (@pxref{Optional}).
-
address@hidden AM_ENABLE_MULTILIB
address@hidden AM_ENABLE_MULTILIB
-This is used when a ``multilib'' library is being built.  The first
-optional argument is the name of the @file{Makefile} being generated; it
-defaults to @samp{Makefile}.  The second option argument is used to find
-the top source directory; it defaults to the empty string (generally
-this should not be used unless you are familiar with the internals).
address@hidden
-
 @item AM_C_PROTOTYPES
 @acindex AM_C_PROTOTYPES
 @vindex ANSI2KNR
@@ -2351,12 +2354,14 @@
 @samp{_} and @code{ANSI2KNR} to @samp{./ansi2knr}.  Automake uses these
 values to implement automatic de-ANSI-fication.
 
address@hidden AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
address@hidden AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
-If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
-define @code{GWINSZ_IN_SYS_IOCTL}.  Otherwise @code{TIOCGWINSZ} can be
-found in @file{<termios.h>}.  This macro is obsolete, you should
-use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead.
address@hidden AM_ENABLE_MULTILIB
address@hidden AM_ENABLE_MULTILIB
+This is used when a ``multilib'' library is being built.  The first
+optional argument is the name of the @file{Makefile} being generated; it
+defaults to @samp{Makefile}.  The second option argument is used to find
+the top source directory; it defaults to the empty string (generally
+this should not be used unless you are familiar with the internals).
address@hidden
 
 @item AM_INIT_AUTOMAKE([OPTIONS])
 @itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
@@ -2469,15 +2474,6 @@
 @code{GCJ} and @code{GCJFLAGS}.  @command{gcj} is the Java front-end to the
 GNU Compiler Collection.
 
address@hidden AM_SYS_POSIX_TERMIOS
address@hidden AM_SYS_POSIX_TERMIOS
address@hidden POSIX termios headers
address@hidden termios POSIX headers
-Check to see if POSIX termios headers and functions are available on the
-system.  If so, set the shell variable @code{am_cv_sys_posix_termios} to
address@hidden  If not, set the variable to @samp{no}.  This macro is obsolete,
-you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead.
-
 @item AM_WITH_DMALLOC
 @acindex AM_WITH_DMALLOC
 @cindex @command{dmalloc}, support for
@@ -2502,6 +2498,45 @@
 
 @end table
 
+
address@hidden Obsolete macros
address@hidden Obsolete macros
address@hidden obsolete macros
address@hidden autoupdate
+
+Although using some of the following macros was required in past
+releases, you should not used any of them in new code.  Running
address@hidden should adjust your @file{configure.ac}
+automatically (@pxref{autoupdate Invocation, , Using
address@hidden to Modernize @file{configure.ac}, autoconf, The
+Autoconf Manual}).
+
address@hidden @code
address@hidden AM_CONFIG_HEADER
address@hidden AM_CONFIG_HEADER
+Automake will generate rules to automatically regenerate the config
+header.  This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
+today (@pxref{Optional}).
+
address@hidden AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
address@hidden AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
+If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
+define @code{GWINSZ_IN_SYS_IOCTL}.  Otherwise @code{TIOCGWINSZ} can be
+found in @file{<termios.h>}.  This macro is obsolete, you should
+use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead.
+
address@hidden AM_SYS_POSIX_TERMIOS
address@hidden AM_SYS_POSIX_TERMIOS
address@hidden POSIX termios headers
address@hidden termios POSIX headers
+Check to see if POSIX termios headers and functions are available on the
+system.  If so, set the shell variable @code{am_cv_sys_posix_termios} to
address@hidden  If not, set the variable to @samp{no}.  This macro is obsolete,
+you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead.
+
address@hidden table
+
+
 @node Private macros
 @subsection Private macros
 
-- 
Alexandre Duret-Lutz