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