From: Paul Eggert Date: Wed, 3 May 2006 00:36:32 +0000 (+0000) Subject: * doc/autoconf.texi: Use @option systematically. X-Git-Tag: AUTOCONF-2.59d~91 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=04e292eda5f261dc7bb5c85f7f2277fb8249e5e0;p=thirdparty%2Fautoconf.git * doc/autoconf.texi: Use @option systematically. --- diff --git a/ChangeLog b/ChangeLog index a840b4a7b..051ac1ccf 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2006-05-02 Paul Eggert + + * doc/autoconf.texi: Use @option systematically. + 2006-05-02 Paul Eggert and Bruno Haible diff --git a/doc/autoconf.texi b/doc/autoconf.texi index bf7dcb848..5795813b9 100644 --- a/doc/autoconf.texi +++ b/doc/autoconf.texi @@ -1393,8 +1393,8 @@ disable warnings falling into @var{category} Warnings about @samp{syntax} are enabled by default, and the environment variable @env{WARNINGS}, a comma separated list of categories, is -honored as well. Passing @samp{-W @var{category}} will actually behave as if -you had passed @samp{--warnings=syntax,$WARNINGS,@var{category}}. If +honored as well. Passing @option{-W @var{category}} will actually behave as if +you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}. If you want to disable the defaults and @env{WARNINGS}, but (for example) enable the warnings about obsolete constructs, you would use @option{-W none,obsolete}. @@ -1623,8 +1623,8 @@ disable warnings falling into @var{category} Warnings about @samp{syntax} are enabled by default, and the environment variable @env{WARNINGS}, a comma separated list of categories, is -honored as well. Passing @samp{-W @var{category}} will actually behave as if -you had passed @samp{--warnings=syntax,$WARNINGS,@var{category}}. If +honored as well. Passing @option{-W @var{category}} will actually behave as if +you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}. If you want to disable the defaults and @env{WARNINGS}, but (for example) enable the warnings about obsolete constructs, you would use @option{-W none,obsolete}. @@ -2520,7 +2520,7 @@ 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"], [Data directory.])}, you should add -@samp{-DDATADIR="$(datadir)"} to your @code{CPPFLAGS}. +@option{-DDATADIR="$(datadir)"} to your @code{CPPFLAGS}. Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace @code{datadir} and friends in your shell scripts and other files, rather @@ -5983,9 +5983,9 @@ Normally Autoconf ignores warnings generated by the compiler, linker, and preprocessor. If this macro is used, warnings will be treated as fatal errors instead for the current language. This macro is useful when the results of configuration will be used where warnings are unacceptable; for -instance, if parts of a program are built with the GCC @samp{-Werror} -option. If the whole program will be built using @samp{-Werror} it is -often simpler to put @samp{-Werror} in the compiler flags (@code{CFLAGS}, +instance, if parts of a program are built with the GCC @option{-Werror} +option. If the whole program will be built using @option{-Werror} it is +often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS}, etc.). @end defmac @@ -8768,7 +8768,7 @@ default, the parenthesis around arguments, etc.). These primitives are really meant to make M4 more useful for specific domains: they should be considered like command line options: @option{--quotes}, @option{--comments}, @option{--words}, and -@code{--syntax}. Nevertheless, they are implemented as M4 builtins, as +@option{--syntax}. Nevertheless, they are implemented as M4 builtins, as it makes M4 libraries self contained (no need for additional options). There lies the problem@enddots{} @@ -9796,7 +9796,7 @@ level macros as described below. @asindex{MESSAGE_FD} The file descriptor for @samp{checking for...} messages and results. Normally this directs messages to the standard output, however when -@command{configure} is run with the @code{-q} option, messages sent to +@command{configure} is run with the @option{-q} option, messages sent to @code{AS_MESSAGE_FD} will be discarded. If you want to display some messages, consider using one of the printing @@ -12161,7 +12161,7 @@ set x $my_list; shift Avoid @samp{set -}, e.g., @samp{set - $my_list}. Posix no longer requires support for this command, and in traditional shells -@samp{set - $my_list} resets the @samp{-v} and @samp{-x} options, which +@samp{set - $my_list} resets the @option{-v} and @option{-x} options, which makes scripts harder to debug. Some nonstandard shells do not recognize more than one option @@ -12600,10 +12600,10 @@ compiler name. @c ------------------ @prindex @command{chmod} Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file} -instead, for two reasons. First, plain @samp{-w} does not necessarily +instead, for two reasons. First, plain @option{-w} does not necessarily make the file unwritable, since it does not affect mode bits that correspond to bits in the file mode creation mask. Second, -Posix says that the @samp{-w} might be interpreted as an +Posix says that the @option{-w} might be interpreted as an implementation-specific option, not as a mode; Posix suggests using @samp{chmod -- -w file} to avoid this confusion, but unfortunately @samp{--} does not work on some older hosts. @@ -12927,12 +12927,12 @@ status of @code{grep} to determine whether it found a match. Some traditional @command{grep} implementations do not work on long input lines. Also, many implementations do not support multiple regexps -with @option{-e}: they either reject @samp{-e} entirely (e.g., Solaris) +with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris) or honor only the last pattern (e.g., @acronym{IRIX} 6.5). To work around these problems, invoke @code{AC_PROG_GREP} and then use @code{$GREP}. -Another possible workaround for the multiple @samp{-e} problem is to +Another possible workaround for the multiple @option{-e} problem is to separate the patterns by newlines, for example: @example @@ -12945,7 +12945,7 @@ except that this will fail with traditional @command{grep} implementations and with Open@acronym{BSD} 3.8 @command{grep}. Traditional @command{grep} implementations (e.g., Solaris) do not -support the @option{-E} or @samp{-F} options. To work around these +support the @option{-E} or @option{-F} options. To work around these problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and similarly for @code{AC_PROG_FGREP} and @code{$FGREP}. @@ -13146,7 +13146,7 @@ rm -f foo In older versions of Mac OS X, @command{od} does not support the standard Posix options @option{-A}, @option{-j}, @option{-N}, or @option{-t}, or the @acronym{XSI} option @option{-s}. The only -supported Posix option is @code{-v}, and the only supported +supported Posix option is @option{-v}, and the only supported @acronym{XSI} options are those in @option{-bcdox}. The BSD @command{hexdump} program can be used instead. @@ -13522,7 +13522,7 @@ foo @end example You have a few possibilities if you do want the @code{foo=bar} override -to propagate to sub-@command{make}s. One is to use the @code{-e} +to propagate to sub-@command{make}s. One is to use the @option{-e} option, which causes all environment variables to have precedence over the @file{Makefile} macro definitions, and declare foo as an environment variable: @@ -13531,7 +13531,7 @@ variable: % @kbd{env foo=bar make -e} @end example -The @code{-e} option is propagated to sub-@command{make}s automatically, +The @option{-e} option is propagated to sub-@command{make}s automatically, and since the environment is inherited between @command{make} invocations, the @code{foo} macro will be overridden in sub-@code{make}s as expected. @@ -13540,9 +13540,9 @@ This syntax (@code{foo=bar make -e}) is portable only when used outside of a @file{Makefile}, for instance from a script or from the command line. When run inside a @command{make} rule, @acronym{GNU} @command{make} 3.80 and prior versions forget to propagate the -@code{-e} option to sub-@command{make}s. +@option{-e} option to sub-@command{make}s. -Moreover, using @code{-e} could have unexpected side-effects if your +Moreover, using @option{-e} could have unexpected side-effects if your environment contains some other macros usually defined by the Makefile. (See also the note about @code{make -e} and @code{SHELL} below.) @@ -14442,8 +14442,8 @@ produce code (rarely needed). By default, it is the same as host. If you mean to override the result of @command{config.guess}, use @option{--build}, not @option{--host}, since the latter enables cross-compilation. For historical reasons, passing @option{--host} also -changes the build type. Therefore, whenever you specify @code{--host}, -be sure to specify @code{--build} too; this will be fixed in the +changes the build type. Therefore, whenever you specify @option{--host}, +be sure to specify @option{--build} too; this will be fixed in the future. So, to enter cross-compilation mode, use a command like this @example @@ -16835,7 +16835,7 @@ mode, so it won't run any tests that require execution. Hint: if you mean to override the result of @command{config.guess}, prefer @option{--build} over @option{--host}. In the future, @option{--host} will not override the name of the build system type. -Whenever you specify @code{--host}, be sure to specify @code{--build} +Whenever you specify @option{--host}, be sure to specify @option{--build} too. @sp 1 @@ -16891,8 +16891,8 @@ an executable produced by the compiler. If the execution fails, it will enter cross-compilation mode. This is fragile. Moreover, by the time the compiler test is performed, it may be too late to modify the build-system type: other tests may have already been performed. -Therefore, whenever you specify @code{--host}, be sure to specify -@code{--build} too. +Therefore, whenever you specify @option{--host}, be sure to specify +@option{--build} too. @example ./configure --build=i686-pc-linux-gnu --host=m68k-coff