autoconf-patches
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: documentation bug (?)


From: Paul Eggert
Subject: Re: documentation bug (?)
Date: Fri, 03 Sep 2004 21:53:33 -0700
User-agent: Gnus/5.1006 (Gnus v5.10.6) Emacs/21.3 (gnu/linux)

Frederik Fouvry <address@hidden> writes:

> That works indeed, but the documentation gives at least three
> times the "wrong" use (see quotation for two examples).

Thanks for mentioning this.  I installed the following patch.

2004-09-03  Paul Eggert  <address@hidden>

        * doc/autoconf.texi: Give AC_DEFINE and AC_DEFINE_UNQUOTED
        three args in examples.  Problem reported by Frederik Fouvry in:
        http://lists.gnu.org/archive/html/bug-autoconf/2004-09/msg00017.html
        Also, fix some minor spacing and punctuation bugs.

Index: autoconf.texi
===================================================================
RCS file: /cvsroot/autoconf/autoconf/doc/autoconf.texi,v
retrieving revision 1.831
retrieving revision 1.832
diff -p -u -r1.831 -r1.832
--- autoconf.texi       2 Sep 2004 07:30:26 -0000       1.831
+++ autoconf.texi       4 Sep 2004 04:51:58 -0000       1.832
@@ -981,7 +981,8 @@ For instance:
 
 @example
 AC_CHECK_HEADER([stdio.h],
-                [AC_DEFINE([HAVE_STDIO_H])],
+                [AC_DEFINE([HAVE_STDIO_H], [1],
+                   [Define to 1 if you have <stdio.h>.])],
                 [AC_MSG_ERROR([Sorry, can't do anything for you])])
 @end example
 
@@ -990,7 +991,8 @@ is quoted properly.  You may safely simp
 
 @example
 AC_CHECK_HEADER(stdio.h,
-                [AC_DEFINE(HAVE_STDIO_H)],
+                [AC_DEFINE(HAVE_STDIO_H, 1,
+                   Define to 1 if you have <stdio.h>.)],
                 [AC_MSG_ERROR([Sorry, can't do anything for you])])
 @end example
 
@@ -1002,7 +1004,8 @@ The following example is wrong and dange
 
 @example
 AC_CHECK_HEADER(stdio.h,
-                AC_DEFINE(HAVE_STDIO_H),
+                AC_DEFINE(HAVE_STDIO_H, 1,
+                   Define to 1 if you have <stdio.h>.),
                 AC_MSG_ERROR([Sorry, can't do anything for you]))
 @end example
 
@@ -2347,7 +2350,8 @@ current value of @code{prefix}.
 A corollary is that you should not use these variables except in
 Makefiles.  For instance, instead of trying to evaluate @code{datadir}
 in @file{configure} and hard-coding it in Makefiles using
-e.g., @samp{AC_DEFINE_UNQUOTED(DATADIR, "$datadir")}, you should add
+e.g., @samp{AC_DEFINE_UNQUOTED(DATADIR, "$datadir", [Data directory.])},
+you should add
 @samp{-DDATADIR="$(datadir)"} to your @code{CPPFLAGS}.
 
 Similarly you should not rely on @code{AC_OUTPUT_FILES} to replace
@@ -2840,7 +2844,7 @@ Specify additional shell commands to run
 from @command{configure}.  Associate the commands with @var{tag}.
 Since typically the @var{cmds} create a file, @var{tag} should
 naturally be the name of that file.  If needed, the directory hosting
address@hidden is created. This macro is one of the instantiating macros;
address@hidden is created.  This macro is one of the instantiating macros;
 see @ref{Configuration Actions}.
 
 Here is an unrealistic example:
@@ -3644,7 +3648,7 @@ tradition of it returning @code{int}.
 @c @fuindex free
 @prindex @code{free}
 The ISO C99 standard says a call @code{free(NULL)} does nothing, but
-some old systems don't support this (eg.@: NextStep).
+some old systems don't support this (e.g., NextStep).
 
 @item @code{isinf}
 @itemx @code{isnan}
@@ -3702,20 +3706,20 @@ probably not worth worrying about.
 @c @fuindex malloc
 @prindex @code{malloc}
 The ISO C99 standard says a call @code{malloc(0)} is implementation
-dependent, it may either return @code{NULL} (eg.@: OSF 4) or
address@hidden (eg.@: @acronym{GNU} C Library).  @code{AC_FUNC_MALLOC}
+dependent, it may either return @code{NULL} (e.g., OSF 4) or
address@hidden (e.g., @acronym{GNU} C Library).  @code{AC_FUNC_MALLOC}
 can be used to insist on address@hidden (@pxref{Particular Functions}).
 
 @item @code{putenv}
 @c @fuindex putenv
 @prindex @code{putenv}
 POSIX specifies that @code{putenv} puts the given string directly in
address@hidden, but some systems make a copy of it instead (eg.@:
address@hidden, but some systems make a copy of it instead (e.g.,
 glibc 2.0, or BSD).  And when a copy is made, @code{unsetenv} might
-not free it, causing a memory leak (eg.@: FreeBSD 4).
+not free it, causing a memory leak (e.g., FreeBSD 4).
 
 POSIX specifies that @code{putenv("FOO")} removes @samp{FOO} from the
-environment, but on some systems (eg.@: FreeBSD 4) this is not the
+environment, but on some systems (e.g., FreeBSD 4) this is not the
 case and instead @code{unsetenv} must be used.
 
 On MINGW, a call @code{putenv("FOO=")} removes @samp{FOO} from the
@@ -3725,7 +3729,7 @@ environment, rather than inserting it wi
 @c @fuindex realloc
 @prindex @code{realloc}
 The ISO C99 standard says a call @code{realloc(NULL,size)} is equivalent
-to a @code{malloc(size)}, but some old systems don't support this (eg.@:
+to a @code{malloc(size)}, but some old systems don't support this (e.g.,
 NextStep).
 
 @item @code{signal} handler
@@ -3780,7 +3784,7 @@ having format strings read-only can be a
 @c @fuindex strerror_r
 @prindex @code{strerror_r}
 POSIX specifies that @code{strerror_r} returns an @code{int}, but many
-systems (eg.@: @acronym{GNU} C Library version 2.2.4) provide a
+systems (e.g., @acronym{GNU} C Library version 2.2.4) provide a
 different version returning a @code{char *}.  @code{AC_FUNC_STRERROR_R}
 can detect which is in use (@pxref{Particular Functions}).
 
@@ -3806,7 +3810,7 @@ strnlen ("foobar", 9) = 6
 @item @code{sysconf}
 @c @fuindex sysconf
 @prindex @code{sysconf}
address@hidden is standard, but some older systems (eg.@: HP-UX
address@hidden is standard, but some older systems (e.g., HP-UX
 9) have @code{_SC_PAGE_SIZE} instead.  This can be tested with
 @code{#ifdef}.
 
@@ -4021,7 +4025,7 @@ yourself in new code:
 @prindex @code{fseeko}
 If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
 Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype
-visible on some systems (e.g. glibc 2.2). Otherwise linkage problems
+visible on some systems (e.g., glibc 2.2).  Otherwise linkage problems
 may occur when compiling with @code{AC_SYS_LARGEFILE} on
 largefile-sensitive systems where @code{off_t} does not default to a
 64bit entity.
@@ -5470,7 +5474,7 @@ They tickle a bug in the HP-UX C compile
 @example
 #ifdef __STDC__
 /\
-* A comment with backslash-newlines in it. address@hidden address@hidden *\
+* A comment with backslash-newlines in it.  address@hidden address@hidden *\
 \
 /
 char str[] = "\\
@@ -5885,9 +5889,9 @@ found.
 
 By default, newer dialects are preferred over older dialects, but if
 @code{dialect} is specified then older dialects are preferred starting
-with the specified dialect. @code{dialect} can currently be one of
+with the specified dialect.  @code{dialect} can currently be one of
 Fortran 77, Fortran 90, or Fortran 95.  However, this is only a hint of
-which compiler @emph{name} to prefer (e.g. @code{f90} or @code{f95}),
+which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}),
 and no attempt is made to guarantee that a particular language standard
 is actually supported.  Thus, it is preferable that you avoid the
 @code{dialect} option, and use AC_PROG_FC only for code compatible with
@@ -6114,14 +6118,14 @@ to call Fortran routines from some langu
 @acindex{FC_SRCEXT}
 By default, the @code{FC} macros perform their tests using a @file{.f}
 extension for source-code files.  Some compilers, however, only enable
-newer language features for appropriately named files, e.g. Fortran 90
+newer language features for appropriately named files, e.g., Fortran 90
 features only for @file{.f90} files.  On the other hand, some other
 compilers expect all source files to end in @file{.f} and require
 special flags to support other file name extensions.  The
 @code{AC_FC_SRCEXT} macro deals with both of these issues.
 
 The @code{AC_FC_SRCEXT} tries to get the @code{FC} compiler to accept files
-ending with the extension address@hidden (i.e. @var{ext} does @emph{not}
+ending with the extension address@hidden (i.e., @var{ext} does @emph{not}
 contain the dot).  If any special compiler flags are needed for this, it
 stores them in the output variable @address@hidden  This
 extension and these flags are then used for all subsequent @code{FC} tests
@@ -6170,7 +6174,7 @@ specify a different extension with @code
 succeed without modifying @code{FCFLAGS}.
 
 If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
-calls @ovar{action-if-success} (defaults to nothing). If it fails, it
+calls @ovar{action-if-success} (defaults to nothing).  If it fails, it
 calls @ovar{action-if-failure} (defaults to exiting with an error
 message).
 @end defmac
@@ -6257,7 +6261,7 @@ an arbitrary @code{off_t} value @code{X}
 
 The LFS introduced the @code{fseeko} and @code{ftello} functions to
 replace their C counterparts @code{fseek} and @code{ftell} that do not
-use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their
+use @code{off_t}.  Take care to use @code{AC_FUNC_FSEEKO} to make their
 prototypes available when using them and large-file support is
 enabled.
 @end defmac
@@ -6593,7 +6597,8 @@ For instance executing (observe the doub
 
 @example
 AC_INIT(Autoconf Documentation, @value{VERSION}, bug-autoconf@@gnu.org)
-AC_DEFINE([HELLO_WORLD], ["Hello, World\n"])
+AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
+  [Greetings string.])
 AC_LANG_CONFTEST(
    [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
 gcc -E -dD -o - conftest.c
@@ -6631,7 +6636,8 @@ For instance:
 
 @example
 AC_INIT(Autoconf Documentation, @value{VERSION}, bug-autoconf@@gnu.org)
-AC_DEFINE([HELLO_WORLD], ["Hello, World\n"])
+AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
+  [Greetings string.])
 AC_LANG_CONFTEST(
 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
                  [[fputs (hw, stdout);]])])
@@ -6723,7 +6729,8 @@ For instance:
 
 @example
 AC_INIT(Autoconf Documentation, @value{VERSION}, bug-autoconf@@gnu.org)
-AC_DEFINE([HELLO_WORLD], ["Hello, World\n"])
+AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
+  [Greetings string.])
 AC_PREPROC_IFELSE(
    [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
                     [[fputs (hw, stdout);]])],
@@ -6979,16 +6986,22 @@ fstype=no
 # The order of these tests is important.
 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h>
 #include <sys/fstyp.h>]])],
-                  [AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4])
+                  [AC_DEFINE(FSTYPE_STATVFS, 1,
+                     [Define if statvfs exists.])
+                   fstype=SVR4])
 if test $fstype = no; then
   AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
 #include <sys/fstyp.h>]])],
-                  [AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3])
+                  [AC_DEFINE(FSTYPE_USG_STATFS, 1,
+                     [Define if USG statfs.])
+                   fstype=SVR3])
 fi
 if test $fstype = no; then
   AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
 #include <sys/vmount.h>]])]),
-                  [AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX])
+                  [AC_DEFINE(FSTYPE_AIX_STATFS, 1,
+                     [Define if AIX statfs.])
+                   fstype=AIX])
 fi
 # (more cases omitted here)
 AC_MSG_RESULT([$fstype])
@@ -7029,9 +7042,11 @@ already defined a certain C preprocessor
 appropriate cache variable, as in this example:
 
 @example
-AC_CHECK_FUNC(vprintf, [AC_DEFINE(HAVE_VPRINTF)])
+AC_CHECK_FUNC(vprintf, [AC_DEFINE(HAVE_VPRINTF, 1,
+                          [Define if vprintf exists.])])
 if test "$ac_cv_func_vprintf" != yes; then
-  AC_CHECK_FUNC(_doprnt, [AC_DEFINE(HAVE_DOPRNT)])
+  AC_CHECK_FUNC(_doprnt, [AC_DEFINE(HAVE_DOPRNT, 1,
+                            [Define if _doprnt exists.])])
 fi
 @end example
 
@@ -7057,7 +7072,8 @@ The following example defines the C prep
 @code{EQUATION} to be the string constant @samp{"$a > $b"}:
 
 @example
-AC_DEFINE(EQUATION, "$a > $b")
+AC_DEFINE(EQUATION, "$a > $b",
+  [Equation string.])
 @end example
 
 If neither @var{value} nor @var{description} are given, then
@@ -7077,9 +7093,12 @@ special meaning.  Use this macro instead
 @var{variable} or @var{value} is a shell variable.  Examples:
 
 @example
-AC_DEFINE_UNQUOTED(config_machfile, "$machfile")
-AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups)
-AC_DEFINE_UNQUOTED($ac_tr_hdr)
+AC_DEFINE_UNQUOTED(config_machfile, "$machfile",
+  [Configuration machine file.])
+AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups,
+  [getgroups return type.])
+AC_DEFINE_UNQUOTED($ac_tr_hdr, 1,
+  [Translated header name.])
 @end example
 @end defmac
 
@@ -7090,7 +7109,8 @@ in the resulting @command{configure} scr
 newlines.  That is, do this:
 
 @example
-AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4) LIBS="$LIBS -lelf"])
+AC_CHECK_HEADER(elf.h,
+  [AC_DEFINE(SVR4, 1, [System V Release 4]) LIBS="$LIBS -lelf"])
 @end example
 
 @noindent
@@ -7098,15 +7118,16 @@ or this:
 
 @example
 AC_CHECK_HEADER(elf.h,
- [AC_DEFINE(SVR4)
-  LIBS="$LIBS -lelf"])
+  [AC_DEFINE(SVR4, 1, [System V Release 4])
+   LIBS="$LIBS -lelf"])
 @end example
 
 @noindent
 instead of this:
 
 @example
-AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4); LIBS="$LIBS -lelf"])
+AC_CHECK_HEADER(elf.h,
+  [AC_DEFINE(SVR4, 1, [System V Release 4]); LIBS="$LIBS -lelf"])
 @end example
 
 @node Setting Output Variables
@@ -8667,7 +8688,7 @@ according to the Webster's Revised Unabr
 
 @quotation
 Mash \Mash\, n.  [Akin to G. meisch, maisch, meische, maische, mash,
-wash, and prob.@: to AS.@: miscian to mix.  See ``Mix''.]
+wash, and prob.@: to AS. miscian to mix.  See ``Mix''.]
 
 @enumerate 1
 @item
@@ -10746,9 +10767,9 @@ fi
 @c ------------------
 @prindex @command{printf}
 A format string starting with a @samp{-} can cause problems.
-Bash (eg. 2.05b) will interpret it as an options string and
+Bash (e.g., 2.05b) will interpret it as an options string and
 give an error.  And @samp{--} to mark the end of options is not good
-in the NetBSD Almquist shell (eg. 0.4.6) which will take that
+in the NetBSD Almquist shell (e.g., 0.4.6) which will take that
 literally as the format string.  Putting the @samp{-} in a @samp{%c}
 or @samp{%s} is probably the easiest way to avoid doubt,
 




reply via email to

[Prev in Thread] Current Thread [Next in Thread]