Patch: FYI: doc updates

[Tom Tromey]

More documentation changes.

Tom

Index: ChangeLog
from  Tom Tromey  <address@hidden>

        * automake.texi (Strictness): Mention Cygnus mode.
        (Cygnus): Updated.
        (Uniform): Likewise.
        (Canonicalization): Likewise.
        (Install): Add `nobase_' to example; typo fix.
        (Clean): Typo.
        (Dist): Expand on putting a directory into EXTRA_DIST.  Insert
        section markers.
        (Options): Texinfo fixes; some text updates.

Index: automake.texi
===================================================================
RCS file: /cvs/automake/automake/automake.texi,v
retrieving revision 1.230
diff -u -r1.230 automake.texi
--- automake.texi 2001/07/27 15:34:14 1.230
+++ automake.texi 2001/07/28 19:27:49
@@ -338,7 +338,12 @@
 For more information on the precise implications of the strictness
 level, see @ref{Gnits}.
 
+Automake also has a special ``cygnus'' mode which 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}.
 
+
 @node Uniform, Canonicalization, Strictness, Generalities
 @section The Uniform Naming Scheme
 
@@ -357,8 +362,11 @@
 @cindex Primary variable, defined
 
 At @code{make} time, certain variables are used to determine which
-objects are to be built.  These variables are called @dfn{primary
-variables}.  For instance, the primary variable @code{PROGRAMS} holds a
+objects are to be built.  The variable names are made of several pieces
+which are concatenated together.
+
+The piece which 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.
 @vindex PROGRAMS
 
@@ -370,16 +378,15 @@
 @vindex pkgincludedir
 @vindex pkgdatadir
 
-A different set of variables is used to decide where the built objects
-should be installed.  These variables are named after the primary
-variables, but have a prefix indicating 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}).  Automake extends this list with
address@hidden, @code{pkgincludedir}, and @code{pkgdatadir}; these are
-the same as the address@hidden versions, but with @samp{@@PACKAGE@@}
-appended.  For instance, @code{pkglibdir} is defined as
address@hidden(libdir)/@@PACKAGE@@}.
+A different set of names is used to decide where the built objects
+should be installed.  These names are prefixes to the primary which
+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}).
+Automake extends this list with @code{pkglibdir}, @code{pkgincludedir},
+and @code{pkgdatadir}; these are the same as the address@hidden
+versions, but with @samp{@@PACKAGE@@} appended.  For instance,
address@hidden is defined as @code{$(libdir)/@@PACKAGE@@}.
 @cvindex PACKAGE
 
 @cindex EXTRA_, prepending
@@ -405,8 +412,8 @@
 sbin_PROGRAMS = @@MORE_PROGRAMS@@
 @end example
 
-Defining a primary variable without a prefix (e.g. @code{PROGRAMS}) is
-an error.
+Defining a primary without a prefix as a variable, e.g.,
address@hidden, is an error.
 
 Note that the common @samp{dir} suffix is left off when constructing the
 variable names; thus one writes @samp{bin_PROGRAMS} and not
@@ -446,7 +453,7 @@
 The special prefix @samp{check} indicates that the objects in question
 should not be built until the @code{make check} command is run.
 
-Possible primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
+The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
 @samp{LISP}, @samp{PYTHON}, @samp{JAVA}, @samp{SCRIPTS}, @samp{DATA},
 @samp{HEADERS}, @samp{MANS}, and @samp{TEXINFOS}.
 @vindex PROGRAMS
@@ -471,18 +478,23 @@
 
 @cindex canonicalizing Automake macros
 
-Sometimes a Makefile variable name is derived from some text the user
-supplies.  For instance, program names are rewritten into Makefile macro
-names.  Automake canonicalizes this text, so that it does not have to
-follow Makefile macro naming rules.  All characters in the name except
-for letters, numbers, the strudel (@@), and the underscore are turned into
-underscores when making macro references.  For example, if your program
-is named @code{sniff-glue}, the derived variable name would be
address@hidden, not @code{sniff-glue_SOURCES}.  The strudel
-is an addition since Automake 1.4c, to make the use of Autoconf
-substitutions in macro names less obfuscating.
+Sometimes a Makefile variable name is derived from some text the
+maintainer supplies.  For instance, a program name listed in
address@hidden is rewritten into the name of a @samp{_SOURCES}
+variable.  In cases like this, Automake canonicalizes the text, so that
+program names and the like do not have to follow Makefile macro naming
+rules.  All characters in the name except for letters, numbers, the
+strudel (@@), and the underscore are turned into underscores when making
+macro references.
+
+For example, if your program is named @code{sniff-glue}, the derived
+variable name would be @code{sniff_glue_SOURCES}, not
address@hidden
 
+The strudel is an addition, to make the use of Autoconf substitutions in
+macro names less obfuscating.
 
+
 @node User Variables, Auxiliary Programs, Canonicalization, Generalities
 @section Variables reserved for the user
 
@@ -3350,10 +3362,10 @@
 suppress the base name step.  For example:
 
 @example
-include_HEADERS = stdio.h sys/types.h
+nobase_include_HEADERS = stdio.h sys/types.h
 @end example
 
-Will include @file{stdio.h} in @code{$(includedir)} and @file{types.h}
+Will install @file{stdio.h} in @code{$(includedir)} and @file{types.h}
 in @code{$(includedir)/sys}.
 
 Automake generates separate @code{install-data} and @code{install-exec}
@@ -3432,7 +3444,7 @@
 @vindex MAINTAINERCLEANFILES
 
 As the GNU Standards aren't always explicit as to which files should be
-removed by which target, we've adopted a heuristic which we believe were
+removed by which target, we've adopted a heuristic which we believe was
 first formulated by Fran@,{c}ois Pinard:
 
 @itemize @bullet 
@@ -3459,6 +3471,8 @@
 @node Dist, Tests, Clean, Top
 @chapter What Goes in a Distribution
 
address@hidden Basics of distribution
+
 @cindex make dist
 @cindex make distcheck
 
@@ -3484,14 +3498,18 @@
 Still, sometimes there are files which 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}.  You can also mention a directory
-there; in this case the entire directory will be recursively copied into
-the distribution.  Please note that this will also copy
address@hidden in the directory, including CVS/RCS version control
-files.
+subdirectories in @code{EXTRA_DIST}.
 
+You can also mention a directory in @code{EXTRA_DIST}; in this case the
+entire directory will be recursively copied into the distribution.
+Please note that this will also copy @emph{everything} in the directory,
+including CVS/RCS version control files.  We recommend against using
+this feature.
+
 @vindex EXTRA_DIST
 
address@hidden Fine-grained distribution control
+
 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
@@ -3512,6 +3530,8 @@
 nodist_foo_SOURCES = do-not-distribute.c
 @end example
 
address@hidden The dist hook
+
 Another way to to use this is for removing unnecessary files that get
 recursively included by specifying a directory in EXTRA_DIST:
 
@@ -3545,6 +3565,8 @@
         cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
 @end example
 
address@hidden Checking the distribution
+
 Automake also generates a @code{distcheck} target which can be of help
 to ensure that a given distribution will actually work.
 @code{distcheck} makes a distribution, and then tries to do a
@@ -3657,7 +3679,7 @@
 @item @code{gnits}
 @itemx @code{gnu}
 @itemx @code{foreign}
address@hidden @code{cygnus}
address@hidden @code{cygnus}
 @cindex Option, gnits
 @cindex Option, gnu
 @cindex Option, foreign
@@ -3667,13 +3689,13 @@
 @code{readme-alpha} and @code{check-news}.
 
 @item @code{ansi2knr}
address@hidden @code{path/ansi2knr}
address@hidden @address@hidden/ansi2knr}
 @cindex Option, ansi2knr
 Turn on automatic de-ANSI-fication.  @xref{ANSI}.  If preceded by a
 path, the generated @file{Makefile.in} will look in the specified
-directory to find the @file{ansi2knr} program.  Generally the path
-should be a relative path to another directory in the same distribution
-(though Automake currently does not check this).
+directory to find the @file{ansi2knr} program.  The path should be a
+relative path to another directory in the same distribution (Automake
+currently does not check this).
 
 @item @code{check-news}
 @cindex Option, check-news
@@ -3813,9 +3835,10 @@
 @file{TAGS} file that includes by reference all @file{TAGS} files from
 subdirectories.
 
-Also, if the variable @code{ETAGS_ARGS} is defined, a @code{tags} target
-will be generated.  This variable is intended for use in directories
-which contain taggable source that @code{etags} does not understand.
+The @code{tags} target will also be generated if the variable
address@hidden is defined.  This variable is intended for use in
+directories which contain taggable source that @code{etags} does not
+understand.
 @vindex ETAGS_ARGS
 
 Here is how Automake generates tags for its source, and for nodes in its
@@ -4069,10 +4092,14 @@
 
 @cindex Cygnus strictness
 
-Cygnus Solutions has slightly different rules for how a
address@hidden is to be constructed.  Passing @samp{--cygnus} to
address@hidden will cause any generated @file{Makefile.in} to comply
-with Cygnus rules.
+Some packages, notably GNU GCC and GNU gdb, have a build environment
+originally written at Cygnus Support (subsequently renamed Cygnus
+Solutions, and then later purchased by Red Hat).  Packages with this
+ancestry are sometimes referred to as ``Cygnus'' trees.
+
+A Cygnus tree has slightly different rules for how a @file{Makefile.in}
+is to be constructed.  Passing @samp{--cygnus} to @code{automake} will
+cause any generated @file{Makefile.in} to comply with Cygnus rules.
 
 Here are the precise effects of @samp{--cygnus}:
 
@@ -4088,9 +4115,8 @@
 Cygnus packages are typically bundled.
 
 @item
address@hidden dist} will look for files in the build directory as well as
-the source directory.  This is required to support putting info files
-into the build directory.
address@hidden dist} is not supported, and the rules for it are not
+generated.  Cygnus-style trees use their own distribution mechanism.
 
 @item
 Certain tools will be searched for in the build tree as well as in the
@@ -4113,7 +4139,10 @@
 @end itemize
 
 GNU maintainers are advised to use @samp{gnu} strictness in preference
-to the special Cygnus mode.
+to the special Cygnus mode.  Some day, perhaps, the differences between
+Cygnus trees and GNU trees will disappear (for instance, as GCC is made
+more standards compliant).  At that time the special Cygnus mode will be
+removed.
 
 
 @node Extending, Distributing, Cygnus, Top
Index: stamp-vti
===================================================================
RCS file: /cvs/automake/automake/stamp-vti,v
retrieving revision 1.129
diff -u -r1.129 stamp-vti
--- stamp-vti 2001/07/27 15:34:14 1.129
+++ stamp-vti 2001/07/28 19:27:49
@@ -1,4 +1,4 @@
address@hidden UPDATED 27 July 2001
address@hidden UPDATED 28 July 2001
 @set UPDATED-MONTH July 2001
 @set EDITION 1.4i
 @set VERSION 1.4i
Index: version.texi
===================================================================
RCS file: /cvs/automake/automake/version.texi,v
retrieving revision 1.202
diff -u -r1.202 version.texi
--- version.texi 2001/07/27 15:34:14 1.202
+++ version.texi 2001/07/28 19:27:49
@@ -1,4 +1,4 @@
address@hidden UPDATED 27 July 2001
address@hidden UPDATED 28 July 2001
 @set UPDATED-MONTH July 2001
 @set EDITION 1.4i
 @set VERSION 1.4i