* Ralf Wildenhues wrote on Sat, Jan 15, 2011 at 02:49:33PM CET: > * Stefano Lattarini wrote on Sat, Jan 15, 2011 at 02:23:56PM CET: > > On Saturday 15 January 2011, Ralf Wildenhues wrote: > > > Empty lines before @example and after @end example, and before > > > @noindent (the last two should be collapsed to just one). > > > > > Oh, sorry. I just copied and pasted from some pre-existing code, > > which lacks such spacing. > > Indeed. I'll fix them in maint presently.
Pushing as follows. Cheers, Ralf docs: ensure example are separated with empty lines in the input * doc/automake.texi (Extending aclocal, Emacs Lisp, Rebuilding) (API Versioning, Renamed Objects, Multiple Outputs): Add empty lines before `@example' and after `@end example' lines, so info output is rendered correctly, and a following @noindent honored. Report by Stefano Lattarini. diff --git a/doc/automake.texi b/doc/automake.texi index 80a5ce2..73c0e51 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -3456,6 +3456,7 @@ Extending aclocal current implementation, however it requires a stricter style from the macro authors. Hopefully it is easy to revise the existing macros. For instance, + @example # bad style AC_PREREQ(2.57) @@ -3465,8 +3466,10 @@ Extending aclocal AX_BAR ]) @end example + @noindent should be rewritten as + @example AC_DEFUN([AX_FOOBAR], [AC_PREREQ([2.57])dnl @@ -7455,18 +7458,20 @@ Emacs Lisp There are two ways to avoid byte-compiling. Historically, we have recommended the following construct. + @example lisp_LISP = file1.el file2.el ELCFILES = @end example + @noindent @code{ELCFILES} is an internal Automake variable that normally lists all @file{.elc} files that must be byte-compiled. Automake defines @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this variable explicitly prevents byte-compilation. -Since Automake 1.8, we now recommend using @code{lisp_DATA} instead. As -in +Since Automake 1.8, we now recommend using @code{lisp_DATA} instead: + @example lisp_DATA = file1.el file2.el @end example @@ -8925,9 +8930,11 @@ Rebuilding from @file{configure.ac}. For instance, the following statement will cause @file{configure} to be rerun each time @file{version.sh} is changed. + @example AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh']) @end example + @noindent Note the @samp{$(top_srcdir)/} in the file name. Since this variable is to be used in all @file{Makefile}s, its value must be sensible at @@ -8953,12 +8960,14 @@ Rebuilding today. They are mainly used when the version of a package is updated automatically by a script (e.g., in daily builds). Here is what some old-style @file{configure.ac}s may look like: + @example AC_INIT . $srcdir/version.sh AM_INIT_AUTOMAKE([name], $VERSION_NUMBER) @dots{} @end example + @noindent Here, @file{version.sh} is a shell fragment that sets @code{VERSION_NUMBER}. The problem with this example is that @@ -8969,12 +8978,14 @@ Rebuilding straightforward, because shell variables are not allowed in @code{AC_INIT}'s arguments. We recommend that @file{version.sh} be replaced by an M4 file that is included by @file{configure.ac}: + @example m4_include([version.m4]) AC_INIT([name], VERSION_NUMBER) AM_INIT_AUTOMAKE @dots{} @end example + @noindent Here @file{version.m4} could contain something like @samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this @@ -10300,12 +10311,14 @@ API Versioning @example AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better. @end example + @noindent or, in a particular @file{Makefile.am}: @example AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better. @end example + @noindent Automake will print an error message if its version is older than the requested version. @@ -11192,6 +11205,7 @@ Renamed Objects false_SOURCES = generic.c false_CPPFLAGS = -DEXIT_CODE=1 @end example + @noindent Obviously the two programs are built from the same source, but it would be bad if they shared the same object, because @file{generic.o} @@ -11361,6 +11375,7 @@ Multiple Outputs data.h: data.foo data.c foo data.foo @end example + @noindent therefore a parallel @command{make} will have to serialize the builds of @file{data.c} and @file{data.h}, and will detect that the second is