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
> > -@samp{automake --help}@footnote{Note 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
> > +@samp{automake --help}. Note that some files in this list are actually
> > +distributed only if other certain conditions hold (for example,
> > +@c The following example should be covered by the test case
> > +@c '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
