Re: Texinfos handling

[Akim Demaille]

 Akim> I stumble on a simple question: what is the correct style
 Akim> for function calls?  I see there are still many
 Akim> &define_variable, where I would write define_variable
 Akim> (cleaner, enables proto checking, but less Emacs
 Akim> friendly, and therefore slightly less colorful).  Is
 Akim> there a guide line?

 > No, but maybe we should write one down? 

Agreed.

 > What do you prefer?  My opinion is that we should never use &,
 > unless necessary.  & disables prototype checking; while this is
 > convenient in some places, this sounds like a bad default.

Same here!

I'm installing the following (diff -w).

Index: ChangeLog
from  Akim Demaille  <address@hidden>

        * automake.in (&scan_texinfo_file, &output_texinfo_build_rules,
        (&handle_texinfo_helper, &handle_texinfo): Formatting changes.
        Prototype properly.
        Don't use & when calling functions.

Index: automake.in
===================================================================
RCS file: /cvs/automake/automake/automake.in,v
retrieving revision 1.1475
diff -u -u -u -w -r1.1475 automake.in
--- automake.in 2 Jul 2003 23:30:56 -0000 1.1475
+++ automake.in 4 Jul 2003 08:35:48 -0000
@@ -2993,13 +2993,19 @@
 }
 
 
+
+
+## ------------------------ ##
+## Handling Texinfo files.  ##
+## ------------------------ ##
+
 # ($OUTFILE, $VFILE, @CLEAN_FILES)
 # &scan_texinfo_file ($FILENAME)
 # ------------------------------
-# $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_file
+# $OUTFILE     - name of the info file produced by $FILENAME.
+# $VFILE       - name of the version.texi file used (undef if none).
+# @CLEAN_FILES - list of byproducts (indexes etc.)
+sub scan_texinfo_file ($)
 {
     my ($filename) = @_;
 
@@ -3008,8 +3014,8 @@
     # are only created when they are used.  We used to scan $FILENAME
     # for their use, but that is not enough: they could be used in
     # included files.  We can't scan included files because we don't
-    # know the include path.  Therefore we always erase these files,
-    # no matter whether they are used or not.
+  # know the include path.  Therefore we always erase these files, no
+  # matter whether they are used or not.
     #
     # (tmp is only created if an @macro is used and a certain e-TeX
     # feature is not available.)
@@ -3043,8 +3049,8 @@
             return;
           }
       }
-      # A "version.texi" file is actually any file whose name
-      # matches "vers*.texi".
+      # A "version.texi" file is actually any file whose name matches
+      # "vers*.texi".
       elsif (/address@hidden(vers[^.]*\.texi)\s*$/)
       {
         $vfile = $1;
@@ -3080,6 +3086,7 @@
            map { "$infobase.$_" } (sort keys %clean_suffixes));
 }
 
+
 # ($DIRSTAMP, @CLEAN_FILES)
 # output_texinfo_build_rules ($SOURCE, $DEST, @DEPENDENCIES)
 # ----------------------------------------------------------
@@ -3097,15 +3104,15 @@
   $ssfx ||= "";
   $dsfx ||= "";
 
-  # We can output two kinds of rules: the "generic" rules
-  # use Make suffix rules and are appropritate when
-  # $source and $dest lie in the current directory; the "specifix"
-  # rules is needed in the other case.
+  # We can output two kinds of rules: the "generic" rules use Make
+  # suffix rules and are appropritate when $source and $dest lie in
+  # the current directory; the "specifix" rules is needed in the other
+  # case.
   #
-  # The former are output only once (this is not really apparent
-  # here, but just remember that some logic deeper in Automake will
-  # not output the same rule twice); while the later need to be output
-  # for each Texinfo source.
+  # The former are output only once (this is not really apparent here,
+  # but just remember that some logic deeper in Automake will not
+  # output the same rule twice); while the later need to be output for
+  # each Texinfo source.
   my $generic;
   my $makeinfoflags;
   my $sdir = dirname $source;
@@ -3120,22 +3127,25 @@
       $makeinfoflags = "-I $sdir -I \$(srcdir)/$sdir";
     }
 
-  # We cannot use a suffix rule to build info files with
-  # an empty extension.  Otherwise we would output a single suffix
-  # inference rule, with separate dependencies, as in
+  # We cannot use a suffix rule to build info files with an empty
+  # extension.  Otherwise we would output a single suffix inference
+  # rule, with separate dependencies, as in
+  # 
   #    .texi:
   #           $(MAKEINFO) ...
   #    foo.info: foo.texi
-  # which confuse Solaris make.  (See the Autoconf manual for details.)
-  # Therefore we use a specific rule in this case.  This applies
-  # to info files only (dvi and pdf files always have an extension).
+  # 
+  # which confuse Solaris make.  (See the Autoconf manual for
+  # details.)  Therefore we use a specific rule in this case.  This
+  # applies to info files only (dvi and pdf files always have an
+  # extension).
   my $generic_info = ($generic && $dsfx) ? 1 : 0;
 
   # If the resulting file lie into a subdirectory,
   # make sure this directory will exist.
   my $dirstamp = require_build_directory_maybe ($dest);
 
-  $output_rules .= &file_contents ('texibuild',
+  $output_rules .= file_contents ('texibuild',
                                   new Automake::Location,
                                    GENERIC       => $generic,
                                    GENERIC_INFO  => $generic_info,
@@ -3157,7 +3167,7 @@
 # handle_texinfo_helper ()
 # ------------------------
 # Handle all Texinfo source; helper for handle_texinfo
-sub handle_texinfo_helper
+sub handle_texinfo_helper ()
 {
     reject_var 'TEXINFOS', "`TEXINFOS' is an anachronism; use `info_TEXINFOS'";
     reject_var 'html_TEXINFOS', "HTML generation not yet supported";
@@ -3189,14 +3199,14 @@
        # If 'version.texi' is referenced by input file, then include
        # automatic versioning capability.
        my ($out_file, $vtexi, @clean_files) =
-         &scan_texinfo_file ("$relative_dir/$info_cursor")
+       scan_texinfo_file ("$relative_dir/$info_cursor")
            or next;
        push (@texi_cleans, @clean_files);
 
        # If the Texinfo source is in a subdirectory, create the
-       # resulting info in this subdirectory.  If it is in the
-       # current directory, try hard to not prefix "./" because
-       # it breaks the generic rules.
+      # resulting info in this subdirectory.  If it is in the current
+      # directory, try hard to not prefix "./" because it breaks the
+      # generic rules.
        my $outdir = dirname ($info_cursor) . '/';
        $outdir = "" if $outdir eq './';
        $out_file =  $outdir . $out_file;
@@ -3206,11 +3216,11 @@
        @texi_deps = ();
        push (@texi_deps, "$outdir$vtexi") if $vtexi;
 
-       my $canonical = &canonicalize ($infobase);
+      my $canonical = canonicalize ($infobase);
        if (var ($canonical . "_TEXINFOS"))
        {
            push (@texi_deps, '$(' . $canonical . '_TEXINFOS)');
-           &push_dist_common ('$(' . $canonical . '_TEXINFOS)');
+         push_dist_common ('$(' . $canonical . '_TEXINFOS)');
        }
 
        my ($dirstamp, @cfiles) =
@@ -3259,7 +3269,7 @@
            {
                $conf_dir = '$(srcdir)/';
            }
-           $output_rules .= &file_contents ('texi-vers',
+         $output_rules .= file_contents ('texi-vers',
                                             new Automake::Location,
                                             TEXI     => $info_cursor,
                                             VTI      => $vti,
@@ -3276,12 +3286,12 @@
     if ($cygnus_mode)
     {
         $texinfodir = '$(top_srcdir)/../texinfo';
-       &define_variable ('TEXINFO_TEX', "$texinfodir/texinfo.tex", INTERNAL);
+      define_variable ('TEXINFO_TEX', "$texinfodir/texinfo.tex", INTERNAL);
     }
     elsif ($config_aux_dir_set_in_configure_in)
     {
         $texinfodir = $config_aux_dir;
-       &define_variable ('TEXINFO_TEX', "$texinfodir/texinfo.tex", INTERNAL);
+      define_variable ('TEXINFO_TEX', "$texinfodir/texinfo.tex", INTERNAL);
        $need_texi_file = 2; # so that we require_conf_file later
     }
     elsif (var ('TEXINFO_TEX'))
@@ -3289,14 +3299,14 @@
        # The user defined TEXINFO_TEX so assume he knows what he is
        # doing.
         $texinfodir = ('$(srcdir)/'
-                      . dirname (&variable_value ('TEXINFO_TEX')));
+                    . dirname (variable_value ('TEXINFO_TEX')));
     }
     else
     {
         $texinfodir = '$(srcdir)';
        $need_texi_file = 1;
     }
-    &define_variable ('am__TEXINFO_TEX_DIR', $texinfodir, INTERNAL);
+  define_variable ('am__TEXINFO_TEX_DIR', $texinfodir, INTERNAL);
 
     # The return value.
     my $texiclean = makefile_wrap ("", "\t  ", @texi_cleans);
@@ -3311,15 +3321,15 @@
        unshift (@all, '$(INFO_DEPS)');
     }
 
-    &define_variable ("INFO_DEPS", "@info_deps_list", INTERNAL);
-    &define_variable ("DVIS", "@dvis_list", INTERNAL);
-    &define_variable ("PDFS", "@pdfs_list", INTERNAL);
-    &define_variable ("PSS", "@pss_list", INTERNAL);
-    &define_variable ("HTMLS", "@htmls_list", INTERNAL);
+  define_variable ("INFO_DEPS", "@info_deps_list", INTERNAL);
+  define_variable ("DVIS", "@dvis_list", INTERNAL);
+  define_variable ("PDFS", "@pdfs_list", INTERNAL);
+  define_variable ("PSS", "@pss_list", INTERNAL);
+  define_variable ("HTMLS", "@htmls_list", INTERNAL);
     # This next isn't strictly needed now -- the places that look here
     # could easily be changed to look in info_TEXINFOS.  But this is
     # probably better, in case noinst_TEXINFOS is ever supported.
-    &define_variable ("TEXINFOS", &variable_value ('info_TEXINFOS'), INTERNAL);
+  define_variable ("TEXINFOS", variable_value ('info_TEXINFOS'), INTERNAL);
 
     # Do some error checking.  Note that this file is not required
     # when in Cygnus mode; instead we defined TEXINFO_TEX explicitly
@@ -3341,17 +3351,19 @@
     return (1, $texiclean);
 }
 
+
 # handle_texinfo ()
 # -----------------
 # Handle all Texinfo source.
-sub handle_texinfo
+sub handle_texinfo ()
 {
     my ($do_something, $texiclean) = handle_texinfo_helper ();
-    $output_rules .=  &file_contents ('texinfos',
+  $output_rules .=  file_contents ('texinfos',
                                      new Automake::Location,
                                      TEXICLEAN => $texiclean,
                                      'LOCAL-TEXIS' => $do_something);
 }
+
 
 # Handle any man pages.
 sub handle_man_pages
Index: HACKING
===================================================================
RCS file: /cvs/automake/automake/HACKING,v
retrieving revision 1.15
diff -u -u -u -w -r1.15 HACKING
--- HACKING 20 Sep 2002 17:17:01 -0000 1.15
+++ HACKING 4 Jul 2003 08:35:48 -0000
@@ -76,6 +76,12 @@
   default), and other portions using the GNU style (cperl-mode's
   default).  Write new code using GNU style.
 
+* Don't use & for function calls, unless required.
+  The use of & prevents prototypes from being checked.
+  Just as above, don't change massively all the code to strip the
+  &, just convert the old code as you work on it, and write new
+  code without.
+
 * Perl 5 is now OK.
 
 
@@ -131,3 +137,28 @@
 
 * Update version number in configure.in to next alpha number.
   Re-run autoconf and commit.
+
+-----
+
+Copyright (C) 2003 Free Software Foundation, Inc.
+
+This file is part of GNU Automake.
+
+GNU Automake is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Automake is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with autoconf; see the file COPYING.  If not, write to
+the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+Boston, MA 02111-1307, USA.
+
+Local Variables:
+mode: text
+End: