From 87b665e53a60c8020a6a172b5f3e56c65cf7e417 Mon Sep 17 00:00:00 2001 From: William Pursell Date: Mon, 1 Dec 2008 21:06:32 +0000 Subject: [PATCH] Simple typographical and grammar errors in automake.texi. * doc/automake.texi: Fix object/article consistency (eg "an flag" becomes "a flag"), correct minor punctuation errors, etc. --- ChangeLog | 4 ++ doc/automake.texi | 123 +++++++++++++++++++++++++++--------------------------- 2 files changed, 66 insertions(+), 61 deletions(-) diff --git a/ChangeLog b/ChangeLog index e866c0456..d0d82cade 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,9 @@ 2008-12-03 William Pursell + Simple typographical and grammar errors in automake.texi. + * doc/automake.texi: Fix object/article consistency (eg "an + flag" becomes "a flag"), correct minor punctuation errors, etc. + * doc/automake.texi (Auxiliary Programs, Python, Rebuilding): Replace 'configure' with '@command{configure}' as appropriate. diff --git a/doc/automake.texi b/doc/automake.texi index a3d777dbb..52b178b98 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -6108,11 +6108,11 @@ Any flags to pass to the Objective C compiler. The maintainer's variant of @code{OBJCFLAGS}. @item OBJCCOMPILE -The command used to actually compile a Objective C source file. The +The command used to actually compile an Objective C source file. The file name is appended to form the complete command line. @item OBJCLINK -The command used to actually link a Objective C program. +The command used to actually link an Objective C program. @end vtable @@ -6128,7 +6128,7 @@ Any package including Unified Parallel C code must define the output variable @code{UPC} in @file{configure.ac}; the simplest way to do this is to use the @code{AM_PROG_UPC} macro (@pxref{Public macros}). -A few additional variables are defined when an Unified Parallel C +A few additional variables are defined when a Unified Parallel C source file is seen: @vtable @code @@ -6694,8 +6694,8 @@ bin_PROGRAMS = liver$(EXEEXT) The targets Automake generates are likewise given the @samp{$(EXEEXT)} extension. -The variables @code{TESTS}, @code{XFAIL_TESTS} (@pxref{Tests}) are also -rewritten if it contains filenames that have been declared as programs +The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Tests}) are also +rewritten if they contain filenames that have been declared as programs in the same @file{Makefile}. (This is mostly useful when some programs from @code{check_PROGRAMS} are listed in @code{TESTS}.) @@ -6777,7 +6777,7 @@ prefix as with other primaries. Scripts can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir}, or @code{pkgdatadir}. -Scripts that need not being installed can be listed in +Scripts that need not be installed can be listed in @code{noinst_SCRIPTS}, and among them, those which are needed only by @samp{make check} should go in @code{check_SCRIPTS}. @@ -6819,7 +6819,7 @@ AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script]) @end example @noindent -to build @file{src/my_script} from @file{src/my_script.in}, then an +to build @file{src/my_script} from @file{src/my_script.in}, then a @file{src/Makefile.am} to install this script in @code{$(bindir)} can be as simple as @@ -7064,7 +7064,7 @@ bindir.h: Makefile echo '#define bindir "$(bindir)"' >$@@ @end example -See how @file{bindir.h} get built first: +See how @file{bindir.h} gets built first: @example % make @@ -7144,7 +7144,7 @@ Directories, autoconf, The Autoconf Manual}), or by processing a Autoconf Manual}). At this point it should be clear that building @file{bindir.h} from -@file{configure} work well for this example. @file{bindir.h} will exist +@file{configure} works well for this example. @file{bindir.h} will exist before you build any target, hence will not cause any dependency issue. The Makefile can be shrunk as follows. We do not even have to mention @@ -7157,7 +7157,7 @@ foo_SOURCES = foo.c However, it's not always possible to build sources from @file{configure}, especially when these sources are generated by a tool -that needs to be built first... +that needs to be built first. @unnumberedsubsec Build @file{bindir.c}, not @file{bindir.h}. @@ -7254,7 +7254,7 @@ ELCFILES = @code{ELCFILES} is an internal Automake variable that normally lists all @file{.elc} files that must be byte-compiled. Automake defines @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this -variable explicitly prevents byte-compilation to occur. +variable explicitly prevents byte-compilation. Since Automake 1.8, we now recommend using @code{lisp_DATA} instead. As in @@ -7279,7 +7279,7 @@ internationalization (@pxref{Top, , Introduction, gettext, GNU gettext utilities}). The @code{gettext} support in Automake requires the addition of one or -two subdirectories to the package, @file{po} and possibly also @file{intl}. +two subdirectories to the package: @file{po} and possibly also @file{intl}. The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the @samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used. Automake ensures that these directories exist and are mentioned in @@ -7385,7 +7385,7 @@ 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 variables @code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source -files in your @file{Makefile.am}, depending where you want your files +files in your @file{Makefile.am}, depending on where you want your files installed (see the definitions of @code{pythondir} and @code{pkgpythondir} below). @@ -7634,7 +7634,7 @@ use this. By default, info pages are installed by @samp{make install}, so running @code{make install-info} is pointless. This can be prevented via the @code{no-installinfo} option. In this case, @file{.info} files are not installed by default, and user must -request this explicitly using @samp{make install-info} +request this explicitly using @samp{make install-info}. The following variables are used by the Texinfo build rules. @@ -7685,7 +7685,7 @@ The name of the command that translates a @file{.texi} file into a @file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}. @item DVIPS -The name of the command that build a @file{.ps} file out of a +The name of the command that builds a @file{.ps} file out of a @file{.dvi} file. This defaults to @samp{dvips}. @item TEXINFO_TEX @@ -7834,7 +7834,8 @@ suppress the base name step. For example: nobase_include_HEADERS = stdio.h sys/types.h @end example -Will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h} +@noindent +will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h} in @samp{$(includedir)/sys}. For most file types, Automake will install multiple files at once, while @@ -8022,7 +8023,7 @@ We recommend that you follow this same set of heuristics in your @trindex dist The @code{dist} rule in the generated @file{Makefile.in} can be used to generate a gzipped @code{tar} file and other flavors of archive for -distribution. The files is named based on the @code{PACKAGE} and +distribution. The file is named based on the @code{PACKAGE} and @code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE} (@pxref{Macros}); more precisely the gzipped @code{tar} file is named @samp{@var{package}-@var{version}.tar.gz}. @@ -8227,7 +8228,7 @@ correctly coded your @code{uninstall}-related rules. By default, the checking is done by the @code{distuninstallcheck} rule, and the list of files in the install tree is generated by -@samp{$(distuninstallcheck_listfiles}) (this is a variable whose value is +@samp{$(distuninstallcheck_listfiles)} (this is a variable whose value is a shell command to run that prints the list of files to stdout). Either of these can be overridden to modify the behavior of @@ -8610,9 +8611,9 @@ ignored in sub-packages of nested packages (@pxref{Subpackages}). @item @option{no-define} @cindex Option, @option{no-define} @opindex no-define -This options is meaningful only when passed as an argument to +This option is meaningful only when passed as an argument to @code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and -@code{VERSION} variables to be @code{AC_DEFINE}d. +@code{VERSION} variables from being @code{AC_DEFINE}d. @item @option{no-dependencies} @cindex Option, @option{no-dependencies} @@ -8751,7 +8752,7 @@ when generating tarballs with @samp{make dist}. (The tar file created is then compressed according to the set of @option{no-dist-gzip}, @option{dist-bzip2}, @option{dist-lzma} and @option{dist-tarZ} options in use.) -These options must be passed as argument to @code{AM_INIT_AUTOMAKE} +These options must be passed as arguments to @code{AM_INIT_AUTOMAKE} (@pxref{Macros}) because they can require additional configure checks. Automake will complain if it sees such options in an @code{AUTOMAKE_OPTIONS} variable. @@ -8883,7 +8884,7 @@ Automake will also generate an @code{ID} rule that will run directory-by-directory basis. @trindex id -Finally, Automake also emit rules to support the +Finally, Automake also emits 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} @@ -8902,7 +8903,7 @@ 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 that could compile @file{.foo} -files to @file{.o} files. You would simply define an suffix rule for +files to @file{.o} files. You would simply define a suffix rule for your language: @example @@ -8919,14 +8920,14 @@ doit_SOURCES = doit.foo @end example This was the simpler and more common case. In other cases, you will -have to help Automake to figure which extensions you are defining your -suffix rule for. This usually happens when your extensions does not +have to help Automake to figure out which extensions you are defining your +suffix rule for. This usually happens when your extension does not start with a dot. Then, all you have to do is to put a list of new suffixes in the @code{SUFFIXES} variable @strong{before} you define your implicit rule. -For instance, the following definition prevents Automake to misinterpret -@samp{.idlC.cpp:} as an attempt to transform @file{.idlC} files into +For instance, the following definition prevents Automake from misinterpreting +the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into @file{.cpp} files. @example @@ -9300,7 +9301,7 @@ With some minor exceptions (for example @code{_PROGRAMS} variables, @cindex copying semantics -These copying semantics means that many problems can be worked around +These copying semantics mean that many problems can be worked around by simply adding some @command{make} variables and rules to @file{Makefile.am}. Automake will ignore these additions. @@ -9314,10 +9315,10 @@ different places (@file{Makefile.am}, @file{configure.ac}, and @command{automake} itself), it is possible to have conflicting definitions of rules or variables. When building @file{Makefile.in} the following priorities are respected by @command{automake} to ensure -the user always have the last word. User defined variables in +the user always has the last word. User defined variables in @file{Makefile.am} have priority over variables @code{AC_SUBST}ed from @file{configure.ac}, and @code{AC_SUBST}ed variables have priority -over @command{automake}-defined variables. As far rules are +over @command{automake}-defined variables. As far as rules are concerned, a user-defined rule overrides any @command{automake}-defined rule for the same target. @@ -9329,10 +9330,10 @@ These overriding semantics make it possible to fine tune some default settings of Automake, or replace some of its rules. Overriding Automake rules is often inadvisable, particularly in the topmost directory of a package with subdirectories. The @option{-Woverride} -option (@pxref{Invoking Automake}) comes handy to catch overridden +option (@pxref{Invoking Automake}) comes in handy to catch overridden definitions. -Note that Automake does not make any difference between rules with +Note that Automake does not make any distinction between rules with commands and rules that only specify dependencies. So it is not possible to append new dependencies to an @command{automake}-defined target without redefining the entire rule. @@ -9590,7 +9591,7 @@ and @samp{@@top_builddir@@} are defined by @file{configure} when it processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset Output Variables, autoconf, The Autoconf Manual}), they are not computed by the Makefile like the aforementioned @samp{$(distdir)} and -@samp{$(top_distdir)} variables.. +@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 @@ -9600,7 +9601,7 @@ versions. @cindex @file{GNUmakefile} including @file{Makefile} Here are two other ideas. If GNU make is assumed, one possibility is to add to that subdirectory a @file{GNUmakefile} that defines the -required targets and include the third-party @file{Makefile}. For +required targets and includes the third-party @file{Makefile}. For this to work in VPATH builds, @file{GNUmakefile} must lie in the build directory; the easiest way to do this is to write a @file{GNUmakefile.in} instead, and have it processed with @@ -9654,7 +9655,7 @@ EXTRA_DIST = subdir/Makefile subdir/program.c ... Pushing this idea to the extreme, it is also possible to ignore the subproject build system and build everything from this proxy -@file{Makefile.am}. This might sounds very sensible if you need VPATH +@file{Makefile.am}. This might sound very sensible if you need VPATH builds but the subproject does not support them. @node Distributing @@ -9681,7 +9682,7 @@ version. Things get worse when maintaining a large tree of packages, each one requiring a different version of Automake. In the past, this meant that -any developer (and sometime users) had to install several versions of +any developer (and sometimes users) had to install several versions of Automake in different places, and switch @samp{$PATH} appropriately for each package. @@ -9919,15 +9920,15 @@ happen. CVS's timestamp handling can also let you think an out-of-date file is up-to-date. For instance, suppose a developer has modified @file{Makefile.am} and -has rebuilt @file{Makefile.in}. He then decide to do a last-minute +has rebuilt @file{Makefile.in}. He then decides to do a last-minute change to @file{Makefile.am} right before checking in both files (without rebuilding @file{Makefile.in} to account for the change). -This last change to @file{Makefile.am} make the copy of +This last change to @file{Makefile.am} makes the copy of @file{Makefile.in} out-of-date. Since CVS processes files -alphabetically, when another developer @samp{cvs update} his or her +alphabetically, when another developer @samp{cvs update}s his or her tree, @file{Makefile.in} will happen to be newer than -@file{Makefile.am}. This other developer will not see +@file{Makefile.am}. This other developer will not see that @file{Makefile.in} is out-of-date. @end itemize @@ -9993,7 +9994,7 @@ 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 @command{autoconf} is not installed. When all distributed files are -kept under CVS, this feature of @command{missing} allows user +kept under CVS, this feature of @command{missing} allows a user @emph{with no maintainer tools} to build a package off CVS, bypassing any timestamp inconsistency implied by @samp{cvs update}. @@ -10009,13 +10010,13 @@ the build continue is one of the arguments of the @cindex @code{AM_MAINTAINER_MODE}, purpose @acindex AM_MAINTAINER_MODE -@code{AM_MAINTAINER_MODE} allows to choose whether the so called +@code{AM_MAINTAINER_MODE} allows you to choose whether the so called "rebuild rules" should be enabled or disabled. With @code{AM_MAINTAINER_MODE([enable])}, they are enabled by default, otherwise they are disabled by default. In the latter case, 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. +rebuild @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs, etc. I.e., this disables build rules for files that are usually distributed and that users should normally not have to update. @@ -10035,7 +10036,7 @@ rules that need exotic tools that users may not have available. Several years ago Fran@,{c}ois Pinard pointed out several arguments against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to insecurity. By removing dependencies you get non-dependable builds: -change to sources files can have no effect on generated files and this +changes to sources files can have no effect on generated files and this can be very confusing when unnoticed. He adds that security shouldn't be reserved to maintainers (what @option{--enable-maintainer-mode} suggests), on the contrary. If one user has to modify a @@ -10118,7 +10119,7 @@ generate file lists in @file{Makefile.am} or in separate Even if you don't care about portability, and are tempted to use @samp{$(wildcard ...)} anyway because you target only GNU Make, you -should know there are many places where Automake need to know exactly +should know there are many places where Automake needs to know exactly which files should be processed. As Automake doesn't know how to expand @samp{$(wildcard ...)}, you cannot use it in these places. @samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed @@ -10150,7 +10151,7 @@ Portable POSIX file names cannot contain components that exceed a 14-byte limit, but nowadays it's normally safe to assume the more-generous @acronym{XOPEN} limit of 255 bytes. @acronym{POSIX} limits file names to 255 bytes (@acronym{XOPEN} allows 1023 bytes), -but you may want to limit a source tarball to file names to 99 bytes +but you may want to limit a source tarball to file names of 99 bytes to avoid interoperability problems with old versions of @command{tar}. If you depart from these rules (e.g., by using non-@acronym{ASCII} @@ -10227,7 +10228,7 @@ proceed with an example. Suppose our package contains a program for which we want to build a man page using @command{help2man}. GNU @command{help2man} produces simple manual pages from the @option{--help} and @option{--version} output of other commands (@pxref{Top, , Overview, -help2man, The Help2man Manual}). Because we don't to force want our +help2man, The Help2man Manual}). Because we don't want to force our users to install @command{help2man}, we decide to distribute the generated man page using the following setup. @@ -10255,8 +10256,8 @@ Why was @file{foo.1} rebuilt? Because although distributed, will always appear to be newer than the distributed @file{foo.1}. @samp{make distcheck} caught an inconsistency in our package. Our -intent was to distribute @file{foo.1} so users do not need installing -@command{help2man}, however since this our rule causes this file to be +intent was to distribute @file{foo.1} so users do not need to install +@command{help2man}, however since this rule causes this file to be always rebuilt, users @emph{do} need @command{help2man}. Either we should ensure that @file{foo.1} is not rebuilt by users, or there is no point in distributing @file{foo.1}. @@ -10488,7 +10489,7 @@ AM_CPPFLAGS = -DDATADIR=\"$(datadir)\" @end example @noindent -is all what is needed here if no per-target flags are used. +is all that is needed here if no per-target flags are used. You should not add options to these user variables within @file{configure} either, for the same reason. Occasionally you need @@ -10549,7 +10550,7 @@ DejaGnu tests (@pxref{Tests}) use @code{RUNTESTDEFAULTFLAGS} and (@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS}, @code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules (@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None -of these rules supports per-target flags (yet). +of these rules support per-target flags (yet). To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories}) obeys this naming scheme. The slight difference is that @@ -10558,7 +10559,7 @@ obeys this naming scheme. The slight difference is that However you should not think that all variables ending with @code{FLAGS} follow this convention. For instance, -@code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Dist}), +@code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Dist}) and @code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}), are two variables that are only useful to the maintainer and have no user counterpart. @@ -10600,7 +10601,7 @@ build two different objects: @file{true-generic.o} and @command{automake} doesn't actually look whether source files are shared to decide if it must rename objects. It will just rename all objects of a target as soon as it sees per-target compilation flags -are used. +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 @@ -11012,15 +11013,15 @@ sysconf_DATA = afile @noindent by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because this is what the GNU Standards require. When such a package is -installed on a FHS compliant system, the installer will have to set +installed on an FHS compliant system, the installer will have to set @samp{--sysconfdir=/etc}. As the maintainer of the package you should not be concerned by such site policies: use the appropriate -standard directory variable to install your files so that installer +standard directory variable to install your files so that the installer can easily redefine these variables to match their site conventions. Installing files that should be used by another package is slightly more involved. Let's take an example and assume you want to install -shared library that is a Python extension module. If you ask Python +a shared library that is a Python extension module. If you ask Python where to install the library, it will answer something like this: @example @@ -11063,7 +11064,7 @@ The @code{AM_PATH_PYTHON} macro uses similar commands to define 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 +part of the installation directory that must be preserved. For instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp}) computes @samp{$(lispdir)}: @@ -11088,7 +11089,7 @@ the search path of emacs, and then substitutes @samp{$@{libdir@}} or @samp{$@{datadir@}} appropriately. The emacs case looks complicated because it processes a list and -expect two possible layouts, otherwise it's easy, and the benefit for +expects two possible layouts, otherwise it's easy, and the benefits for non-root users are really worth the extra @command{sed} invocation. @@ -11254,7 +11255,7 @@ AM_PROGRAMS = foo bar baz (@code{AM_PROGRAMS} has since then been renamed to @code{EXTRA_PROGRAMS}.) -Similarly scripts, static libraries, and data can built and installed +Similarly scripts, static libraries, and data can be built and installed using the @code{LIBRARIES}, @code{SCRIPTS}, and @code{DATA} variables. However @code{LIBRARIES} were treated a bit specially in that Automake did automatically supply the @file{lib} and @file{.a} prefixes. @@ -11274,7 +11275,7 @@ for another purpose, @pxref{Conditional Subdirectories}). @item 1995-11-26 Automake 0.21 -In less time that it takes to cook a frozen pizza, Tom rewrites +In less time than it takes to cook a frozen pizza, Tom rewrites Automake using Perl. At this time Perl 5 is only one year old, and Perl 4.036 is in use at many sites. Supporting several Perl versions has been a source of problems through the whole history of Automake. @@ -11359,7 +11360,7 @@ be really helpful later on. All the third-party Autoconf macros, written mostly by Fran@,cois Pinard (and later Jim Meyering), are distributed in Automake's hand-written @file{aclocal.m4} file. Package maintainers are expected -to extract the necessary macros from this file. (In previous version +to extract the necessary macros from this file. (In previous versions you had to copy and paste them from the manual...) @item 1996-03-11 Automake 0.31 -- 2.11.4.GIT