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

[Ralf Wildenhues]

* Stefano Lattarini wrote on Thu, Jun 23, 2011 at 11:33:41PM CEST:
> On Thursday 23 June 2011, Ralf Wildenhues wrote:
> > 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);

Actually, I had been reluctant to use it for a long time, basically
until I learned --index and C-s (interactive search), which is a lot
slower in PDF and less trivial to do with HTML.

> and footnotes are not so bad in HTML and PDF.

True.

> > 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?

Cool, thanks!

Cheers,
Ralf

> 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.

> --- 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'.

@c The following example is covered by autodist-config-headers.test.

?

Maybe even some kind of formatted comment, to allow some checking in the
future?

> +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.