From 3a8a87527b08bd77efa05712b524dff1d6f8f65b Mon Sep 17 00:00:00 2001 From: Alexandre Duret-Lutz Date: Sat, 5 Mar 2005 16:36:52 +0000 Subject: [PATCH] * doc/automake.texi: Replace wicked whiches by thats. --- ChangeLog | 4 + doc/automake.texi | 259 +++++++++++++++++++++++----------------------- doc/stamp-vti | 4 +- doc/version.texi | 4 +- 4 files changed, 139 insertions(+), 132 deletions(-) diff --git a/ChangeLog b/ChangeLog index 0412b105..bad8f803 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2005-03-05 Alexandre Duret-Lutz + + * doc/automake.texi: Replace wicked whiches by thats. + 2005-03-04 Alexandre Duret-Lutz * aclocal.in (scan_configure_dep, scan_file): Include file names diff --git a/doc/automake.texi b/doc/automake.texi index 741f9369..b5d2fd5a 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -10,7 +10,7 @@ @copying This manual is for @acronym{GNU} Automake (version @value{VERSION}, -@value{UPDATED}), a program which creates GNU standards-compliant +@value{UPDATED}), a program that creates GNU standards-compliant Makefiles from template files. Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, @@ -427,7 +427,7 @@ contents of @code{foo_SOURCES}. @cindex Special Automake comment @cindex Comment, special to Automake -Automake also allows a form of comment which is @emph{not} copied into +Automake also allows a form of comment that is @emph{not} copied into the output; all lines beginning with @samp{##} (leading spaces allowed) are completely ignored by Automake. @@ -471,7 +471,7 @@ The valid strictness levels are: @table @option @item foreign -Automake will check for only those things which are absolutely +Automake will check for only those things that are absolutely required for proper operations. For instance, whereas GNU standards dictate the existence of a @file{NEWS} file, it will not be required in this mode. The name comes from the fact that Automake is intended to be @@ -490,13 +490,13 @@ recommended that you avoid this option until such time as the Gnits standard is actually published (which may never happen). @end table -For more information on the precise implications of the strictness -level, see @ref{Gnits}. +@xref{Gnits}, for more information on the precise implications of the +strictness level. -Automake also has a special ``cygnus'' mode which is similar to +Automake also has a special ``cygnus'' mode that is similar to strictness but handled differently. This mode is useful for packages -which are put into a ``Cygnus'' style tree (e.g., the GCC tree). For -more information on this mode, see @ref{Cygnus}. +that are put into a ``Cygnus'' style tree (e.g., the GCC tree). +@xref{Cygnus}, for more information on this mode. @node Uniform @@ -517,11 +517,11 @@ built, and how they are installed. This scheme also supports At @command{make} time, certain variables are used to determine which objects are to be built. The variable names are made of several pieces -which are concatenated together. +that are concatenated together. -The piece which tells automake what is being built is commonly called +The piece that tells automake what is being built is commonly called the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a -list of programs which are to be compiled and linked. +list of programs that are to be compiled and linked. @vindex PROGRAMS @cindex @code{pkglibdir}, defined @@ -534,7 +534,7 @@ list of programs which are to be compiled and linked. @cindex @code{PACKAGE}, directory A different set of names is used to decide where the built objects -should be installed. These names are prefixes to the primary which +should be installed. These names are prefixes to the primary, and they indicate which standard directory should be used as the installation directory. The standard directory names are given in the GNU standards (@pxref{Directory Variables, , , standards, The GNU Coding Standards}). @@ -546,7 +546,7 @@ versions, but with @samp{$(PACKAGE)} appended. For instance, @cindex @code{EXTRA_}, prepending For each primary, there is one additional variable named by prepending @samp{EXTRA_} to the primary name. This variable is used to list -objects which may or may not be built, depending on what +objects that may or may not be built, depending on what @command{configure} decides. This variable is required because Automake must statically know the entire list of objects that may be built in order to generate a @file{Makefile.in} that will work in all cases. @@ -555,9 +555,9 @@ order to generate a @file{Makefile.in} that will work in all cases. @cindex Example, @code{EXTRA_PROGRAMS} @cindex @command{cpio} example -For instance, @command{cpio} decides at configure time which programs are -built. Some of the programs are installed in @code{bindir}, and some -are installed in @code{sbindir}: +For instance, @command{cpio} decides at configure time which programs +should be built. Some of the programs are installed in @code{bindir}, +and some are installed in @code{sbindir}: @example EXTRA_PROGRAMS = mt rmt @@ -626,7 +626,7 @@ The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES}, @vindex MANS @vindex TEXINFOS -Some primaries also allow additional prefixes which control other +Some primaries also allow additional prefixes that control other aspects of @command{automake}'s behavior. The currently defined prefixes are @samp{dist_}, @samp{nodist_}, and @samp{nobase_}. These prefixes are explained later (@pxref{Program and Library Variables}). @@ -669,7 +669,7 @@ instance, @code{CFLAGS} is one such variable. Sometimes package developers are tempted to set user variables such as @code{CFLAGS} because it appears to make their job easier. However, the package itself should never set a user variable, particularly not -to include switches which are required for proper compilation of the +to include switches that are required for proper compilation of the package. Since these variables are documented as being for the package builder, that person rightfully expects to be able to override any of these variables at build time. @@ -703,9 +703,9 @@ These two files are used by the automatic de-ANSI-fication support (@pxref{ANSI}). @item compile -This is a wrapper for compilers which don't accept both @option{-c} and -@option{-o} at the same time. It is only used when absolutely required. -Such compilers are rare. +This is a wrapper for compilers that do not accept options @option{-c} +and @option{-o} at the same time. It is only used when absolutely +required. Such compilers are rare. @item config.guess @itemx config.sub @@ -719,15 +719,15 @@ You are encouraged to fetch the latest versions of these files from release. @item depcomp -This program understands how to run a compiler so that it will generate -not only the desired output but also dependency information which is -then used by the automatic dependency tracking feature. +This program understands how to run a compiler so that it will +generate not only the desired output but also dependency information +that is then used by the automatic dependency tracking feature. @item elisp-comp This program is used to byte-compile Emacs Lisp code. @item install-sh -This is a replacement for the @command{install} program which works on +This is a replacement for the @command{install} program that works on platforms where @command{install} is unavailable or unusable. @item mdate-sh @@ -735,7 +735,7 @@ This script is used to generate a @file{version.texi} file. It examines a file and prints some date information about it. @item missing -This wraps a number of programs which are typically only required by +This wraps a number of programs that are typically only required by maintainers. If the program in question doesn't exist, @command{missing} prints an informative warning and attempts to fix things so that the build can continue. @@ -1178,7 +1178,7 @@ probably should not be used. @opindex --no-force Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in @file{configure.ac}. This option causes it to only update those -@file{Makefile.in}s which are out of date with respect to one of their +@file{Makefile.in}s that are out of date with respect to one of their dependents. @item -o @var{dir} @@ -1216,7 +1216,8 @@ obsolete features or constructions @item override user redefinitions of Automake rules or variables @item portability -portability issues (e.g., use of Make features which are known not portable) +portability issues (e.g., use of @command{make} features that are +known to be not portable) @item syntax weird syntax, unused variables, typos @item unsupported @@ -1284,10 +1285,10 @@ easier. These macros can automatically be put into your @acindex AM_INIT_AUTOMAKE The one real requirement of Automake is that your @file{configure.ac} -call @code{AM_INIT_AUTOMAKE}. This macro does several things which are +call @code{AM_INIT_AUTOMAKE}. This macro does several things that are required for proper Automake operation (@pxref{Macros}). -Here are the other macros which Automake requires but which are not run +Here are the other macros that Automake requires but which are not run by @code{AM_INIT_AUTOMAKE}: @table @code @@ -1568,7 +1569,7 @@ you can use these variables in any @file{Makefile.am} if This is required when using automatic de-ANSI-fication; see @ref{ANSI}. @item AM_GNU_GETTEXT -This macro is required for packages which use GNU gettext +This macro is required for packages that use GNU gettext (@pxref{gettext}). It is distributed with gettext. If Automake sees this macro it ensures that the package meets some of gettext's requirements. @@ -1602,7 +1603,7 @@ aclocal}). @cindex Invoking @command{aclocal} @cindex @command{aclocal}, Invoking -Automake includes a number of Autoconf macros which can be used in +Automake includes a number of Autoconf macros that can be used in your package (@pxref{Macros}); some of them are actually required by Automake in certain situations. These macros must be defined in your @file{aclocal.m4}; otherwise they will not be seen by @@ -1625,7 +1626,7 @@ requires, to be put into @file{aclocal.m4}. @emph{Putting} the file that contains the macro definition into @file{aclocal.m4} is usually done by copying the entire text of this file, including unused macro definitions as well as both @samp{#} and -@samp{dnl} comments. If you want to make a comment which will be +@samp{dnl} comments. If you want to make a comment that will be completely ignored by @command{aclocal}, use @samp{##} as the comment leader. @@ -1635,7 +1636,7 @@ argument, @command{aclocal} assumes the file belongs to the package 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. -(@xref{Local Macros}, for an example.) Any macro which is found in a +(@xref{Local Macros}, for an example.) Any macro that is found in a system-wide directory, or via an absolute search path will be copied. So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever some relative directory need to be considered outside the package. @@ -1648,8 +1649,8 @@ using @file{acinclude.m4} in new packages (@pxref{Local Macros}). @cindex autom4te While computing @file{aclocal.m4}, @command{aclocal} runs @command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te}, -autoconf, The Autoconf Manual}) in order to trace the macros which are -really used, and omit from @file{aclocal.m4} all macros which are +autoconf, The Autoconf Manual}) in order to trace the macros that are +really used, and omit from @file{aclocal.m4} all macros that are mentioned but otherwise unexpanded (this can happen when a macro is called conditionally). @command{autom4te} is expected to be in the @env{PATH}, just as @command{autoconf}. Its location can be @@ -1728,7 +1729,7 @@ Cause the output to be put into @var{file} instead of @file{aclocal.m4}. @item --print-ac-dir @opindex --print-ac-dir -Prints the name of the directory which @command{aclocal} will search to +Prints the name of the directory that @command{aclocal} will search to find third-party @file{.m4} files. When this option is given, normal processing is suppressed. This option can be used by a package to determine where to install a macro file. @@ -1885,8 +1886,8 @@ that case, many of these ``extra'' @file{.m4} files are in @file{/usr/local/share/aclocal}. The only way to force @file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to always call @samp{aclocal -I /usr/local/share/aclocal}. This is -inconvenient. With @file{dirlist}, one may create the file -@file{/usr/share/aclocal/dirlist} which contains only the single line +inconvenient. With @file{dirlist}, one may create a file +@file{/usr/share/aclocal/dirlist} containing only the single line @example /usr/local/share/aclocal @@ -1920,9 +1921,9 @@ macros installed at other places on the system. The @command{aclocal} program doesn't have any built-in knowledge of any macros, so it is easy to extend it with your own macros. -This can be used by libraries which want to supply their own Autoconf +This can be used by libraries that want to supply their own Autoconf macros for use by other programs. For instance the @command{gettext} -library supplies a macro @code{AM_GNU_GETTEXT} which should be used by +library supplies a macro @code{AM_GNU_GETTEXT} that should be used by any package using @command{gettext}. When the library is installed, it installs this macro so that @command{aclocal} will find it. @@ -1959,8 +1960,8 @@ and many third party macros are underquoted; and we have to apologize for this temporary inconvenience. The reason we have to be stricter is that a future implementation of @command{aclocal} (@pxref{Future of aclocal}) will have to temporary include all these third party -@file{.m4} files, maybe several times, even those which are not -actually needed. Doing so should alleviate many problem of the +@file{.m4} files, maybe several times, including even files that are +not actually needed. Doing so should alleviate many problems of the current implementation, however it requires a stricter style from the macro authors. Hopefully it is easy to revise the existing macros. For instance @@ -1998,7 +1999,7 @@ reported before doing so: people tend to work faster when they aren't flooded by mails. Another situation where @command{aclocal} is commonly used is to -manage macros which are used locally by the package, @ref{Local +manage macros that are used locally by the package, @ref{Local Macros}. @node Local Macros @@ -2057,12 +2058,12 @@ However there is no consensus on the distribution of third-party macros that your package may use. Many libraries install their own macro in the system-wide @command{aclocal} directory (@pxref{Extending aclocal}). For instance Guile ships with a file called -@file{guile.m4} that contains the macro @code{GUILE_FLAGS} which can +@file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can be used to define setup compiler and linker flags appropriate for using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will cause @command{aclocal} to copy @file{guile.m4} into @file{aclocal.m4}, but as @file{guile.m4} is not part of the project, -it will not be distributed. Technically, that means a user which +it will not be distributed. Technically, that means a user who needs to rebuild @file{aclocal.m4} will have to install Guile first. This is probably OK, if Guile already is a requirement to build the package. However, if Guile is only an optional feature, or if your @@ -2365,7 +2366,7 @@ Runs many macros required for proper operation of the generated Makefiles. @vindex AUTOMAKE_OPTIONS This macro has two forms, the first of which is preferred. In this form, @code{AM_INIT_AUTOMAKE} is called with a -single argument: a space-separated list of Automake options which should +single argument: a space-separated list of Automake options that should be applied to every @file{Makefile.am} in the tree. The effect is as if each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}). @@ -2524,7 +2525,7 @@ This macro is used to discover how the user's @command{make} handles needed; there should be no need to invoke it manually. @item AM_PROG_INSTALL_STRIP -This is used to find a version of @code{install} which can be used to +This is used to find a version of @code{install} that can be used to strip a program at installation time. This macro is automatically included when required. @@ -2575,7 +2576,7 @@ building of various sorts can occur. The rules for many targets both locally and in all specified subdirectories. Note that the directories listed in @code{SUBDIRS} are not required to contain @file{Makefile.am}s; only @file{Makefile}s (after configuration). -This allows inclusion of libraries from packages which do not use +This allows inclusion of libraries from packages that do not use Automake (such as @code{gettext}; see also @ref{Third-Party Makefiles}). @@ -2602,7 +2603,7 @@ own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper subdirectories. Automake can be used to construct packages of arbitrary depth this way. -By default, Automake generates @file{Makefiles} which work depth-first +By default, Automake generates @file{Makefiles} that work depth-first in postfix order: the subdirectories are built before the current directory. However, it is possible to change this ordering. You can do this by putting @samp{.} into @code{SUBDIRS}. For instance, @@ -2669,7 +2670,7 @@ will see in the next two sections, it is possible to define it conditionally so that some directory will be omitted from the build. @code{DIST_SUBDIRS} is used in rules that need to recurse in all -directories, even those which have been conditionally left out of the +directories, even those that have been conditionally left out of the build. Recall our example where we may not want to build subdirectory @file{opt/}, but yet we want to distribute it? This is where @code{DIST_SUBDIRS} come into play: @samp{opt} may not appear in @@ -2815,7 +2816,7 @@ must therefore ensure that this directory does not appear in @samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS = $(SUBDIRS)}. -Of course, directories which are omitted from @code{DIST_SUBDIRS} will +Of course, directories that are omitted from @code{DIST_SUBDIRS} will not be distributed unless you make other arrangements for this to happen (for instance always running @samp{make dist} in a configuration where all directories are known to appear in @@ -3078,7 +3079,7 @@ bin_PROGRAMS = hello In this simple case, the resulting @file{Makefile.in} will contain code to generate a program named @code{hello}. -Associated with each program are several assisting variables which are +Associated with each program are several assisting variables that are named after the program. These variables are all optional, and have reasonable defaults. Each variable, its use, and default is spelled out below; we use the ``hello'' example throughout. @@ -3170,7 +3171,7 @@ this purpose. @cindex @code{_DEPENDENCIES}, defined @vindex maude_DEPENDENCIES It is also occasionally useful to have a program depend on some other -target which is not actually part of that program. This can be done +target that is not actually part of that program. This can be done using the @code{@var{prog}_DEPENDENCIES} variable. Each program depends on the contents of such a variable, but no further interpretation is done. @@ -3204,7 +3205,7 @@ to use an Automake conditional. Automake must know all the source files that could possibly go into a program, even if not all the files are built in every circumstance. Any -files which are only conditionally built should be listed in the +files that are only conditionally built should be listed in the appropriate @code{EXTRA_} variable. For instance, if @file{hello-linux.c} or @file{hello-generic.c} were conditionally included in @code{hello}, the @file{Makefile.am} would contain: @@ -3638,7 +3639,7 @@ endif @vindex noinst_LTLIBRARIES @vindex check_LTLIBRARIES -Sometimes you want to build libtool libraries which should not be +Sometimes you want to build libtool libraries that should not be installed. These are called @dfn{libtool convenience libraries} and are typically used to encapsulate many sublibraries, later gathered into one big installed library. @@ -3902,13 +3903,13 @@ Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because when the @code{prog_CFLAGS} is defined, it is used instead of @code{AM_CFLAGS}. However as a side effect it will cause @file{prog.c} and @file{foo.c} to be compiled as -@file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)} which solves +@file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves the issue. @node Program and Library Variables @section Program and Library Variables -Associated with each program are a collection of variables which can be +Associated with each program are a collection of variables that can be used to modify how that program is built. There is a similar list of such variables for each library. The canonical name of the program (or library) is used as a base for naming these variables. @@ -3922,7 +3923,7 @@ libraries differ. @vtable @code @item maude_SOURCES -This variable, if it exists, lists all the source files which are +This variable, if it exists, lists all the source files that are compiled to build the program. These files are added to the distribution by default. When building the program, Automake will cause each source file to be compiled to a single @file{.o} file (or @@ -3983,7 +3984,7 @@ $(ARFLAGS)} followed by the name of the library and then the objects being put into the library. You can override this by setting the @code{_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++ +templates that should go into a library. For instance, the SGI C++ compiler likes this variable set like so: @example libmaude_a_AR = $(CXX) -ar -o @@ -4028,7 +4029,7 @@ the compiler or linker flags). @xref{Libtool Flags}. @item maude_DEPENDENCIES It is also occasionally useful to have a program depend on some other -target which is not actually part of that program. This can be done +target that is not actually part of that program. This can be done using the @code{_DEPENDENCIES} variable. Each program depends on the contents of such a variable, but no further interpretation is done. @@ -4045,7 +4046,7 @@ You can override the linker on a per-program basis. By default the linker is chosen according to the languages used by the program. For instance, a program that includes C++ source code would use the C++ compiler to link. The @code{_LINK} variable must hold the name of a -command which can be passed all the @file{.o} file names as arguments. +command that can be passed all the @file{.o} file names as arguments. Note that the name of the underlying program is @emph{not} passed to @code{_LINK}; typically one uses @samp{$@@}: @@ -4106,7 +4107,7 @@ per-target variables. @item maude_SHORTNAME On some platforms the allowable file names are very short. In order to support these systems and per-target compilation flags at the same -time, Automake allows you to set a ``short name'' which will influence +time, Automake allows you to set a ``short name'' that will influence how intermediate object files are named. For instance, in the following example, @@ -4349,11 +4350,11 @@ Some variables are inherited from Autoconf; these are @code{CC}, @vindex LDFLAGS @vindex LIBS -There are some additional variables which Automake itself defines: +There are some additional variables that Automake defines on its own: @vtable @code @item AM_CPPFLAGS -The contents of this variable are passed to every compilation which invokes +The contents of this variable are passed to every compilation that invokes the C preprocessor; it is a list of arguments to the preprocessor. For instance, @option{-I} and @option{-D} options should be listed here. @@ -4374,7 +4375,7 @@ same functionality. This variable is deprecated; we suggest using @code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead. @item AM_CFLAGS -This is the variable which the @file{Makefile.am} author can use to pass +This is the variable the @file{Makefile.am} author can use to pass in additional C compiler flags. It is more fully documented elsewhere. In some situations, this is not used, in preference to the per-executable (or per-library) @code{_CFLAGS}. @@ -4384,7 +4385,7 @@ This is the command used to actually compile a C source file. The file name is appended to form the complete command line. @item AM_LDFLAGS -This is the variable which the @file{Makefile.am} author can use to pass +This is the variable the @file{Makefile.am} author can use to pass in additional linker flags. In some situations, this is not used, in preference to the per-executable (or per-library) @code{_LDFLAGS}. @@ -5129,7 +5130,7 @@ the @option{no-exeext} option, this use will give a diagnostic. @node Other objects @chapter Other Derived Objects -Automake can handle derived objects which are not C programs. Sometimes +Automake can handle derived objects that are not C programs. Sometimes the support for actually building such objects must be explicitly supplied, but Automake will still automatically handle installation and distribution. @@ -5150,7 +5151,7 @@ distribution. @cindex Primary variable, @code{SCRIPTS} @vindex _SCRIPTS -It is possible to define and install programs which are scripts. Such +It is possible to define and install programs that are scripts. Such programs are listed using the @code{SCRIPTS} primary name. Automake doesn't define any dependencies for scripts; the @file{Makefile.am} should include the appropriate rules. @@ -5484,7 +5485,7 @@ bindir.h: Makefile @end example You don't have to list @emph{all} the dependencies of @file{foo.o} -explicitly, only those which might need to be built. If a dependency +explicitly, only those that might need to be built. If a dependency already exists, it will not hinder the first compilation and will be recorded by the normal dependency tracking code. (Note that after this first compilation the dependency tracking code will also have @@ -5693,7 +5694,7 @@ instance, a @file{.java} file can define multiple classes; the resulting @file{.class} file names cannot be predicted without parsing the @file{.java} file. -There are a few variables which are used when compiling Java sources: +There are a few variables that are used when compiling Java sources: @vtable @code @item JAVAC @@ -5713,7 +5714,7 @@ The value of this variable is passed to the @option{-d} option to @code{javac}. It defaults to @samp{$(top_builddir)}. @item CLASSPATH_ENV -This variable is an @code{sh} expression which is used to set the +This variable is an @code{sh} expression that is used to set the @env{CLASSPATH} environment variable on the @code{javac} command line. (In the future we will probably handle class path setting differently.) @end vtable @@ -5738,7 +5739,7 @@ byte-compilation occurs at install time, any files listed in @code{noinst_PYTHON} will not be compiled. Python source files are included in the distribution by default. -Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON} which +Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON} that will determine some Python-related directory variables (see below). If you have called @code{AM_PATH_PYTHON} from @file{configure.ac}, then you may use the following variables to list you Python source files in your @@ -5751,7 +5752,7 @@ want your files installed. Search a Python interpreter on the system. This macro takes three optional arguments. The first argument, if present, is the minimum version of Python required for this package: @code{AM_PATH_PYTHON} -will skip any Python interpreter which is older than @var{VERSION}. +will skip any Python interpreter that is older than @var{VERSION}. If an interpreter is found and satisfies @var{VERSION}, then @var{ACTION-IF-FOUND} is run. Otherwise, @var{ACTION-IF-NOT-FOUND} is run. @@ -5791,12 +5792,12 @@ The Python version number, in the form @var{major}.@var{minor} @item PYTHON_PREFIX The string @samp{$@{prefix@}}. This term may be used in future work -which needs the contents of Python's @samp{sys.prefix}, but general +that needs the contents of Python's @samp{sys.prefix}, but general consensus is to always use the value from configure. @item PYTHON_EXEC_PREFIX The string @samp{$@{exec_prefix@}}. This term may be used in future work -which needs the contents of Python's @samp{sys.exec_prefix}, but general +that needs the contents of Python's @samp{sys.exec_prefix}, but general consensus is to always use the value from configure. @item PYTHON_PLATFORM @@ -5809,7 +5810,7 @@ The directory name for the @file{site-packages} subdirectory of the standard Python install tree. @item pkgpythondir -This is is the directory under @code{pythondir} which is named after the +This is the directory under @code{pythondir} that is named after the package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided as a convenience. @@ -5818,7 +5819,7 @@ This is the directory where Python extension modules (shared libraries) should be installed. @item pkgpyexecdir -This is a convenience variable which is defined as +This is a convenience variable that is defined as @samp{$(pyexecdir)/$(PACKAGE)}. @end vtable @@ -6139,7 +6140,7 @@ in @samp{$(bindir)}. Sometimes it is useful to avoid the basename step at install time. For instance, you might have a number of header files in subdirectories of -the source tree which are laid out precisely how you want to install +the source tree that are laid out precisely how you want to install them. In this situation you can use the @code{nobase_} prefix to suppress the base name step. For example: @@ -6153,7 +6154,7 @@ in @samp{$(includedir)/sys}. @section The two parts of install Automake generates separate @code{install-data} and @code{install-exec} -rules, in case the installer is installing on multiple machines which +rules, in case the installer is installing on multiple machines that share directory structure---these targets allow the machine-independent parts to be installed only once. @code{install-exec} installs platform-dependent files, and @code{install-data} installs @@ -6283,7 +6284,7 @@ clean-local: @end example As the GNU Standards aren't always explicit as to which files should -be removed by which rule, we've adopted a heuristic which we believe +be removed by which rule, we've adopted a heuristic that we believe was first formulated by Fran@,{c}ois Pinard: @itemize @bullet @@ -6336,10 +6337,10 @@ is run. The default setting is @option{--best}. For the most part, the files to distribute are automatically found by Automake: all source files are automatically included in a distribution, as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also -has a built-in list of commonly used files which are automatically +has a built-in list of commonly used files that are automatically included if they are found in the current directory (either physically, or as the target of a @file{Makefile.am} rule). This list is printed by -@samp{automake --help}. Also, files which are read by @command{configure} +@samp{automake --help}. Also, files that are read by @command{configure} (i.e. the source files corresponding to the files specified in various Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are automatically distributed. Files included in @file{Makefile.am}s (using @@ -6348,7 +6349,7 @@ helper scripts installed with @samp{automake --add-missing} are also distributed. @vindex EXTRA_DIST -Still, sometimes there are files which must be distributed, but which +Still, sometimes there are files that must be distributed, but which are not covered in the automatic rules. These files should be listed in the @code{EXTRA_DIST} variable. You can mention files from subdirectories in @code{EXTRA_DIST}. @@ -6376,8 +6377,8 @@ exact list of subdirectories to include in the distribution @vindex dist_ @vindex nodist_ Sometimes you need tighter control over what does @emph{not} go into the -distribution; for instance you might have source files which are -generated and which you do not want to distribute. In this case +distribution; for instance you might have source files that are +generated and that you do not want to distribute. In this case Automake gives fine-grained control using the @code{dist} and @code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be prefixed with @code{dist_} to add the listed files to the distribution. @@ -6452,7 +6453,7 @@ dist} was run, not to any sub-packages involved. @vindex distuninstallcheck_listfiles @trindex distcheck -Automake also generates a @code{distcheck} rule which can be of help +Automake also generates a @code{distcheck} rule that can be of help to ensure that a given distribution will actually work. @code{distcheck} makes a distribution, then tries to do a @code{VPATH} build, run the test suite, and finally make another tarfile to ensure the @@ -6500,7 +6501,7 @@ distcleancheck: @@: @end example -If you want @code{distcleancheck} to ignore built files which have not +If you want @code{distcleancheck} to ignore built files that have not been cleaned because they are also part of the distribution, add the following definition instead: @@ -6626,7 +6627,7 @@ program. If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in @code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is -assumed. The variable @code{DEJATOOL} is a list of names which are +assumed. The variable @code{DEJATOOL} is a list of names that are passed, one at a time, as the @option{--tool} argument to @command{runtest} invocations; it defaults to the name of the package. @@ -6689,7 +6690,7 @@ Sometimes you need to run @command{aclocal} with an argument like @option{-I} to tell it where to find @file{.m4} files. Since sometimes @command{make} will automatically run @command{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 +@code{ACLOCAL_AMFLAGS}; this holds arguments that are passed verbatim to @command{aclocal}. This variable is only useful in the top-level @file{Makefile.am}. @@ -6914,7 +6915,7 @@ be available for optional installation. This option is disallowed at @item @option{nostdinc} @cindex Option, @option{nostdinc} @opindex nostdinc -This option can be used to disable the standard @option{-I} options which +This option can be used to disable the standard @option{-I} options that are ordinarily automatically provided by Automake. @item @option{no-texinfo.tex} @@ -7023,7 +7024,7 @@ can document this accurately). @option{tar-pax} selects the new pax interchange format defined by POSIX 1003.1-2001. It does not limit the length of file names. However, this format is very young and should probably be restricted to -packages which target only very modern platforms. There are moves to +packages that target only very modern platforms. There are moves to change the pax format in an upward-compatible way, so this option may refer to a more recent version in the future. @@ -7088,13 +7089,14 @@ generated source files that are not distributed must be declared in variables like @code{nodist_noinst_HEADERS} or @code{nodist_@var{prog}_SOURCES} or they will be ignored. -At the topmost directory of a multi-directory package, a @code{tags} -rule will be output which, when run, will generate a @file{TAGS} file -that includes by reference all @file{TAGS} files from subdirectories. +A @code{tags} rule will be output at the topmost directory of a +multi-directory package. When run from this topmost directory, +@samp{make tags} will generate a @file{TAGS} file that includes by +reference all @file{TAGS} files from subdirectories. The @code{tags} rule will also be generated if the variable @code{ETAGS_ARGS} is defined. This variable is intended for use in -directories which contain taggable source that @command{etags} does +directories that contain taggable source that @command{etags} does not understand. The user can use the @code{ETAGSFLAGS} to pass additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also available for use in @file{Makefile.am}. @@ -7115,13 +7117,13 @@ want to define @code{TAGS_DEPENDENCIES}. The contents of this variable are added directly to the dependencies for the @code{tags} rule. @vindex TAGS_DEPENDENCIES -Automake also generates a @code{ctags} rule which can be used to +Automake also generates a @code{ctags} rule that can be used to build @command{vi}-style @file{tags} files. The variable @code{CTAGS} is the name of the program to invoke (by default @command{ctags}); @code{CTAGSFLAGS} can be used by the user to pass additional flags, and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}. -Automake will also generate an @code{ID} rule which will run +Automake will also generate an @code{ID} rule that will run @command{mkid} on the source. This is only supported on a directory-by-directory basis. @trindex id @@ -7130,7 +7132,7 @@ Finally, Automake also emit rules to support the @uref{http://www.gnu.org/software/global/, GNU Global Tags program}. The @code{GTAGS} rule runs Global Tags and puts the result in the top build directory. The variable @code{GTAGS_ARGS} -holds arguments which are passed to @command{gtags}. +holds arguments that are passed to @command{gtags}. @vindex GTAGS_ARGS @@ -7144,7 +7146,7 @@ holds arguments which are passed to @command{gtags}. It is sometimes useful to introduce a new implicit rule to handle a file type that Automake does not know about. -For instance, suppose you had a compiler which could compile @file{.foo} +For instance, suppose you had a compiler that could compile @file{.foo} files to @file{.o} files. You would simply define an suffix rule for your language: @@ -7189,7 +7191,7 @@ by Automake generated suffixes not already in the list. @section Support for Multilibs Automake has support for an obscure feature called multilibs. A -@dfn{multilib} is a library which is built for multiple different ABIs +@dfn{multilib} is a library that is built for multiple different ABIs at a single time; each time the library is built with a different target flag combination. This is only useful when the library is intended to be cross-compiled, and it is almost exclusively used for compiler @@ -7206,7 +7208,7 @@ familiar with multilibs and can debug problems you might encounter. @cindex Including @file{Makefile} fragment @cindex @file{Makefile} fragment, including -Automake supports an @code{include} directive which can be used to +Automake supports an @code{include} directive that can be used to include other @file{Makefile} fragments when @command{automake} is run. Note that these fragments are read and interpreted by @command{automake}, not by @command{make}. As with conditionals, @command{make} has no idea that @@ -7216,11 +7218,11 @@ There are two forms of @code{include}: @table @code @item include $(srcdir)/file -Include a fragment which is found relative to the current source +Include a fragment that is found relative to the current source directory. @item include $(top_srcdir)/file -Include a fragment which is found relative to the top source directory. +Include a fragment that is found relative to the top source directory. @end table Note that if a fragment is included inside a conditional, then the @@ -7244,7 +7246,7 @@ Before using a conditional, you must define it by using The conditional name, @var{conditional}, should be a simple string starting with a letter and containing only letters, digits, and underscores. It must be different from @samp{TRUE} and @samp{FALSE} -which are reserved by Automake. +that are reserved by Automake. The shell @var{condition} (suitable for use in a shell @code{if} statement) is evaluated when @command{configure} is run. Note that you @@ -7258,9 +7260,9 @@ will confuse automake. @cindex Example conditional @option{--enable-debug} @cindex Conditional example, @option{--enable-debug} -Conditionals typically depend upon options which the user provides to +Conditionals typically depend upon options that the user provides to the @command{configure} script. Here is an example of how to write a -conditional which is true if the user uses the @option{--enable-debug} +conditional that is true if the user uses the @option{--enable-debug} option. @example @@ -7297,7 +7299,7 @@ negated using @samp{!}. The @code{else} statement may be omitted. Conditionals may be nested to any depth. You may specify an argument to @code{else} in which case it must be the negation of the condition used for the current @code{if}. Similarly you may specify the condition -which is closed by an @code{end}: +that is closed by an @code{end}: @example if DEBUG @@ -7669,7 +7671,7 @@ constructed. Of course this target is not required if the The variables @samp{$(top_distdir)} and @samp{$(distdir)} (@pxref{Dist}) will be passed from the outer package to the subpackage when the @code{distdir} target is invoked. These two variables have -been adjusted for the directory which is being recursed into, so they +been adjusted for the directory that is being recursed into, so they are ready to use. @item install @@ -7717,7 +7719,7 @@ how third-party @file{Makefile}s can be used with Automake. The implement all these targets. That way they can be added to @code{SUBDIRS} in Automake packages. -Directories which are only listed in @code{DIST_SUBDIRS} but not in +Directories that are only listed in @code{DIST_SUBDIRS} but not in @code{SUBDIRS} need only the @code{distclean}, @code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional Subdirectories}). @@ -7854,7 +7856,7 @@ will use @command{automake-1.6} explicitly in their rebuild rules. The number @samp{1.6} in @command{automake-1.6} is Automake's API version, not Automake's version. If a bug fix release is made, for instance Automake 1.6.1, the API version will remain 1.6. This means that a -package which work with Automake 1.6 should also work with 1.6.1; after +package that works with Automake 1.6 should also work with 1.6.1; after all, this is what people expect from bug fix releases. If your package relies on a feature or a bug fix introduced in @@ -8002,7 +8004,7 @@ commit time), CVS preserves timestamp during @samp{cvs commit} and @samp{cvs import -d} operations. When you check out a file using @samp{cvs checkout} its timestamp is -set to that of the revision which is being checked out. +set to that of the revision that is being checked out. However, during @command{cvs update}, files will have the date of the update, not the original timestamp of this revision. This is meant to @@ -8093,7 +8095,7 @@ tree, @file{Makefile.in} will happen to be newer than @subsubheading Generated files out of CVS One way to get CVS and @command{make} working peacefully is to never -store generated files in CVS, i.e., do not CVS-control files which +store generated files in CVS, i.e., do not CVS-control files that are @file{Makefile} targets (also called @emph{derived} files). This way developers are not annoyed by changes to generated files. It @@ -8121,7 +8123,7 @@ versions of this tool. @cindex third-party files and CVS Another class of files not discussed here (because they do not cause -timestamp issues) are files which are shipped with a package, but +timestamp issues) are files that are shipped with a package, but maintained elsewhere. For instance tools like @command{gettextize} and @command{autopoint} (from Gettext) or @command{libtoolize} (from Libtool), will install or update files in your package. @@ -8148,7 +8150,7 @@ checked for in @file{configure}. However, if for some reason a rebuild rule is triggered and involves a missing tool, @command{missing} will notice it and warn the user. Besides the warning, when a tool is missing, @command{missing} will -attempt to fix timestamps in a way which allow the build to continue. +attempt to fix timestamps in a way that allows the build to continue. For instance @command{missing} will touch @file{configure} if @command{autoconf} is not installed. When all distributed files are kept under CVS, this feature of @command{missing} allows user @@ -8172,7 +8174,7 @@ default. If you have @code{AM_MAINTAINER_MODE} in @file{configure.ac}, and run @samp{./configure && make}, then @command{make} will *never* attempt to rebuilt @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs, etc. I.e., this disables -build rules for files which are usually distributed and that users +build rules for files that are usually distributed and that users should normally not have to update. If you run @samp{./configure --enable-maintainer-mode}, then these @@ -8233,7 +8235,7 @@ you remember to @samp{cvs add} it. @item Using wildcards makes easy to distribute files by mistake. For instance some code a developer is experimenting with (a test case, -say) but which should not be part of the distribution. +say) but that should not be part of the distribution. @item Using wildcards it's easy to omit some files by mistake. For @@ -8393,7 +8395,8 @@ cross-compilation, because building @file{foo.1} involves an @emph{execution} of @file{foo$(EXEEXT)}. Another context where such errors are common is when distributed files -are built by tools which are built by the package. The pattern is similar: +are built by tools that are built by the package. The pattern is +similar: @example distributed-file: built-tools distributed-sources @@ -9851,7 +9854,7 @@ to be very tricky (later releases will improve this) as people had devised many ways to cope with the limitation of previous @command{aclocal} versions, notably using handwritten @code{m4_include}s: @command{aclocal} must make sure not to redefine a -rule which is already included by such statement. +rule that is already included by such statement. Automake also has seen its guts rewritten. Although this rewriting took a lot of efforts, it is only apparent to the users in that some @@ -9904,7 +9907,7 @@ Prerequisites, , Generating Prerequisites Automatically, make, The GNU make Manual}) This version worked by precomputing dependencies ahead of time. For -each source file, it had a special @file{.P} file which held the +each source file, it had a special @file{.P} file that held the dependencies. There was a rule to generate a @file{.P} file by invoking the compiler appropriately. All such @file{.P} files were included by the @file{Makefile}, thus implicitly becoming dependencies @@ -9934,14 +9937,14 @@ As dependency tracking was done as a pre-pass, compile times were doubled--the compiler had to be run twice per source file. @item @samp{make dist} re-ran @command{automake} to generate a -@file{Makefile} which did not have automatic dependency tracking (and -which was thus portable to any version of @command{make}). In order to +@file{Makefile} that did not have automatic dependency tracking (and +that was thus portable to any version of @command{make}). In order to do this portably, Automake had to scan the dependency files and remove -any reference which was to a source file not in the distribution. +any reference that was to a source file not in the distribution. This process was error-prone. Also, if @samp{make dist} was run in an environment where some object file had a dependency on a source file -which was only conditionally created, Automake would generate a -@file{Makefile} which referred to a file which might not appear in the +that was only conditionally created, Automake would generate a +@file{Makefile} that referred to a file that might not appear in the end user's build. A special, hacky mechanism was required to work around this. @end itemize @@ -9971,7 +9974,7 @@ We only computed dependencies when a file was actually compiled. This avoided the performance penalty associated with scanning each file twice. It also let us avoid the other problems associated with the first, eager, implementation. For instance, dependencies would never -be generated for a source file which was not compilable on a given +be generated for a source file that was not compilable on a given architecture (because it in fact would never be compiled). @unnumberedsubsubsec Bugs @@ -10022,13 +10025,13 @@ of the second implementation: dependency computation as a side effect of compilation. In the end we found that most modern make implementations support some -form of include directive. Also, we wrote a wrapper script which let +form of include directive. Also, we wrote a wrapper script that let us abstract away differences between dependency tracking methods for compilers. For instance, some compilers cannot generate dependencies as a side effect of compilation. In this case we simply have the script run the compiler twice. Currently our wrapper script (@command{depcomp}) knows about twelve different compilers (including -a "compiler" which simply invokes @command{makedepend} and then the +a "compiler" that simply invokes @command{makedepend} and then the real compiler, which is assumed to be a standard Unix-like C compiler with no way to do dependency tracking). diff --git a/doc/stamp-vti b/doc/stamp-vti index 16bb07f5..7138e1a5 100644 --- a/doc/stamp-vti +++ b/doc/stamp-vti @@ -1,4 +1,4 @@ -@set UPDATED 27 February 2005 -@set UPDATED-MONTH February 2005 +@set UPDATED 5 March 2005 +@set UPDATED-MONTH March 2005 @set EDITION 1.9a @set VERSION 1.9a diff --git a/doc/version.texi b/doc/version.texi index 16bb07f5..7138e1a5 100644 --- a/doc/version.texi +++ b/doc/version.texi @@ -1,4 +1,4 @@ -@set UPDATED 27 February 2005 -@set UPDATED-MONTH February 2005 +@set UPDATED 5 March 2005 +@set UPDATED-MONTH March 2005 @set EDITION 1.9a @set VERSION 1.9a -- 2.43.5