2005-03-31 Stepan Kasal * doc/automake.texi: When the phrase "for instance" introduces a sentence, it should be delimited by a comma. --- doc/automake.texi 2005-03-31 10:09:27.000000000 +0200 +++ doc/automake.texi 2005-03-31 10:16:00.000000000 +0200 @@ -309,7 +309,7 @@ @cindex Constraints of Automake @cindex Automake constraints -Automake does constrain a project in certain ways; for instance it +Automake does constrain a project in certain ways; for instance, it assumes that the project uses Autoconf (@pxref{Top, , Introduction, autoconf, The Autoconf Manual}), and enforces certain restrictions on the @file{configure.ac} address@hidden Autoconf versions used @@ -365,7 +365,7 @@ The variable definitions and rules 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 +arbitrary code into the generated @file{Makefile.in}. For instance, the Automake distribution includes a non-standard rule for the @code{cvs-dist} target, which the Automake maintainer uses to make distributions from his source control system. @@ -1120,7 +1120,7 @@ @opindex -a @opindex --add-missing Automake requires certain common files to exist in certain situations; -for instance @file{config.guess} is required if @file{configure.ac} runs +for instance, @file{config.guess} is required if @file{configure.ac} runs @code{AC_CANONICAL_HOST}. Automake is distributed with several of these files (@pxref{Auxiliary Programs}); this option will cause the missing ones to be automatically added to the package, whenever possible. In @@ -1248,7 +1248,7 @@ @end table A category can be turned off by prefixing its name with @samp{no-}. For -instance @option{-Wno-syntax} will hide the warnings about unused +instance, @option{-Wno-syntax} will hide the warnings about unused variables. The categories output by default are @samp{syntax} and @@ -1358,7 +1358,7 @@ fine if the @code{AC_CONFIG_FILES} specifications contain only literals. If part of the specification uses shell variables, @command{automake} will not be able to fulfil this setup, and you will -have to complete the missing bits by hand. For instance on +have to complete the missing bits by hand. For instance, on @example file=input @@ -1395,7 +1395,7 @@ that is compatible with @command{make}'s syntax) and furthermore use @code{AC_SUBST} to ensure that @address@hidden@}} is meaningful in a @file{Makefile}, then @command{automake} will be able to use address@hidden@address@hidden to generate all these rules. For instance here is address@hidden@address@hidden to generate all these rules. For instance, here is how the Automake package itself generates versioned scripts for its test suite: @@ -1939,7 +1939,7 @@ macros, so it is easy to extend it with your own macros. This can be used by libraries that want to supply their own Autoconf -macros for use by other programs. For instance the @command{gettext} +macros for use by other programs. For instance, the @command{gettext} 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. @@ -1981,7 +1981,7 @@ 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 +For instance, @example # bad style AC_PREREQ(2.57) @@ -2074,7 +2074,7 @@ 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 +aclocal}). For instance, Guile ships with a file called @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 @@ -2270,7 +2270,7 @@ Finally, note that the @option{--force} option of @command{aclocal} has absolutely no effect on the files installed by @option{--install}. For -instance you have modified your local macros, do not expect +instance, you have modified your local macros, do not expect @option{--install --force} to replace the local macros by their system-wide versions. If you want to do so, simply erase the local macros you want to revert, and run @samp{aclocal -I m4 --install}. @@ -2288,7 +2288,7 @@ indication of how that feature is misplaced. The new implementation will probably be done slightly differently. -For instance it could enforce the @file{m4/}-style layout discussed in +For instance, it could enforce the @file{m4/}-style layout discussed in @ref{Local Macros}. We have no idea when and how this will happen. This has been @@ -2846,7 +2846,7 @@ In order to prevent recursion in some non-configured directory you must therefore ensure that this directory does not appear in address@hidden (and @code{SUBDIRS}). For instance if you define address@hidden (and @code{SUBDIRS}). For instance, if you define @code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define @code{DIST_SUBDIRS} explicitly, it will be default to @samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS @@ -2854,7 +2854,7 @@ 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 +happen (for instance, always running @samp{make dist} in a configuration where all directories are known to appear in @code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to distribute these directories). @@ -2925,7 +2925,7 @@ Finally, note that a variable using the @samp{nobase_} prefix can always be replaced by several variables, one for each destination -directory (@pxref{Uniform}). For instance the last example could be +directory (@pxref{Uniform}). For instance, the last example could be rewritten as follows: @example @@ -3025,7 +3025,7 @@ The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to force Automake and Autoconf into search auxiliary script in the -current directory. For instance this means that there will be two +current directory. For instance, this means that there will be two copies of @file{install-sh}: one in the top-level of the @code{arm} package, and another one in the @file{hand/} subdirectory for the @code{hand} package. @@ -3381,7 +3381,7 @@ libraries using libtool and the @code{LTLIBRARIES} primary. Each @code{_LIBRARIES} variable is a list of the libraries to be built. -For instance to create a library named @file{libcpio.a}, but not install +For instance, to create a library named @file{libcpio.a}, but not install it, you would write: @example @@ -4011,7 +4011,7 @@ files in the @code{EXTRA_} variable. This variable also supports @code{dist_} and @code{nodist_} prefixes. -For instance @code{nodist_EXTRA_maude_SOURCES} would list extra +For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra sources that may need to be built, but should not be distributed. @item maude_AR @@ -4028,7 +4028,7 @@ @item maude_LIBADD Extra objects can be added to a @emph{library} using the @code{_LIBADD} -variable. For instance this should be used for objects determined by +variable. For instance, this should be used for objects determined by @command{configure} (@pxref{A Library}). In the case of libtool libraries, @code{maude_LIBADD} can also refer @@ -4037,7 +4037,7 @@ @item maude_LDADD Extra objects (@file{*.$(OBJDIR)}) and libraries (@file{*.a}, @file{*.la}) can be added to a @emph{program} by listing them in the address@hidden variable. For instance this should be used for objects address@hidden variable. For instance, this should be used for objects determined by @command{configure} (@pxref{Linking}). @code{_LDADD} and @code{_LIBADD} are inappropriate for passing @@ -4200,7 +4200,7 @@ @cindex @code{check_PROGRAMS} example @vindex check_PROGRAMS Default sources are mainly useful in test suites, when building many -tests programs each from a single source. For instance in +tests programs each from a single source. For instance, in @example check_PROGRAMS = test1 test2 test3 @@ -4351,7 +4351,7 @@ Please note it would be wrong to use the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in @file{src/Makefile.am}, because these variables -contains unprefixed object names, and for instance +contains unprefixed object names, and, for instance, @file{malloc.$(OBJEXT)} is not buildable in the @file{src/} directory. (Actually if you try using @samp{$(LIBOBJS)} in @file{src/}, Automake will require a copy of @file{malloc.c}, @file{memcmp.c}, @@ -4373,7 +4373,7 @@ @section Variables used when building a program Occasionally it is useful to know which @file{Makefile} variables -Automake uses for compilations; for instance you might need to do your +Automake uses for compilations; for instance, you might need to do your own compilation in some special cases. Some variables are inherited from Autoconf; these are @code{CC}, @@ -5217,7 +5217,7 @@ Because---as we have just seen---scripts can be built, they are not distributed by default. Scripts that should be distributed can be specified using a @code{dist_} prefix as in other primaries. For -instance the following @file{Makefile.am} declares that +instance, the following @file{Makefile.am} declares that @file{my_script} should be distributed and installed in @samp{$(sbindir)}. @@ -5261,7 +5261,7 @@ Header files that must be installed are specified by the @code{HEADERS} family of variables. Headers can be installed in @code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any -other directory you may have defined (@pxref{Uniform}). For instance +other directory you may have defined (@pxref{Uniform}). For instance, @example include_HEADERS = foo.h bar/bar.h @@ -5357,7 +5357,7 @@ they can be used to decide whether @file{foo.o} should be rebuilt. It's a different story if @file{foo.h} doesn't exist by the first address@hidden run. For instance there might be a rule to build address@hidden run. For instance, there might be a rule to build @file{foo.h}. This time @file{file.o}'s build will fail because the compiler can't find @file{foo.h}. @command{make} failed to trigger the rule to build @file{foo.h} first by lack of dependency information. @@ -5380,7 +5380,7 @@ @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which must be created early in the build process can be listed in this variable. Moreover, all built sources do not necessarily have to be -listed in @code{BUILT_SOURCES}. For instance a generated @file{.c} file +listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by another source), because it's a known dependency of the associated object. @@ -5449,7 +5449,7 @@ it is not even being built on-time. One may wonder what the @samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This line simply states that @file{bindir.h} is a source of @code{foo}, so -for instance it should be inspected while generating tags +for instance, it should be inspected while generating tags (@pxref{Tags}). In other words, it does not help our present problem, and the build would fail identically without it. @@ -6043,7 +6043,7 @@ @samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html} files. -For instance the following setting can be used to obtain one single +For instance, the following setting can be used to obtain one single @file{.html} file per manual, without node separators. @example AM_MAKEINFOHTMLFLAGS = --no-headers --no-split @@ -6212,7 +6212,7 @@ @samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate}, @samp{lib}, or @samp{pkglib} are installed by @code{install-exec}. -For instance @code{data_DATA} files are installed by @code{install-data}, +For instance, @code{data_DATA} files are installed by @code{install-data}, while @code{bin_PROGRAMS} files are installed by @code{install-exec}. Any variable using a user-defined directory prefix with @samp{exec} in @@ -6311,7 +6311,7 @@ own commands. Simply define a rule for any of the @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local}, or @code{maintainer-clean-local} targets (@pxref{Extending}). A common -case is deleting a directory, for instance a directory created by the +case is deleting a directory, for instance, a directory created by the test suite: @example @@ -6413,7 +6413,7 @@ @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 that are +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 @@ -6528,7 +6528,7 @@ The @code{distcleancheck} behavior should be OK for most packages, otherwise you have the possibility to override the definition of either the @code{distcleancheck} rule, or the address@hidden(distcleancheck_listfiles)} variable. For instance to disable address@hidden(distcleancheck_listfiles)} variable. For instance, to disable @code{distcleancheck} completely, add the following rule to your top-level @file{Makefile.am}: @@ -6742,7 +6742,7 @@ dependencies. These variable should be defined in all @file{Makefile}s of the tree (because these two rebuild rules are output in all them), so it is safer and easier to @code{AC_SUBST} them -from @file{configure.ac}. For instance the following statement will +from @file{configure.ac}. For instance, the following statement will cause @file{configure} to be rerun each time @file{version.sh} is changed. @example @@ -6986,11 +6986,11 @@ @vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT In a few situations, programs (or scripts) have to be exempted from this -test. For instance @command{false} (from GNU sh-utils) is never +test. For instance, @command{false} (from GNU sh-utils) is never successful, even for @option{--help} or @option{--version}. You can list such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}. Programs (not scripts) listed in this variable should be suffixed by address@hidden(EXEEXT)} for the sake of Win32 or OS/2. For instance suppose we address@hidden(EXEEXT)} for the sake of Win32 or OS/2. For instance, suppose we build @file{false} as a program but @file{true.sh} as a script, and that neither of them support @option{--help} or @option{--version}: @@ -7006,7 +7006,7 @@ @opindex subdir-objects If this option is specified, then objects are placed into the subdirectory of the build directory corresponding to the subdirectory of -the source file. For instance if the source file is +the source file. For instance, if the source file is @file{subdir/file.cxx}, then the output file would be @file{subdir/file.o}. @@ -7084,7 +7084,7 @@ These options behave exactly like their command-line counterpart (@pxref{Invoking Automake}). This allows you to enable or disable some warning categories on a per-file basis. You can also setup some warnings -for your entire project; for instance try @samp{AM_INIT_AUTOMAKE([-Wall])} +for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])} in your @file{configure.ac}. @end table @@ -7206,7 +7206,7 @@ suffixes in the @code{SUFFIXES} variable @strong{before} you define your implicit rule. -For instance the following definition prevents Automake to misinterpret +For instance, the following definition prevents Automake to misinterpret @samp{.idlC.cpp:} as an attempt to transform @file{.idlC} files into @file{.cpp} files. @@ -7385,7 +7385,7 @@ checking; it is advisable to be familiar with the precise requirements of the GNU standards. Also, @option{--gnu} can require certain non-standard GNU programs to exist for use by various maintainer-only -rules; for instance in the future @command{pathchk} might be required for +rules; for instance, in the future @command{pathchk} might be required for @samp{make dist}. @cindex @option{--gnits}, complete description @@ -7635,7 +7635,7 @@ @end example Although cheaper and more portable than symbolic links, hard links -will not work everywhere (for instance OS/2 does not have +will not work everywhere (for instance, OS/2 does not have @command{ln}). Ideally you should fall back to @samp{cp -p} when @command{ln} does not work. An easy way, if symbolic links are acceptable to you, is to add @code{AC_PROG_LN_S} to @@ -7678,7 +7678,7 @@ In most projects all @file{Makefile}s are generated by Automake. In some cases, however, projects need to embed subdirectories with -handwritten @file{Makefile}s. For instance one subdirectory could be +handwritten @file{Makefile}s. For instance, one subdirectory could be a third-party project with its own build system, not using Automake. It is possible to list arbitrary directories in @code{SUBDIRS} or @@ -7790,7 +7790,7 @@ @samp{$(top_distdir)} variables.. It is sometimes inconvenient to modify a third-party @file{Makefile} -to introduce the above required targets. For instance one may want to +to introduce the above required targets. For instance, one may want to keep the third-party sources untouched to ease upgrades to new versions. @@ -7972,7 +7972,7 @@ overridden by new versions (@pxref{Invoking Automake}). It is important to regenerate all these files each time Automake is -upgraded, even between bug fixes releases. For instance it is not +upgraded, even between bug fixes releases. For instance, it is not unusual for a bug fix to involve changes to both the rules generated in @file{Makefile.in} and the supporting M4 macros copied to @file{aclocal.m4}. @@ -8022,7 +8022,7 @@ or Info documentation, are usually distributed on similar grounds. Automake outputs rules in @file{Makefile}s to rebuild these files. For -instance @command{make} will run @command{autoconf} to rebuild +instance, @command{make} will run @command{autoconf} to rebuild @file{configure} whenever @file{configure.ac} is changed. This makes development safer by ensuring a @file{configure} is never out-of-date with respect to @file{configure.ac}. @@ -8070,7 +8070,7 @@ what is distributed, and you can checkout any prior version entirely. @item -Maintainers can see how generated files evolve (for instance you can +Maintainers can see how generated files evolve (for instance, you can see what happens to your @file{Makefile.in}s when you upgrade Automake and make sure they look OK). @@ -8160,7 +8160,7 @@ Another class of files not discussed here (because they do not cause timestamp issues) are files that are shipped with a package, but -maintained elsewhere. For instance tools like @command{gettextize} +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. @@ -8187,7 +8187,7 @@ 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 that allows the build to continue. -For instance @command{missing} will touch @file{configure} if +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 @emph{with no maintainer tools} to build a package off CVS, bypassing @@ -8270,12 +8270,12 @@ @item Using wildcards makes easy to distribute files by mistake. For -instance some code a developer is experimenting with (a test case, +instance, some code a developer is experimenting with (a test case, say) but that should not be part of the distribution. @item Using wildcards it's easy to omit some files by mistake. For -instance one developer creates a new file, uses it at many places, +instance, one developer creates a new file, uses it at many places, but forget to commit it. Another developer then checkout the incomplete project and is able to run `make dist' successfully, even though a file is missing. @@ -8584,7 +8584,7 @@ It is also not uncommon to override a user variable at @command{make}-time. Many installers do this with @code{prefix}, but -this can be useful with compiler flags too. For instance if, while +this can be useful with compiler flags too. For instance, if, while debugging a C++ project, you need to disable optimization in one specific object file, you can run something like @@ -8633,7 +8633,7 @@ variables in all @file{Makefile}s. What we recommend is that you define extra flags in separate -variables. For instance you may write an Autoconf macro that computes +variables. For instance, you may write an Autoconf macro that computes a set of warning options for the C compiler, and @code{AC_SUBST} them in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that determines which compiler and which linker flags should be used to @@ -8660,7 +8660,7 @@ every target in a @file{Makefile.in}. Using variables like this gives you full control over the ordering of -the flags. For instance if there is a flag in $(WARNINGCFLAGS) that +the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that you want to negate for a particular target, you can use something like @samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all these flags had been forcefully appended to @code{CFLAGS}, there would be no way to @@ -8675,7 +8675,7 @@ @subsection Other Variables There are other variables in Automake that follow similar principles -to allow user options. For instance Texinfo rules (@pxref{Texinfo}) +to allow user options. For instance, Texinfo rules (@pxref{Texinfo}) use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly, DejaGnu tests (@pxref{Tests}) use @code{RUNTESTDEFAULTFLAGS} and @code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules @@ -8690,7 +8690,7 @@ @command{make} itself. However you should not think that all variables ending with address@hidden follow this convention. For instance address@hidden follow this convention. For instance, @code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Dist}), @code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}), are two variables that are only useful to the maintainer and have no @@ -8701,7 +8701,7 @@ Finally you should not think either that the existence of a per-target variable implies that of an @code{AM_} variable or that of a user -variable. For instance the @code{mumble_LDADD} per-target variable +variable. For instance, the @code{mumble_LDADD} per-target variable overrides the global @code{LDADD} variable (which is not a user variable), and @code{mumble_LIBADD} exists only as a per-target variable. @xref{Program and Library Variables}. @@ -8736,7 +8736,7 @@ are used. It's OK to share object files when per-target compilation flags are not -used. For instance @file{true} and @file{false} will both use +used. For instance, @file{true} and @file{false} will both use @file{version.o} in the following example. @example @@ -8762,7 +8762,7 @@ Automake supports per-program and per-library compilation flags (see @ref{Program and Library Variables} and @ref{Flag Variables Ordering}). With this you can define compilation flags that apply to -all files compiled for a target. For instance in +all files compiled for a target. For instance, in @example bin_PROGRAMS = foo @@ -8809,7 +8809,7 @@ compile rules @command{automake} would output for these files. Automake will not define a rule for a target you have defined, so you could think about defining the @samp{foo-foo.o: foo.c} rule yourself. -We recommend against this, because this is error prone. For instance +We recommend against this, because this is error prone. For instance, if you add such a rule to the first example, it will break the day you decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{renamed @@ -8940,7 +8940,7 @@ The above scheme can be extended to handle more outputs and more inputs. One of the outputs is selected to serve as a witness to the successful completion of the command, it depends upon all inputs, and -all other outputs depend upon it. For instance if @command{foo} +all other outputs depend upon it. For instance, if @command{foo} should additionally read @file{data.bar} and also produce @file{data.w} and @file{data.x}, we would write: @@ -9014,7 +9014,7 @@ erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then @command{make} may start both recover rules in parallel. If the two instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS) -data.stamp} concurrently the build is likely to fail (for instance the +data.stamp} concurrently the build is likely to fail (for instance, the two rules will create @file{data.tmp}, but only one can rename it). Admittedly, such a weird situation does not arise during ordinary @@ -9196,7 +9196,7 @@ Of course not all tools are as advanced as Python regarding that substitution of @var{prefix}. So another strategy is to figure the part of the of the installation directory that must be preserved. For -instance here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp}) +instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp}) computes @samp{$(lispdir)}: @example @@ -9343,7 +9343,7 @@ Tracking Evolution}), this version also supplies a 9-page manual. At this time @command{aclocal} and @code{AM_INIT_AUTOMAKE} did not -exist, so many things had to be done by hand. For instance here is +exist, so many things had to be done by hand. For instance, here is what a configure.in (this is the former name of the @file{configure.ac} we use today) must contain in order to use Automake 0.20: @@ -9461,7 +9461,7 @@ Automake did only know about the @file{Makefile.am}s it processed. @file{configure.in} was Autoconf's world and the link between Autoconf and Automake had to be done by the @file{Makefile.am} author. For -instance if @file{config.h} was generated by @file{configure}, it was the +instance, if @file{config.h} was generated by @file{configure}, it was the package maintainer's responsibility to define the @code{CONFIG_HEADER} variable in each @file{Makefile.am}. @@ -9829,7 +9829,7 @@ Some of these breakages were effectively bugs that would eventually be fixed in the next release. However, a lot of damage was caused by some changes made deliberately to render Automake stricter on some -setup we did consider bogus. For instance @samp{make distcheck} was +setup we did consider bogus. For instance, @samp{make distcheck} was improved to check that @samp{make uninstall} did remove all the files @samp{make install} installed, that @samp{make distclean} did not omit some file, and that a VPATH build would work even if the source