From: Alexandre Duret-Lutz <adl@gnu.org>
Date: Sun, 25 Apr 2004 10:01:22 +0000 (+0000)
Subject: * doc/automake.texi (Headers): Revamp.
X-Git-Tag: Release-1-8b~28
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=55f9950207c2ab7810348ee053328f6ca68085ed;p=thirdparty%2Fautomake.git

* doc/automake.texi (Headers): Revamp.
---

diff --git a/ChangeLog b/ChangeLog
index 220fda416..df21a0bc4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2004-04-25  Alexandre Duret-Lutz  <adl@gnu.org>
+
+	* doc/automake.texi (Headers): Revamp.
+
 2004-04-24  Alexandre Duret-Lutz  <adl@gnu.org>
 
 	* automake.in (check_typos): Clarify the diagnostic.
diff --git a/doc/automake.texi b/doc/automake.texi
index 414886a05..09e49007b 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -4293,30 +4293,57 @@ Scripts that need not being installed can be listed in
 @cindex Primary variable, HEADERS
 
 @vindex noinst_HEADERS
-
-Header files are specified by the @samp{HEADERS} family of variables.
-Generally header files are not installed, so the @code{noinst_HEADERS}
-variable will be the most used.  @footnote{However, for the case of a
-non-installed header file that is actually used by a particular program,
-we recommend listing it in the program's @samp{_SOURCES} variable
-instead of in @code{noinst_HEADERS}.  We believe this is more clear.}
-@vindex HEADERS
-
-All header files must be listed somewhere; missing ones will not appear
-in the distribution.  Often it is clearest to list uninstalled headers
-with the rest of the sources for a program.  @xref{A Program}.  Headers
-listed in a @samp{_SOURCES} variable need not be listed in any
-@samp{_HEADERS} variable.
-
 @cindex HEADERS, installation directories
 @cindex Installing headers
-
 @vindex include_HEADERS
 @vindex oldinclude_HEADERS
 @vindex pkginclude_HEADERS
 
-Headers can be installed in @code{includedir}, @code{oldincludedir}, or
-@code{pkgincludedir}.
+
+Header files that must be installed are specified by the
+@samp{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
+
+@example
+include_HEADERS = foo.h bar/bar.h
+@end example
+
+@noindent
+will install the two files as @file{$(includedir)/foo.h} and
+@file{$(includedir)/bar.h}.
+
+The @samp{nobase_} prefix is also supported,
+
+@example
+nobase_include_HEADERS = foo.h bar/bar.h
+@end example
+
+@noindent
+will install the two files as @file{$(includedir)/foo.h} and
+@file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
+
+@vindex noinst_HEADERS
+Usually, only header files that accompany installed libraries need to
+be installed.  Headers used by programs or convenience libraries are
+not installed.  The @code{noinst_HEADERS} variable can be used for
+such headers.  However when the header actually belongs to one
+convenient library or program, we recommend listing it in the
+program's or library's @samp{_SOURCES} variable (@pxref{Program
+Sources}) instead of in @code{noinst_HEADERS}.  This is clearer for
+the @file{Makefile.am} reader.  @code{noinst_HEADERS} would be the
+right variable to use in a directory containing only headers and no
+associated library or program.
+
+All header files must be listed somewhere; in a @samp{_SOURCES}
+variable or in a @samp{_HEADERS} variable.  Missing ones will not
+appear in the distribution.
+
+For header files that are built and must not be distributed, use the
+@samp{nodist_} prefix as in @code{nodist_include_HEADERS} or
+@code{nodist_prog_SOURCES}.  If these generated headers are needed
+during the build, you must also ensure they exist before they are
+used, see @xref{Sources}.
 
 
 @node Data
@@ -5946,7 +5973,7 @@ is then compressed according to the set of @code{no-dist-gzip},
 @code{dist-bzip2} and @code{dist-tarZ} options in use.)
 
 These options must be passed as argument to @code{AM_INIT_AUTOMAKE}
-(@xref{Macros}) because they can causes new configure check to be
+(@pxref{Macros}) because they can causes new configure check to be
 performed.  Automake will complain if it sees such option in a
 @code{AUTOMAKE_OPTIONS} variable.
 
diff --git a/doc/stamp-vti b/doc/stamp-vti
index 07fa958e8..d06a374fc 100644
--- a/doc/stamp-vti
+++ b/doc/stamp-vti
@@ -1,4 +1,4 @@
-@set UPDATED 23 April 2004
+@set UPDATED 25 April 2004
 @set UPDATED-MONTH April 2004
 @set EDITION 1.8a
 @set VERSION 1.8a
diff --git a/doc/version.texi b/doc/version.texi
index 07fa958e8..d06a374fc 100644
--- a/doc/version.texi
+++ b/doc/version.texi
@@ -1,4 +1,4 @@
-@set UPDATED 23 April 2004
+@set UPDATED 25 April 2004
 @set UPDATED-MONTH April 2004
 @set EDITION 1.8a
 @set VERSION 1.8a