[Top][All Lists]
[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
- Autotest doc update,
Ralf Wildenhues <=