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)
On Monday 27 June 2011, Ralf Wildenhues wrote: * Stefano Lattarini wrote on Mon, Jun 27, 2011 at 03:35:23PM CEST: On Monday 27 June 2011, Ralf Wildenhues wrote: +@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? A nice idea. Suggestions? autoconf.texi uses stuff like: @c If you change this example, adjust tests/semantics.at:AC_CHECK_SIZEOF struct. 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. Sure. Well, do they use some format already? Well, there are only two of them, and both follows this format: @c The test case for the setup described here is @c test/subdircond2.test @c Try to keep it in sync. (which is wrongish BTW, as the testsuite subdirectory is `tests/', not `test/') I'd go with one of these simple formats: @c Keep in sync with subdircond2.test @c The following is covered by subdircond2.test which are short and easy to grep; and I'd document this idiom in tests/README. I can do that by this evening if nobody beats me. Regards, Stefano
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 wrote on Tue, Jun 28, 2011 at 08:24:13AM CEST: On Monday 27 June 2011, Ralf Wildenhues wrote: Sure. Well, do they use some format already? Well, there are only two of them, and both follows this format: @c The test case for the setup described here is @c test/subdircond2.test @c Try to keep it in sync. (which is wrongish BTW, as the testsuite subdirectory is `tests/', not `test/') I'd go with one of these simple formats: @c Keep in sync with subdircond2.test I like this one (with a trailing dot ;-) ;-) @c The following is covered by subdircond2.test which are short and easy to grep; and I'd document this idiom in tests/README. I can do that by this evening if nobody beats me. Thanks, Ralf
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 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.
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 wrote on Mon, Jun 27, 2011 at 03:35:23PM CEST: On Monday 27 June 2011, Ralf Wildenhues wrote: +@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? A nice idea. Suggestions? autoconf.texi uses stuff like: @c If you change this example, adjust tests/semantics.at:AC_CHECK_SIZEOF struct. 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. Sure. Well, do they use some format already? Thanks, Ralf
