generated texinfo files

[Alexandre Duret-Lutz]

This is a first step towards supporting generated Texinfo files.  In
current Automake this is tricky because Automake scans the file for
various pieces of information (@setfilename being the most important).

Therefore this patch adds support for ``mumble_FILENAME = mumble.info'' 
to replace address@hidden''.  This was initially
suggested here:
  http://sources.redhat.com/ml/bug-automake/2001/msg00423.html
and discussed here:
  http://sources.redhat.com/ml/automake/2001-12/msg00080.html

I think any implementation making a decision based on file
existance (e.g., if the mumble.texi is not present, assume it
will contain @setfilename{mumble.info}) is a bad idea because it
means unstable output: if Automake is latter run when the file
exists, the Makefile.in could be different the next time
Automake is run (e.g. Automake may discover new indices to
clean).  It seems better to rely on the presence of some
variable in Makefile.am (here _FILENAME), and NOT scan the
Texinfo source when this variable is given.

Note this is only a first step.  The next one would be to
support ``nodist_'' for Texinfo files.  It would also be nice
that rules for version.texi be output when version.texi appears
in the dependencies of mumble.texi (e.g. ``mumble_TEXINFOS =
a.texi version.texi'').

What do yo think?


2002-06-02  Alexandre Duret-Lutz  <address@hidden>

        Honor `_FILENAME' variables for Texinfo files, to help with
        generated Texinfo sources.

        * automake.in (texinfo_build_clean_files): New function, extracted
        from scan_texinfo_file.
        (scan_texinfo_file): Use it.  Don't try to be overly smart at cleaning
        indices: ignore synindex and syncodeindex, clean all know index
        files, even if we are not sure they are created.
        (get_texinfo_deps): New function.
        (handle_texinfo_helper): Call get_texinfo_deps instead of
        scan_texinfo_file.
        * automake.texi (Texinfo): Document _FILENAME.
        * tests/Makefile.am (TESTS): Add texinfo11.test.
        * tests/texinfo11.test: New file.
        Suggested by Peter Muir and Bruce Korb.

Index: NEWS
===================================================================
RCS file: /cvs/automake/automake/NEWS,v
retrieving revision 1.179
diff -u -r1.179 NEWS
--- NEWS        17 May 2002 10:49:52 -0000      1.179
+++ NEWS        2 Jun 2002 19:11:18 -0000
@@ -1,4 +1,8 @@
 New in 1.6a:
+* If `mumble.texi' is a generated Texinfo file, use
+  `mumble_FILENAME = mumble.info' to prevent Automake from reading
+  `mumble.texi' and thus allowing you to run automake even if
+  `mumble.texi' does not exist.
 * `make distcheck' will enforce DESTDIR support by attempting
   a DESTDIR install.
 * `+=' can be used in conditionals, even if the augmented variable
Index: automake.in
===================================================================
RCS file: /cvs/automake/automake/automake.in,v
retrieving revision 1.1299
diff -u -r1.1299 automake.in
--- automake.in 20 May 2002 20:42:01 -0000      1.1299
+++ automake.in 2 Jun 2002 19:11:41 -0000
@@ -3066,6 +3066,31 @@
 }
 
 
+# @CLEAN_FILES
+# &texinfo_build_clean_files ($FILENAME,
+#                             address@hidden, address@hidden)
+# ---------------------------------------------------------------------
+# $FILENAME the texinfo file that will be compiled
+# address@hidden a set of additional suffixes (without the leading dot)
+#    that might be generated as a side-effect of compilation of $FILENAME
+# address@hidden a set of suffixes that will not be generated from
+#    $FILENAME.
+sub texinfo_build_clean_files ($;address@hidden@)
+{
+    my ($filename, $extra_suffixes, $syncode_indexes) = (@_, [], []);
+
+    # These are always created, no matter whether indexes are used or not.
+    my @clean_suffixes = qw(aux dvi log ps toc
+                           cp fn ky vr tp pg); # grep new.*index texinfo.tex
+    push @clean_suffixes, @$extra_suffixes;
+
+    my $infobase = basename $filename;
+    $infobase =~ s/\.te?xi(nfo)?$//;
+    my %clean_files = map { +"$infobase.$_" => 1 } @clean_suffixes;
+    grep { delete $clean_files{"$infobase.$_"} } @$syncode_indexes;
+    return sort keys %clean_files;
+}
+
 # ($OUTFILE, $VFILE, @CLEAN_FILES)
 # &scan_texinfo_file ($FILENAME)
 # ------------------------------
@@ -3076,9 +3101,8 @@
 {
     my ($filename) = @_;
 
-    # These are always created, no matter whether indexes are used or not.
-    my @clean_suffixes = qw(aux dvi log ps toc
-                           cp fn ky vr tp pg); # grep new.*index texinfo.tex
+    # Extra suffixes to clean.
+    my @clean_suffixes = ();
 
     # There are predefined indexes which don't follow the regular rules.
     my %predefined_index = qw(c cps
@@ -3156,13 +3180,41 @@
        return;
       }
 
-    my $infobase = basename ($filename);
-    $infobase =~ s/\.te?xi(nfo)?$//;
-    my %clean_files = map { +"$infobase.$_" => 1 } @clean_suffixes;
-    grep { delete $clean_files{"$infobase.$_"} } @syncodeindexes;
-    return ($outfile, $vfile, (sort keys %clean_files));
+    my @clean_files =
+       texinfo_build_clean_files $filename, @clean_suffixes, @syncodeindexes;
+    return ($outfile, $vfile, @clean_files);
 }
 
+# ($OUTFILE, $VFILE, @CLEAN_FILES)
+# &scan_texinfo_deps ($FILENAME, $CANONICAL)
+# ------------------------------------------
+# This is a wrapper around &scan_texinfo_file, that avoid calling
+# scan_texinfo_file("mumble.texi") if mumble_FILENAME is defined.
+#
+# $OUTFILE is the name of the info file produced by $FILENAME.
+# $VFILE is the name of the version.texi file used (empty if none).
+# @CLEAN_FILES is the list of by products (indexes etc.)
+sub scan_texinfo_deps($$)
+{
+    my ($filename, $canonical) = @_;
+
+    # ${CANONICAL}_FILENAME is used when $FILENAME is derived from
+    # other files.  Never scan $FILENAME when this is defined, even
+    # if the file exists:
+    #   These files may be present or not (depending whether they
+    #   have been generated or cleaned), but we should always
+    #   generate the same Makefile.in.
+    if (variable_defined ($canonical . "_FILENAME"))
+    {
+       # Assume version.texi is not needed.  Clear
+       # the most common index files and let the user clean any
+       # custom index file itself.
+       my @common_indices = qw/cps fns kys vrs tps pgs/;
+       return ("\$(${canonical}_FILENAME)", undef,
+               texinfo_build_clean_files ($filename, @common_indices));
+    }
+    return scan_texinfo_file $filename;
+}
 
 # ($DO-SOMETHING, $TEXICLEANS)
 # handle_texinfo_helper ()
@@ -3205,13 +3257,15 @@
        }
        $texi_suffixes{$1} = 1;
 
-       # If 'version.texi' is referenced by input file, then include
-       # automatic versioning capability.
+       my $canonical = &canonicalize ($infobase);
+
        my ($out_file, $vtexi, @clean_files) =
-         &scan_texinfo_file ("$relative_dir/$info_cursor")
+         &scan_texinfo_deps ("$relative_dir/$info_cursor", $canonical)
            or next;
        push (@texi_cleans, @clean_files);
 
+       # If 'version.texi' is referenced by input file, then include
+       # automatic versioning capability.
        if ($vtexi)
        {
            &am_error ("`$vtexi', included in `$info_cursor', also included in 
`$versions{$vtexi}'")
@@ -3261,7 +3315,6 @@
        # work if the target has it and the dependency doesn't.
        push (@texi_deps, '$(srcdir)/' . $vtexi) if $vtexi;
 
-       my $canonical = &canonicalize ($infobase);
        if (variable_defined ($canonical . "_TEXINFOS"))
        {
            push (@texi_deps, '$(' . $canonical . '_TEXINFOS)');
Index: automake.texi
===================================================================
RCS file: /cvs/automake/automake/automake.texi,v
retrieving revision 1.276
diff -u -r1.276 automake.texi
--- automake.texi       6 May 2002 06:51:05 -0000       1.276
+++ automake.texi       2 Jun 2002 19:12:00 -0000
@@ -3453,6 +3453,8 @@
 @vindex TEXINFOS
 @vindex info_TEXINFOS
 
address@hidden @file{version.texi}
+
 @cindex Texinfo macro, VERSION
 @cindex Texinfo macro, UPDATED
 @cindex Texinfo macro, EDITION
@@ -3493,6 +3495,8 @@
 Texinfo file that matches @samp{vers*.texi} just as an automatically
 generated version file.
 
address@hidden @code{MAKEINFO}
+
 When an info file is rebuilt, the program named by the @code{MAKEINFO}
 variable is used to invoke it.  If the @code{makeinfo} program is found
 on the system then it will be used by default; otherwise @code{missing}
@@ -3505,6 +3509,8 @@
 @vindex MAKEINFOFLAGS
 @vindex AM_MAKEINFOFLAGS
 
address@hidden @code{@@include}s
+
 Sometimes an info file actually depends on more than one @file{.texi}
 file.  For instance, in GNU Hello, @file{hello.texi} includes the file
 @file{gpl.texi}.  You can tell Automake about these dependencies using
@@ -3517,6 +3523,11 @@
 hello_TEXINFOS = gpl.texi
 @end example
 
+You don't need to mention @file{version.texi} explicitely in such
+dependencies.
+
address@hidden @file{texinfo.tex}
+
 @cindex texinfo.tex
 
 By default, Automake requires the file @file{texinfo.tex} to appear in
@@ -3545,6 +3556,8 @@
 @code{TEXINFO_TEX} is preferable, however, because that allows the
 @code{dvi} target to still work.
 
address@hidden @code{install-info}
+
 @cindex Target, install-info
 @cindex Target, noinstall-info
 @cindex install-info target
@@ -3557,6 +3570,51 @@
 use this.  By default, info pages are installed by @samp{make install}.
 This can be prevented via the @code{no-installinfo} option.
 
address@hidden Generated Texinfo files.
address@hidden Generated Texinfo files
address@hidden _FILENAME
address@hidden @@setfilename
+
+Handling generated Texinfo files is a bit trickier than ordinary
+hand-crafted Texinfo files.  This is so because Automake normally
+derives some rule construction information from the Texinfo source
+itself.  For instance it scan Texinfo source for things like
address@hidden@@setfilemame}, @file{version.texi}, or indices usage.
+
+However, in setups where Texinfo files are derived from other sources,
+these Texinfo files might not yet exist when Automake is run.
+Additional information must be explicitly supplied to Automake so it can
+output build rules for generated Texinfo files.
+
+The most important piece of information Automake needs is the argument
+of @code{@@setfilename} in @file{maude.texi}; you can set it using the
address@hidden variable.
+
+Using @code{maude_FILENAME} actually prevent Automake from reading
address@hidden, even if the file exists.  You will have to do
+yourself other things that can happen automatically when the Texinfo
+file is read, like deleting custom index files.  Similarly, Automake
+will not output a rule to create @file{version.texi}.
+
+Here is an example of setup for an generated @file{maude.texi}:
+
address@hidden
+info_TEXINFOS = maude.texi
+maude_FILENAME = maude.info
+
+maude.texi: maude.c
+        @i{command to build maude.texi}
+
+MAINTAINERCLEANFILES = maude.texi
+# Extra `index files' to clean.
+MOSTLYCLEANFILES = maude.mf maude.mc
address@hidden example
+
+Note that Automake always distributes Texinfo files.  There is no
+support for @code{nodist_info_TEXINFOS} (yet).  This is why the above
+example cleans @file{maude.texi} from @code{maintainer-clean}: it
+doesn't make much sense to @code{clean} or @code{distclean} a file which
+is distributed.
 
 @node Man pages,  , Texinfo, Documentation
 @section Man pages
Index: tests/Makefile.am
===================================================================
RCS file: /cvs/automake/automake/tests/Makefile.am,v
retrieving revision 1.400
diff -u -r1.400 Makefile.am
--- tests/Makefile.am   24 May 2002 10:36:18 -0000      1.400
+++ tests/Makefile.am   2 Jun 2002 19:12:00 -0000
@@ -357,6 +357,7 @@
 texinfo8.test \
 texinfo9.test \
 texinfo10.test \
+texinfo11.test \
 unused.test \
 vars.test \
 vartar.test \
Index: tests/texinfo11.test
===================================================================
RCS file: tests/texinfo11.test
diff -N tests/texinfo11.test
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ tests/texinfo11.test        2 Jun 2002 19:12:02 -0000
@@ -0,0 +1,46 @@
+#! /bin/sh
+
+# FIXME: Write something here.
+
+required=makeinfo
+. $srcdir/defs || exit 1
+
+set -e
+
+echo AC_OUTPUT >> configure.in
+
+cat > Makefile.am << 'END'
+info_TEXINFOS = generated.texi
+generated_FILENAME = generated.info
+
+generated.texi:
+       cp g $@
+
+EXTRA_DIST = g
+
+MAINTAINERCLEANFILES = generated.texi
+END
+
+cat > g << 'END'
+\input texinfo
address@hidden generated.info
address@hidden generated
address@hidden Top
+Hello walls.
+
address@hidden
+END
+
+
+$ACLOCAL
+$AUTOMAKE --add-missing
+$AUTOCONF
+./configure
+$MAKE
+test -f generated.texi
+test -f generated.info
+$MAKE maintainer-clean
+./configure
+$MAKE distcheck
+test -f generated.texi
+test -f generated.info

-- 
Alexandre Duret-Lutz