Hello Alexandre,
* Alexandre Duret-Lutz wrote on Wed, Aug 16, 2006 at 07:28:29PM CEST:
> Here is the patch. make distcheck is still running, but anyway
> I'll let this patch mellow until the week-end.
May I suggest the following patch, to be applied after yours?
(Or you could combine the two, however you like.)
Notes:
- the @/ I added below within the @uref are ineffectual ATM, but this
way you don't have to think much when changing the text.
- I could not help doing the en_UK -> en_US thing again, for
consistency.
- Some `the @file{foo}' -> `the @file{foo} file' or similar
to ease understanding.
- the DESTDIR example was broken in that the file `file.lst' would
inadvertently end up in the tarball.
> I haven't changed the prompt or font usage for "Makefile". I'm
> not against these changes, it just that they'd require a full
> pass over the manual anyway, so that can be done separately.
Sure.
Cheers,
Ralf
* doc/automake.texi: Fix some typos in the introduction,
adjust some spacing; spell `GNU Build System' consistently.
(menu): Unify node naming.
(Standard Directory Variables): Clarify that this list is not
exhaustive.
(DESTDIR): Fix example.
--- doc/automake.texi 2006-08-16 21:10:32.000000000 +0200
+++ doc/automake.texi 2006-08-16 22:13:12.000000000 +0200
@@ -127,13 +127,13 @@
An Introduction to the Autotools
* GNU Build System:: Introducing the GNU Build System
-* Use Cases:: Use case for the GNU Build System
+* Use Cases:: Use Cases for the GNU Build System
* Why Autotools:: How Autotools Help
* Hello World:: A Small Hello World Package
Use Cases for the GNU Build System
-* Basic Installation:: Common installtion procedure
+* Basic Installation:: Common installation procedure
* Standard Targets:: A list of standard Makefile targets
* Standard Directory Variables:: A list of standard directory variables
* Standard Configuration Variables:: Using configuration variables
@@ -380,24 +380,24 @@
If you are new to Automake, maybe you know that it is part of a set of
tools called @emph{The Autotools}. Maybe you've already delved into a
package full of files named @file{configure}, @file{configure.ac},
[EMAIL PROTECTED], @file{Makefile.am}, @file{aclocal.m4}, @dots{}
[EMAIL PROTECTED], @file{Makefile.am}, @file{aclocal.m4}, @dots{},
some of them claiming to be @emph{generated by} Autoconf or Automake.
But the exact purpose of these files and their relations is probably
-fuzzy. The goal of this chapter is to introduce you this machinery,
+fuzzy. The goal of this chapter is to introduce you to this machinery,
to show you how it works and how powerful it is. If you've never
installed or seen such a package, do not worry: this chapter will walk
you through it.
If you need some teaching material, more illustrations, or a less
[EMAIL PROTECTED] continuation, some slides for this
[EMAIL PROTECTED] continuation, some slides for this
introduction are available in Alexandre Duret-Lutz's
[EMAIL PROTECTED] Turorial,
-http://www-src.lip6.fr/~Alexandre.Duret-Lutz/autotools.html}.
[EMAIL PROTECTED] Tutorial,
+http://www-src.lip6.fr/@/~Alexandre.Duret-Lutz/@/autotools.html}.
This chapter is the written version of the first part of his tutorial.
@menu
* GNU Build System:: Introducing the GNU Build System
-* Use Cases:: Use case for the GNU Build System
+* Use Cases:: Use Cases for the GNU Build System
* Why Autotools:: How Autotools Help
* Hello World:: A Small Hello World Package
@end menu
@@ -406,8 +406,8 @@
@section Introducing the GNU Build System
@cindex GNU Build System, introduction
-It is a truth universally acknowledged, that a developer in
-possession of a new package, must be in want of a build system.
+It is a truth universally acknowledged that a developer in
+possession of a new package must be in want of a build system.
In the Unix world, such a build system is traditionally achieved using
the command @command{make} (@pxref{Top, , Overview, make, The GNU Make
@@ -419,12 +419,12 @@
compiler on @file{main.c}; etc. Each time @command{make} is run, it
reads @file{Makefile}, checks the existence and modification time of
the files mentioned, decides what files need to be built (or rebuilt),
-and run the associated commands.
+and runs the associated commands.
When a package needs to be built on a different platform than the one
it was developed on, its @file{Makefile} usually needs to be adjusted.
For instance the compiler may have another name or require more
-options. In 1991, David J. MacKenzie got tired of customising
+options. In 1991, David J. MacKenzie got tired of customizing
@file{Makefile} for the 20 platforms he had to deal with. Instead, he
handcrafted a little shell script called @file{configure} to
automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis,
@@ -433,7 +433,7 @@
@cindex GNU Coding Standards
-Today this process has been standardised in the GNU project. The GNU
+Today this process has been standardized in the GNU project. The GNU
Coding Standards (@pxref{Managing Releases, The Release Process, ,
standards, The GNU Coding Standards}) explains how each package of the
GNU project should have a @file{configure} script, and the minimal
@@ -462,7 +462,7 @@
@cindex GNU Build System, use cases
@cindex GNU Build System, features
@cindex Features of the GNU Build System
[EMAIL PROTECTED] Use cases for the GNU Build System
[EMAIL PROTECTED] Use Cases for the GNU Build System
@cindex @file{amhello-1.0.tar.gz}, location
@cindex @file{amhello-1.0.tar.gz}, use cases
@@ -480,14 +480,14 @@
Some of the following use cases present features that are in fact
extensions to the GNU Build System. Read: they are not specified by
-the GNU Coding Standard, but they are nonetheless part of the build
-system created by the Autotools. To keep things simple we do not
+the GNU Coding Standards, but they are nonetheless part of the build
+system created by the Autotools. To keep things simple, we do not
point out the difference. Our objective is to show you many of the
features that the build system created by the Autotools will offer to
you.
@menu
-* Basic Installation:: Common installtion procedure
+* Basic Installation:: Common installation procedure
* Standard Targets:: A list of standard Makefile targets
* Standard Directory Variables:: A list of standard directory variables
* Standard Configuration Variables:: Using configuration variables
@@ -540,7 +540,7 @@
The user then enters the newly created directory to run the
@file{configure} script. This script probes the system for various
-features, and finally create the @file{Makefile}s. In this toy
+features, and finally creates the @file{Makefile}s. In this toy
example there are only two @file{Makefile}s, but in real-world project
there may be many more, usually one @file{Makefile} per directory.
@@ -558,12 +558,12 @@
@cindex su, before @code{make install}
After everything has been built, and maybe tested, it is time to
-install them on the system. That means copying the programs,
+install it on the system. That means copying the programs,
libraries, header files, scripts, and other data files from the
source directory to their final destination on the system. The
-command @code{make install} will do that. However by default
+command @code{make install} will do that. However, by default
everything will be installed in subdirectories of @file{/usr/local}:
-binaries will go into @file{/usr/local/bin}, libraries will end into
+binaries will go into @file{/usr/local/bin}, libraries will end up in
@file{/usr/local/lib}, etc. This destination is usually not writable
by any user, so we assume that we have to become root before we can
run @code{make install}. In our example, running @code{make install}
@@ -572,13 +572,13 @@
A last and optional step is to run @code{make installcheck}. This
command may run tests on the installed files. @code{make check} tests
-the files in the source tree while @code{make installcheck} tests
+the files in the source tree, while @code{make installcheck} tests
their installed copies. The tests run by the latter can be different
-from those run by former. For instance, there are tests that cannot
-be run in the source tree. Conversely, some packages are set up so
-that @code{make installcheck} will run the very same tests as
+from those run by the former. For instance, there are tests that
+cannot be run in the source tree. Conversely, some packages are set
+up so that @code{make installcheck} will run the very same tests as
@code{make check}, only on different files (non-installed
-vs. installed). It can make a difference, for instance when the
+vs.@: installed). It can make a difference, for instance when the
source tree's layout is different from that of the installation.
Furthermore it may help to diagnose an incomplete installation.
@@ -603,7 +603,7 @@
@table @code
@item make all
@trindex all
-Build programs, libraries, documentation, etc. (Same as @code{make}.)
+Build programs, libraries, documentation, etc.@: (same as @code{make}).
@item make install
@trindex install
Install what needs to be installed, copying the files from the
@@ -611,7 +611,7 @@
@item make install-strip
@trindex install-strip
Same as @code{make install}, then strip debugging symbols. Some
-users like to trade space for useful bug reports...
+users like to trade space for useful bug [EMAIL PROTECTED]
@item make uninstall
@trindex uninstall
The opposite of @code{make install}: erase the installed files.
@@ -639,7 +639,7 @@
@cindex directory variables
The GNU Coding Standards also specify a hierarchy of variables to
-denote installation directories.
+denote installation directories. Some of these are:
@multitable {Directory variable} [EMAIL
PROTECTED]@code{datarootdir}/doc/@code{PACKAGE}}}
@headitem Directory variable @tab Default value
@@ -675,7 +675,7 @@
@opindex --prefix
-A user who wish to install a package on his own account could proceed
+A user who wishes to install a package on his own account could proceed
as follows:
@example
@@ -741,7 +741,7 @@
@cindex @file{config.site} example
When installing several packages using the same setup, it can be
-convenient to create a @file{config.site} to capture common settings.
+convenient to create a file to capture common settings.
If a file named @[EMAIL PROTECTED]/share/config.site} exists,
@command{configure} will source it at the beginning of its execution.
@@ -753,8 +753,8 @@
@end example
Assuming we are installing many package in @file{~/usr}, and will
-always want to use these definition of @code{CC}, @code{CPPFLAGS}, and
[EMAIL PROTECTED], we can automatize this by creating the following
+always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and
[EMAIL PROTECTED], we can automate this by creating the following
@file{~/usr/share/config.site} file:
@example
@@ -763,7 +763,7 @@
test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
@end example
-Now any time a @file{configure} script is using the @file{~/usr}
+Now, any time a @file{configure} script is using the @file{~/usr}
prefix, it will execute the above @file{config.site} and define
these three variables.
@@ -778,22 +778,22 @@
@node VPATH Builds
[EMAIL PROTECTED] Parallel Build Trees (a.k.a. VPATH Builds)
[EMAIL PROTECTED] Parallel Build Trees (a.k.a.@: VPATH Builds)
@cindex Parallel build trees
@cindex VPATH builds
@cindex source tree and build tree
@cindex build tree and source tree
[EMAIL PROTECTED] trees, source vs. build
[EMAIL PROTECTED] trees, source vs.@: build
The GNU Build System distinguishes two trees: the source tree, and
the build tree.
The source tree is rooted in the directory containing
[EMAIL PROTECTED] it contains all the sources files (those that are
[EMAIL PROTECTED] It contains all the sources files (those that are
distributed), and may be arranged using several subdirectories.
-The build tree is rooted in the directory where the @file{configure}
-were run, and is populated with all object files, programs, libraries,
+The build tree is rooted in the directory in which @file{configure}
+was run, and is populated with all object files, programs, libraries,
and other derived files built from the sources (and hence not
distributed). The build tree usually has the same subdirectory layout
as the source tree; its subdirectories are created automatically by
@@ -801,7 +801,7 @@
If @file{configure} is executed in its own directory, the source and
build trees are combined: derived files are constructed in the same
-directory as their sources. This was the case in our first
+directories as their sources. This was the case in our first
installation example (@pxref{Basic Installation}).
A common request from users is that they want to confine all derived
@@ -941,7 +941,7 @@
...
@end example
-On the second host, however, we need only to install the
+On the second host, however, we need only install the
architecture-specific files.
@example
[HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
@@ -957,10 +957,10 @@
@node Cross-Compilation
@subsection Cross-Compilation
[EMAIL PROTECTED] Cross-compilation
[EMAIL PROTECTED] cross-compilation
To @dfn{cross-compile} is to build on one platform a binary that will
-be run on another platform. When speaking of cross-compilation, it is
+run on another platform. When speaking of cross-compilation, it is
important to distinguish between the @dfn{build platform} on which
the compilation is performed, and the @dfn{host platform} on which the
resulting executable is expected to run. The following
@@ -976,7 +976,7 @@
@end table
When the @option{--host} is used, @command{configure} will search for
-the cross-compiling suite for this platform. cross-compilation tools
+the cross-compiling suite for this platform. Cross-compilation tools
commonly have their target architecture as prefix of their name. For
instance my cross-compiler for MinGW32 has its binaries called
@code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
@@ -1039,7 +1039,7 @@
@cindex Transforming program names
@cindex Programs, renaming during installation
-The GNU build system provides means to automatically rename
+The GNU Build System provides means to automatically rename
executables before they are installed. This is especially convenient
when installing a GNU package on a system that already has a
proprietary implementation you do not want to overwrite. For instance,
@@ -1076,10 +1076,10 @@
@subsection Building Binary Packages Using DESTDIR
@vindex DESTDIR
-The GNU build system's @code{make install} and @code{make uninstall}
+The GNU Build System's @code{make install} and @code{make uninstall}
interface does not exactly fit the needs of a system administrator
who has to deploy and upgrade packages on lots of hosts. In other
-words, the GNU build system does not replace a package manager.
+words, the GNU Build System does not replace a package manager.
Such package managers usually need to know which files have been
installed by a package, so a mere @code{make install} is
@@ -1109,15 +1109,15 @@
~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
@dots{}
~/amhello-1.0 % @kbd{cd ~/inst}
-~/inst % @kbd{find . -type f -print > files.lst}
-~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat file.lst`}
+~/inst % @kbd{find . -type f -print > ../files.lst}
+~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../file.lst`}
./usr/bin/hello
./usr/share/doc/amhello/README
@end example
After this example, @code{amhello-1.0-i686.tar.gz} is ready to be
-uncompressed in @file{/} on many hosts. (Using @code{`cat file.lst`}
-instead of @samp{.} as argument for @command{tar} avoid entries for
+uncompressed in @file{/} on many hosts. (Using @code{`cat ../file.lst`}
+instead of @samp{.} as argument for @command{tar} avoids entries for
each subdirectory in the archive: we would not like @command{tar} to
restore the modification time of @file{/}, @file{/usr/}, etc.)
@@ -1138,7 +1138,7 @@
@cindex Distributions, preparation
We have already mentioned @code{make dist}. This target collects all
-your source files, and the necessary parts of the build system, to
+your source files and the necessary parts of the build system to
create a tarball named @[EMAIL PROTECTED]@var{version}.tar.gz}.
@cindex @code{distcheck} better than @code{dist}
@@ -1146,7 +1146,7 @@
Another, more useful command is @code{make distcheck}. The
@code{distcheck} target constructs
@[EMAIL PROTECTED]@var{version}.tar.gz} just as well as @code{dist},
-but it additionally ensures most of the use-cases presented so far
+but it additionally ensures most of the use cases presented so far
work:
@itemize @bullet
@@ -1247,7 +1247,7 @@
been created by Autoconf and friends) can be nested to arbitrary
depth.
-A typical setup is that a package A will distribute one of the library
+A typical setup is that a package A will distribute one of the libraries
it needs in a subdirectory. This library B is a complete package with
its own GNU Build System. The @command{configure} script of A will
run the @command{configure} script of B as part of its execution,
@@ -1313,7 +1313,7 @@
Yet there also exist reasons why you may want NOT to use the
[EMAIL PROTECTED] For instance you may be already using (or used to)
another incompatible build system. Autotools will only be useful if
-you do accept the concepts of GNU Build System. People who have their
+you do accept the concepts of the GNU Build System. People who have their
own idea of how a build system should work will feel frustrated by the
Autotools.
@@ -1489,7 +1489,7 @@
creating @file{configure} from @file{configure.ac}, while
@command{automake} is in charge of creating @file{Makefile.in}s from
@file{Makefile.am}s and @file{configure.ac}. This should at least
-direct you to the correct manual when seeking answers.
+direct you to the right manual when seeking answers.
@node amhello Explained
@@ -1576,13 +1576,13 @@
@end smallexample
As you probably noticed, @file{src/main.c} includes @file{config.h} so
-it can use @code{PACKAGE_STRING}. In a real work project,
+it can use @code{PACKAGE_STRING}. In a real-world project,
@file{config.h} can grow really big, with one @samp{#define} per
feature probed on the system.
The @code{AC_CONFIG_FILES} macro declares the list of files that
[EMAIL PROTECTED] should create from their @file{*.in} template.
-Automake also scans this list to find the @file{Makefile.am} it must
[EMAIL PROTECTED] should create from their @file{*.in} templates.
+Automake also scans this list to find the @file{Makefile.am} files it must
process. (This is important to remember: when adding a new directory
to your project, you should add its @file{Makefile} to this list,
otherwise Automake will never process the new @file{Makefile.am} you
@@ -1618,14 +1618,14 @@
@command{configure}) but will react to certain variable definitions
by generating some build rules and other variables.
Often @file{Makefile.am}s contain only a list of variable definitions as
-above, but it can also contain other variable and rule definitions that
+above, but they can also contain other variable and rule definitions that
@command{automake} will pass along without interpretation.
Variables that end with @code{_PROGRAMS} are special variables
that list programs that the resulting @file{Makefile} should build.
In Automake speak, this @code{_PROGRAMS} suffix is called a
@dfn{primary}; Automake recognizes other primaries such as
[EMAIL PROTECTED], @code{_DATA}, @code{_LIBRARIES}, etc. corresponding
[EMAIL PROTECTED], @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
to different types of files.
The @samp{bin} part of the @code{bin_PROGRAMS} tells
