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)

[Stefano Lattarini]

On Monday 27 June 2011, Ralf Wildenhues wrote:
> * 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.
> 
> ?
>
Of course this is better.  I really don't understand why I often end up
using 10 words to say what can be said more clearly in 5.  Sigh.

> Maybe even some kind of formatted comment, to allow some checking in the
> future?
>
A nice idea.  Suggestions?  Oh, and I'd keep this for a follow-up, bacause
there are already similar testcase-referring comments in the manual, which
will have to be adjusted.

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

Patch pushed now.

Regards,
  Stefano