autoconf-patches
[Top][All Lists]
Advanced

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

Autotest doc update


From: Ralf Wildenhues
Subject: Autotest doc update
Date: Sat, 19 Jun 2010 06:45:58 +0200
User-agent: Mutt/1.5.20 (2010-04-22)

This is purely nits: it's either "behind the scenes" or "under the
hood", but not "under the scene".  I think.  Then some needed reordering
and @var fixups, and a documentation bug about failed Autotest tests not
being rerun.

OK?

Thanks,
Ralf

    Overhaul the manual, esp. the Autotest chapter.
    
    * doc/autoconf.texi (Installation Directory Variables):
    Replace some uses of @var with @code.
    (Special Shell Variables): Fix misordered paragraph about IFS.
    (Writing Testsuites): Include paragraph following AT_TESTED in
    the macro definition.
    (testsuite Invocation): Failed tests are not rerun.
    (testsuite Scripts, Autotest Logs, testsuite Invocation)
    (Making testsuite Scripts): Minor edits for consistency and
    language.

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index eba61f4..8d2e952 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -2710,10 +2710,10 @@ Installation Directory Variables
 @defvar exec_prefix
 @ovindex exec_prefix
 The installation prefix for architecture-dependent files.  By default
-it's the same as @var{prefix}.  You should avoid installing anything
-directly to @var{exec_prefix}.  However, the default value for
+it's the same as @code{prefix}.  You should avoid installing anything
+directly to @code{exec_prefix}.  However, the default value for
 directories containing architecture-dependent files should be relative
-to @var{exec_prefix}.
+to @code{exec_prefix}.
 @end defvar
 
 @defvar htmldir
@@ -2770,8 +2770,8 @@ Installation Directory Variables
 
 @defvar prefix
 @ovindex prefix
-The common installation prefix for all files.  If @var{exec_prefix}
-is defined to a different value, @var{prefix} is used only for
+The common installation prefix for all files.  If @code{exec_prefix}
+is defined to a different value, @code{prefix} is used only for
 architecture-independent files.
 @end defvar
 
@@ -15804,6 +15804,22 @@ Special Shell Variables
 the value of @env{IFS} in order to split on another character, but
 remember to restore it before expanding further macros.
 
+Unsetting @code{IFS} instead of resetting it to the default sequence
+is not suggested, since code that tries to save and restore the
+variable's value will incorrectly reset it to an empty value, thus
+disabling field splitting:
+
address@hidden
+unset IFS
+# default separators used for field splitting
+
+save_IFS=$IFS
+IFS=:
+# ...
+IFS=$save_IFS
+# no field splitting performed
address@hidden example
+
 @item LANG
 @itemx LC_ALL
 @itemx LC_COLLATE
@@ -15827,22 +15843,6 @@ Special Shell Variables
 @file{configure} scripts and M4sh do that for you.
 Export these variables after setting them.
 
-Unsetting @code{IFS} instead of resetting it to the default sequence
-is not suggested, since code that tries to save and restore the
-variable's value will incorrectly reset it to an empty value, thus
-disabling field splitting:
-
address@hidden
-unset IFS
-# default separators used for field splitting
-
-save_IFS=$IFS
-IFS=:
-# ...
-IFS=$save_IFS
-# no field splitting performed
address@hidden example
-
 @c  However, some older, nonstandard
 @c  systems (notably SCO) break if locale environment variables
 @c  are set to @samp{C}, so when running on these systems
@@ -23216,7 +23216,7 @@ testsuite Scripts
 
 Generating testing or validation suites using Autotest is rather easy.
 The whole validation suite is held in a file to be processed through
address@hidden, itself using GNU M4 under the scene, to
address@hidden, itself using GNU M4 under the hood, to
 produce a stand-alone Bourne shell script which then gets distributed.
 Neither @command{autom4te} nor GNU M4 are needed at
 the installer's end.
@@ -23310,7 +23310,7 @@ testsuite Scripts
 @end example
 
 @noindent
-Files created during the test suite execution:
+Files created during test suite execution:
 
 @example
 atconfig -->.                    .--> testsuite.log
@@ -23331,7 +23331,6 @@ Autotest Logs
 
 @table @asis
 @item command line arguments
address@hidden akim s/to consist in/to consist of/
 A bad but unfortunately widespread habit consists of
 setting environment variables before the command, such as in
 @samp{CC=my-home-grown-cc ./testsuite}.  The test suite does not
@@ -23357,7 +23356,7 @@ Autotest Logs
 run both the test suite and the programs on @var{host}, but then, from
 the point of view of the test suite, there remains a single environment,
 @var{host} = @var{build}.  The log contains relevant information on the
-state of the build machine, including some important environment
+state of the @var{build} machine, including some important environment
 variables.
 @c FIXME: How about having an M4sh macro to say `hey, log the value
 @c of address@hidden'?  This would help both Autoconf and Autotest.
@@ -23496,7 +23495,6 @@ Writing Testsuites
 space-separated list @var{executables}.  Several invocations register
 new executables, in other words, don't fear registering one program
 several times.
address@hidden defmac
 
 Autotest test suites rely on @env{PATH} to find the tested program.
 This avoids the need to generate absolute names of the various tools, and
@@ -23505,6 +23503,7 @@ Writing Testsuites
 the test suite itself, or its occasional misuses.  It is a good idea to
 also subscribe foreign programs you depend upon, to avoid incompatible
 diagnostics.
address@hidden defmac
 
 @sp 1
 
@@ -23536,7 +23535,7 @@ Writing Testsuites
 For instance, if some of your test groups exercise some @samp{foo}
 feature, then using @samp{AT_KEYWORDS(foo)} lets you run
 @samp{./testsuite -k foo} to run exclusively these test groups.  The
address@hidden of the test group is automatically recorded to
address@hidden of the test group is automatically recorded to
 @code{AT_KEYWORDS}.
 
 Several invocations within a test group accumulate new keywords.  In
@@ -23645,7 +23644,7 @@ Writing Testsuites
 literals in the following table, then the test treats the output
 according to the rules of that literal.  Otherwise, the value of the
 parameter is treated as text that must exactly match the output given by
address@hidden on standard out and standard error (including an empty
address@hidden on standard output and standard error (including an empty
 parameter for no output); any differences are captured in the testsuite
 log and the test is failed (unless an unexpected exit status of 77
 skipped the test instead).  The difference between @code{AT_CHECK} and
@@ -23808,10 +23807,9 @@ testsuite Invocation
 
 @sp 1
 
-By default all tests are performed (or described with
address@hidden) in the default environment first silently, then
-verbosely, but the environment, set of tests, and verbosity level can be
-tuned:
+By default all tests are performed (or described with @option{--list})
+silently in the default environment, but the environment, set of tests,
+and verbosity level can be tuned:
 
 @table @samp
 @item @address@hidden
@@ -23868,7 +23866,7 @@ testsuite Invocation
 
 @item --errexit
 @itemx -e
-If any test fails, immediately abort testing.  It implies
+If any test fails, immediately abort testing.  This implies
 @option{--debug}: post test group clean up, and top-level logging
 are inhibited.  This option is meant for the full test
 suite, it is not really useful for generated debugging scripts.
@@ -23890,11 +23888,11 @@ testsuite Invocation
 
 @item --debug
 @itemx -d
-Do not remove the files after a test group was performed ---but they are
+Do not remove the files after a test group was performed---but they are
 still removed @emph{before}, therefore using this option is sane when
 running several test groups.  Create debugging scripts.  Do not
 overwrite the top-level
-log (in order to preserve supposedly existing full log file).  This is
+log (in order to preserve a supposedly existing full log file).  This is
 the default for debugging scripts, but it can also be useful to debug
 the testsuite itself.
 
@@ -24045,7 +24043,7 @@ Making testsuite Scripts
 @noindent
 and manage to have @code{$(EXTRA_DIST)} distributed.  You will also want
 to distribute the file @file{build-aux/@/missing} from the Automake
-project; a copy of this file resides in the Autoconf source.
+project; a copy of this file resides in the Autoconf source tree.
 
 With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS}
 within your makefile, you can fine-tune test suite execution with this



reply via email to

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