Re: Autotools Introduction chapter + amhello-1.0.tar.gz

[Ralf Wildenhues]

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},
address@hidden, @file{Makefile.am}, @file{aclocal.m4}, @dots{}
address@hidden, @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
address@hidden continuation, some slides for this
address@hidden continuation, some slides for this
 introduction are available in Alexandre Duret-Lutz's
address@hidden Turorial,
-http://www-src.lip6.fr/~Alexandre.Duret-Lutz/autotools.html}.
address@hidden 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
address@hidden Use cases for the GNU Build System
address@hidden 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 address@hidden
 @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} 
address@hidden@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 @address@hidden/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
address@hidden, we can automatize this by creating the following
+always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and
address@hidden, 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
address@hidden Parallel Build Trees (a.k.a. VPATH Builds)
address@hidden 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
address@hidden trees, source vs. build
address@hidden 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
address@hidden it contains all the sources files (those that are
address@hidden  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
address@hidden Cross-compilation
address@hidden 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 @address@hidden@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
 @address@hidden@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
 address@hidden 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
address@hidden should create from their @file{*.in} template.
-Automake also scans this list to find the @file{Makefile.am} it must
address@hidden 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
address@hidden, @code{_DATA}, @code{_LIBRARIES}, etc. corresponding
address@hidden, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
 to different types of files.
 
 The @samp{bin} part of the @code{bin_PROGRAMS} tells