[PATCH] docs: avoid a footnote, some related rewordings and improvements (was: Re: [Automake-commit] [SCM] GNU Automake branch, maint, updated. v1.11-393-gc1040a7)

[Stefano Lattarini]

On Thursday 23 June 2011, Ralf Wildenhues wrote:
> [ from automake-commit ]
> 
> since I didn't review the source patch yet:
> 
> * Stefano Lattarini wrote on Thu, Jun 23, 2011 at 11:03:52AM CEST:
> > --- a/doc/automake.texi
> > +++ b/doc/automake.texi
> > @@ -8293,7 +8293,9 @@ as are all @file{Makefile.am}s and 
> > @file{Makefile.in}s.  Automake also
> >  has a built-in list of commonly used files that are automatically
> >  included if they are found in the current directory (either physically,
> >  or as the target of a @file{Makefile.am} rule).  This list is printed by
> > address@hidden --help}.  Also, files that are read by @command{configure}
> > address@hidden address@hidden that some of these files are actually
> 
> Footnotes are hard to read and distract the flow, esp. in an info file.
>
Sorry, I never use info(1) directly (never bothered to learn it actually);
and footnotes are not so bad in HTML and PDF.

> Please avoid them whenever possible (consider that they cost you 10
> bucks, or that you may only introduce 3 per year or so).  Here, you can
> easily reword things.
>
OK.  What about the attached patch?

> > +distributed only when other certain conditions hold}.  Also, files that
> > +are read by @command{configure}
> >  (i.e.@: the source files corresponding to the files specified in various
> >  Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
> >  automatically distributed.  Files included in @file{Makefile.am}s (using
 
Regards,
  Stefano

From 3031bb2d4c1cc3e7ae44f5f486a654de54232ab6 Mon Sep 17 00:00:00 2001
Message-Id: <address@hidden>
From: Stefano Lattarini <address@hidden>
Date: Thu, 23 Jun 2011 23:31:27 +0200
Subject: [PATCH] docs: avoid a footnote, some related rewordings and 
improvements

* doc/automake.texi (Dist): Reword the part about automatically
distributed files to avoid a footnote.  Since we are at it, extend
a bit, and add an example and a reference to a relevant test case.
---
 ChangeLog         |    7 +++++++
 doc/automake.texi |   16 ++++++++++------
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 14233a8..2e17be5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2011-06-23   Stefano Lattarini  <address@hidden>
 
+       docs: avoid a footnote, some related rewordings and improvements
+       * doc/automake.texi (Dist): Reword the part about automatically
+       distributed files to avoid a footnote.  Since we are at it, extend
+       a bit, and add an example and a reference to a relevant test case.
+
+2011-06-23   Stefano Lattarini  <address@hidden>
+
        docs: minor cosmetic fixes
        * doc/automake.texi: Break few overly long lines, throughout the
        file.
diff --git a/doc/automake.texi b/doc/automake.texi
index bd4b4a7..9a53486 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -8292,16 +8292,20 @@ is run.  The default setting is @option{--best}.
 @cmindex include
 For the most part, the files to distribute are automatically found by
 Automake: all source files are automatically included in a distribution,
-as are all @file{Makefile.am}s and @file{Makefile.in}s.  Automake also
+as are all @file{Makefile.am} and @file{Makefile.in} files.  Automake also
 has a built-in list of commonly used files that are automatically
 included if they are found in the current directory (either physically,
-or as the target of a @file{Makefile.am} rule).  This list is printed by
address@hidden address@hidden that some of these files are actually
-distributed only when other certain conditions hold}.  Also, files that
-are read by @command{configure}
+or as the target of a @file{Makefile.am} rule); this list is printed by
address@hidden --help}.  Note that some files in this list are actually
+distributed only if other certain conditions hold (for example,
address@hidden The following example should be covered by the test case
address@hidden 'autodist-config-headers.test'.
+the @file{config.h.top} and @file{config.h.bot} files are automatically
+distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
+in @file{configure.ac}).  Also, files that are read by @command{configure}
 (i.e.@: the source files corresponding to the files specified in various
 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
-automatically distributed.  Files included in @file{Makefile.am}s (using
+automatically distributed.  Files included in a @file{Makefile.am} (using
 @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
 helper scripts installed with @samp{automake --add-missing} are also
 distributed.
-- 
1.7.2.3