FYI: Makefile macro -> Makefile variable (Was: Re: FYI: catch variable names starting with `_' (PR/291).)

[Alexandre Duret-Lutz]

>>> "Akim" == Akim Demaille <address@hidden> writes:

[...]

 Akim> In Make talk, these are really macros.

 adl> Yep, but it will be less confusing if with reserve the word
 adl> `macro' for Autoconf macros.  The manual already states that
 adl> "Makefile macros" are called "variables" in Automake.

By the way, I just remembered this message from Calvin Arndt:
http://sources.redhat.com/ml/automake/2002-04/msg00263.html

 Akim> Great.  Then you might want to s/macro/variable/ in automake.in itself.

I'm checking in the following patch to improve this.  Note that
for now I'm only changing the occurrences that users see, not
the function names themselves.

2002-07-10  Alexandre Duret-Lutz  <address@hidden>

        * automake.texi: Use `variable' instead of `macro' everywhere it
        designates a Makefile variable.
        (Texinfo): `VERSION', `UPDATED', `EDITION', and `UPDATED-MONTH' are
        `flags', not `macros'.  `Macro' means something else in Texinfo.
        Also show how to use these flags.
        * automake.in (file_contents_internal): s/macro/variable/ in
        error message. 

Index: automake.in
===================================================================
RCS file: /cvs/automake/automake/automake.in,v
retrieving revision 1.1325
diff -u -r1.1325 automake.in
--- automake.in 10 Jul 2002 20:30:21 -0000      1.1325
+++ automake.in 10 Jul 2002 21:03:52 -0000
@@ -7722,7 +7722,7 @@
        elsif (/$ASSIGNMENT_PATTERN/mso)
        {
            my ($var, $type, $val) = ($1, $2, $3);
-           err $file, "macro `$var' with trailing backslash"
+           err $file, "variable `$var' with trailing backslash"
              if /\\$/;
 
            $is_rule = 0;
Index: automake.texi
===================================================================
RCS file: /cvs/automake/automake/automake.texi,v
retrieving revision 1.287
diff -u -r1.287 automake.texi
--- automake.texi       10 Jul 2002 05:36:45 -0000      1.287
+++ automake.texi       10 Jul 2002 21:04:10 -0000
@@ -146,9 +146,11 @@
 
 Automake is a tool for automatically generating @file{Makefile.in}s from
 files called @file{Makefile.am}.  Each @file{Makefile.am} is basically a
-series of @code{make} macro definitions (with rules being thrown in
-occasionally).  The generated @file{Makefile.in}s are compliant with the
-GNU Makefile standards.
+series of @code{make} variable address@hidden variables are
+also called @dfn{make macros} in Make terminology, however in this
+manual we reserve the term @dfn{macro} for Autoconf's macros.}, with
+rules being thrown in occasionally.  The generated @file{Makefile.in}s
+are compliant with the GNU Makefile standards.
 
 @cindex GNU Makefile standards
 
@@ -159,7 +161,7 @@
 individual GNU maintainer (and put it on the back of the Automake
 maintainer).
 
-The typical Automake input file is simply a series of macro definitions.
+The typical Automake input file is simply a series of variable definitions.
 Each such file is processed to create a @file{Makefile.in}.  There
 should generally be one @file{Makefile.am} per directory of a project.
 
@@ -210,16 +212,16 @@
 @section General Operation
 
 Automake works by reading a @file{Makefile.am} and generating a
address@hidden  Certain macros and targets defined in the
address@hidden  Certain variables and targets defined in the
 @file{Makefile.am} instruct Automake to generate more specialized code;
-for instance, a @samp{bin_PROGRAMS} macro definition will cause targets
+for instance, a @samp{bin_PROGRAMS} variable definition will cause targets
 for compiling and linking programs to be generated.
 
 @cindex Non-standard targets
 @cindex cvs-dist, non-standard example
 @trindex cvs-dist
 
-The macro definitions and targets in the @file{Makefile.am} are copied
+The variable definitions and targets in the @file{Makefile.am} are copied
 verbatim into the generated file.  This allows you to add arbitrary code
 into the generated @file{Makefile.in}.  For instance the Automake
 distribution includes a non-standard @code{cvs-dist} target, which the
@@ -234,13 +236,12 @@
 
 @cindex Append operator
 A special exception is that the GNU make append operator, @samp{+=}, is
-supported.  This operator appends its right hand argument to the macro
+supported.  This operator appends its right hand argument to the variable
 specified on the left.  Automake will translate the operator into
 an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
 
-Automake tries to group comments with adjoining targets and macro
-definitions in an intelligent way.
address@hidden FIXME: What does this imply practically?
+Automake tries to keep comments grouped with any adjoining targets or
+variable definitions.
 
 @cindex Make targets, overriding
 @cindex Overriding make targets
@@ -251,22 +252,22 @@
 best to avoid making use of it, as sometimes the generated rules are
 very particular.
 
address@hidden Macros, overriding
address@hidden Overriding make macros
address@hidden Variables, overriding
address@hidden Overriding make variables
 
-Similarly, a macro defined in @file{Makefile.am} or @code{AC_SUBST}'ed
-from @file{configure.in} will override any definition of the macro that
+Similarly, a variable defined in @file{Makefile.am} or @code{AC_SUBST}'ed
+from @file{configure.in} will override any definition of the variable that
 @code{automake} would ordinarily create.  This feature is more often
 useful than the ability to override a target definition.  Be warned that
-many of the macros generated by @code{automake} are considered to be for
+many of the variables generated by @code{automake} are considered to be for
 internal use only, and their names might change in future releases.
 
 @cindex Recursive operation of Automake
 @cindex Automake, recursive operation
 @cindex Example of recursive operation
 
-When examining a macro definition, Automake will recursively examine
-macros referenced in the definition.  For example, if Automake is
+When examining a variable definition, Automake will recursively examine
+variables referenced in the definition.  For example, if Automake is
 looking at the content of @code{foo_SOURCES} in this snippet
 
 @example
@@ -358,11 +359,10 @@
 
 @cindex Uniform naming scheme
 
-Automake macros (from here on referred to as @emph{variables}) generally
-follow a @dfn{uniform naming scheme} that makes it easy to decide how
-programs (and other derived objects) are built, and how they are
-installed.  This scheme also supports @code{configure} time
-determination of what should be built.
+Automake variables generally follow a @dfn{uniform naming scheme} that
+makes it easy to decide how programs (and other derived objects) are
+built, and how they are installed.  This scheme also supports
address@hidden time determination of what should be built.
 
 @cindex _PROGRAMS primary variable
 @cindex PROGRAMS primary variable
@@ -487,16 +487,16 @@
 @node Canonicalization, User Variables, Uniform, Generalities
 @section How derived variables are named
 
address@hidden canonicalizing Automake macros
address@hidden canonicalizing Automake variables
 
 Sometimes a Makefile variable name is derived from some text the
 maintainer supplies.  For instance, a program name listed in
 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
 variable.  In cases like this, Automake canonicalizes the text, so that
-program names and the like do not have to follow Makefile macro naming
+program names and the like do not have to follow Makefile variable naming
 rules.  All characters in the name except for letters, numbers, the
 strudel (@@), and the underscore are turned into underscores when making
-macro references.
+variable references.
 
 For example, if your program is named @code{sniff-glue}, the derived
 variable name would be @code{sniff_glue_SOURCES}, not
@@ -505,7 +505,7 @@
 @code{libmumble___a_SOURCES} variable.
 
 The strudel is an addition, to make the use of Autoconf substitutions in
-macro names less obfuscating.
+variable names less obfuscating.
 
 
 @node User Variables, Auxiliary Programs, Canonicalization, Generalities
@@ -1644,7 +1644,7 @@
 the @code{SUBDIRS} variable.
 @vindex SUBDIRS
 
-The @code{SUBDIRS} macro holds a list of subdirectories in which
+The @code{SUBDIRS} variable holds a list of subdirectories in which
 building of various sorts can occur.  Many targets (e.g. @code{all}) in
 the generated @file{Makefile} will run both locally and in all specified
 subdirectories.  Note that the directories listed in @code{SUBDIRS} are
@@ -1690,7 +1690,7 @@
 to take the subdirs, but doesn't actually bind that list until
 @code{configure} is run.
 
-Although the @code{SUBDIRS} macro can contain configure substitutions
+Although the @code{SUBDIRS} variable can contain configure substitutions
 (e.g. @samp{@@DIRS@@}); Automake itself does not actually examine the
 contents of this variable.
 
@@ -1719,7 +1719,7 @@
 @code{DIST_SUBDIRS}, instead of @code{SUBDIRS}, to determine where to
 recurse.  This variable will also be used when the user runs
 @code{distclean} or @code{maintainer-clean}.  It should be set to the
-full list of subdirectories in the project.  If this macro is not set,
+full list of subdirectories in the project.  If this variable is not set,
 Automake will attempt to set it for you.
 
 
@@ -1785,7 +1785,7 @@
 to tell it where to find @file{.m4} files.  Since sometimes @code{make}
 will automatically run @code{aclocal}, you need a way to specify these
 arguments.  You can do this by defining @code{ACLOCAL_AMFLAGS}; this
-holds arguments which are passed verbatim to @code{aclocal}.  This macro
+holds arguments which are passed verbatim to @code{aclocal}.  This variable
 is only useful in the top-level @file{Makefile.am}.
 @vindex ACLOCAL_AMFLAGS
 
@@ -2274,7 +2274,7 @@
 the library.  You can override this by setting the @samp{_AR} variable.
 This is usually used with C++; some C++ compilers require a special
 invocation in order to instantiate all the templates which should go
-into a library.  For instance, the SGI C++ compiler likes this macro set
+into a library.  For instance, the SGI C++ compiler likes this variable set
 like so:
 @example
 libmaude_a_AR = $(CXX) -ar -o
@@ -2410,7 +2410,7 @@
 
 @vtable @code
 @item AM_CPPFLAGS
-The contents of this macro are passed to every compilation which invokes
+The contents of this variable are passed to every compilation which invokes
 the C preprocessor; it is a list of arguments to the preprocessor.  For
 instance, @samp{-I} and @samp{-D} options should be listed here.
 
@@ -2422,7 +2422,7 @@
 
 @item INCLUDES
 This does the same job as @samp{AM_CPPFLAGS}.  It is an older name for
-the same functionality.  This macro is deprecated; we suggest using
+the same functionality.  This variable is deprecated; we suggest using
 @samp{AM_CPPFLAGS} instead.
 
 @item AM_CFLAGS
@@ -2902,8 +2902,8 @@
 compilation invoking @code{gcj} (in its role as an ahead-of-time
 compiler -- when invoking it to create @file{.class} files,
 @samp{AM_JAVACFLAGS} is used instead).  If it is necessary to pass
-options to @code{gcj} from @file{Makefile.am}, this macro, and not the
-user macro @samp{GCJFLAGS}, should be used.
+options to @code{gcj} from @file{Makefile.am}, this variable, and not
+the user variable @samp{GCJFLAGS}, should be used.
 
 @vindex AM_GCJFLAGS
 
@@ -3480,7 +3480,7 @@
 
 If the current directory contains Texinfo source, you must declare it
 with the @samp{TEXINFOS} primary.  Generally Texinfo files are converted
-into info, and thus the @code{info_TEXINFOS} macro is most commonly used
+into info, and thus the @code{info_TEXINFOS} variable is most commonly used
 here.  Any Texinfo source file must end in the @file{.texi},
 @file{.txi}, or @file{.texinfo} extension.  We recommend @file{.texi}
 for new manuals.
@@ -3494,26 +3494,28 @@
 be built on request by @code{make dvi}, @code{make ps}, and @code{make
 pdf}.
 
address@hidden Texinfo macro, VERSION
address@hidden Texinfo macro, UPDATED
address@hidden Texinfo macro, EDITION
address@hidden Texinfo macro, UPDATED-MONTH
-
address@hidden VERSION Texinfo macro
address@hidden UPDATED Texinfo macro
address@hidden EDITION Texinfo macro
address@hidden UPDATED-MONTH Texinfo macro
address@hidden Texinfo flag, VERSION
address@hidden Texinfo flag, UPDATED
address@hidden Texinfo flag, EDITION
address@hidden Texinfo flag, UPDATED-MONTH
+
address@hidden VERSION Texinfo flag
address@hidden UPDATED Texinfo flag
address@hidden EDITION Texinfo flag
address@hidden UPDATED-MONTH Texinfo flag
 
 @cindex mdate-sh
 
 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
 that file will be automatically generated.  The file @file{version.texi}
-defines four Texinfo macros you can reference:
+defines four Texinfo flag you can reference using
address@hidden@@address@hidden@}}, @code{@@address@hidden@}},
address@hidden@@address@hidden@}}, and @code{@@address@hidden@}}.
 
 @table @code
 @item EDITION
 @itemx VERSION
-Both of these macros hold the version number of your program.  They are
+Both of these flags hold the version number of your program.  They are
 kept separate for clarity.
 
 @item UPDATED
@@ -3609,7 +3611,7 @@
 A package can also include man pages (but see the GNU standards on this
 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.)  Man
 pages are declared using the @samp{MANS} primary.  Generally the
address@hidden macro is used.  Man pages are automatically installed in
address@hidden variable is used.  Man pages are automatically installed in
 the correct subdirectory of @code{mandir}, based on the file extension.
 @vindex MANS
 @vindex man_MANS
@@ -4386,7 +4388,7 @@
         # whatever
 @end example
 
-As you may have noted, the @code{SUFFIXES} macro behaves like the
+As you may have noted, the @code{SUFFIXES} variable behaves like the
 @code{.SUFFIXES} special target of @code{make}.  You should not touch
 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
 Automake generate the suffix list for @code{.SUFFIXES}.  Any given

-- 
Alexandre Duret-Lutz