* doc/dejagnu.texi: More overhauling.

2 files changed, 455 insertions, 528 deletions

diff --git a/ChangeLog b/ChangeLog
index 6a4a55f..22454d6 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2016-04-03  Ben Elliston  <bje@gnu.org>
 
+	* doc/dejagnu.texi: More overhauling.
+
+2016-04-03  Ben Elliston  <bje@gnu.org>
+
 	* runtest.exp: Document the magical handling of -D[01].
 
 2016-04-03  Ben Elliston  <bje@gnu.org>
diff --git a/doc/dejagnu.texi b/doc/dejagnu.texi
index 68a2f8d..6db0e6c 100644
--- a/doc/dejagnu.texi
+++ b/doc/dejagnu.texi
@@ -351,31 +351,26 @@ correctly.
 @section Running 'make check'
 
 To run tests from an existing collection, first use @code{configure} as
-usual to set up the build directory. Then type:
-
-@example
-
-      make check
-      
-@end example
-
-If the @emph{check} target exists, it usually saves you some
-trouble. For instance, it can set up any auxiliary programs or other
-files needed by the tests. The most common file the @emph{check} target
-depends on is the @file{site.exp} file. The site.exp file contains
-various variables that DejaGnu used to determine the configuration of
-the program being tested. This is mostly for supporting remote testing.
-
-The @emph{check} target is supported by GNU Automake. To have DejaGnu
-support added to your generated @file{Makefile.in}, just add the keyword
-@code{dejagnu} to the AUTOMAKE_OPTIONS variable in your
-@file{Makefile.am} file.
+usual to set up the build directory. Then type @code{make check}.  If
+the @emph{check} target exists, it usually saves you some trouble. For
+instance, it can set up any auxiliary programs or other files needed by
+the tests. The most common file the @emph{check} target depends on is
+the @file{site.exp} file. The @file{site.exp} contains various variables
+that DejaGnu uses to determine the configuration of the program being
+tested.
 
 Once you have run @emph{make check} to build any auxiliary files, you
 can invoke the test driver @code{runtest} directly to repeat the tests.
 You will also have to execute @code{runtest} directly for test
 collections with no @emph{check} target in the @file{Makefile}.
 
+GNU Automake has built-in support for DejaGnu.  To add DejaGnu support
+to your generated @file{Makefile.in}, just add the keyword
+@code{dejagnu} to the AUTOMAKE_OPTIONS variable in
+@file{Makefile.am}. This will ensure that the generated
+@file{Makefile.in} has a @code{check} target that invokes DejaGnu
+correctly.
+
 @node Runtest, Output Files, Make Check, Running tests
 @section Running runtest
 
@@ -384,9 +379,16 @@ of things on the @code{runtest} command line: command line options, and
 Tcl variables that are passed to the test scripts. The options are
 listed alphabetically below.
 
-@code{runtest} returns an exit code of @emph{1} if any test has an
-unexpected result. If all tests pass or fail as expected, @code{runtest}
-returns @emph{0} as the exit code.
+@code{runtest} returns one of the following exit codes:
+
+@table @asis
+@item 0
+if all tests passed including expected failures and unsupported tests.
+@item 1
+if any test failed, passed unexpectedly, or was unresolved.
+@item 2
+if Expect encountered any error in the test scripts.
+@end table
 
 @menu
 * Output States::
@@ -481,13 +483,37 @@ itself). Specify @code{--all} to see output for tests with status
 or @emph{WARNING} (minor error in the test case itself).
 
 @item @code{--build [triplet]}
-@emph{string} is a configuration triplet as used by
-@code{configure}. This is the type of machine DejaGnu and the tools to
-be tested are built on. For a normal cross this is the same as the host,
-but for a Canadian cross, they are separate.
+@emph{triplet} is a system triplet of the form
+@emph{cpu-vendor-os}. This is the type of machine DejaGnu and the tools
+to be tested are built on. For a normal cross environment this is the
+same as the host, but for a Canadian cross, they are different.
+
+@item @code{-D0}, @code{-D1}
+Start the internal Tcl debugger. The Tcl debugger supports breakpoints,
+single stepping, and other common debugging activities. See the document
+@uref{http://expect.sourceforge.net/doc/tcl-debug.ps, Debugger for Tcl
+Applications} by Don Libes. If you specify @emph{-D1}, the @emph{expect}
+shell stops at a breakpoint as soon as DejaGnu invokes it. If you
+specify @emph{-D0}, DejaGnu starts as usual, but you can enter the
+debugger by sending an interrupt (e.g. by typing @key{Control}@key{c}).
+
+@item @code{--debug}
+Turns on the Expect internal debugging output. Debugging output is
+displayed as part of the @emph{runtest} output, and logged to a file
+called @file{dbg.log}. The extra debugging output does @emph{not} appear
+on standard output, unless the verbose level is greater than 2 (for
+instance, to see debug output immediately, specify @code{--debug -v
+-v}). The debugging output shows all attempts at matching the test
+output of the tool with the scripted patterns describing expected
+output.  The output generated with @code{--strace} also goes into
+@file{dbg.log}.
+
+@item @code{--help}
+Prints out a short summary of the @emph{runtest} options, then exits
+(even if you specify other options).
 
 @item @code{--host [triplet]}
-@code{string} is a configuration triplet as used by @emph{configure}.
+@emph{triplet} is a system triplet of the form @emph{cpu-vendor-os}.
 Use this option to override the default string recorded by your
 configuration's choice of host.  This choice does not change how
 anything is actually configured unless --build is also specified; it
@@ -503,31 +529,17 @@ run on.
 @item @code{--host_board [name]}
 The host board to use.
 
-@item @code{--target [triplet]}
-Use this option to override the default setting (running native
-tests). @emph{triplet} is a configuration triplet of the form
-@emph{cpu-vendor-os} as used by @code{configure}. This option changes
-the configuration @code{runtest} uses for the default tool names, and
-other setup information.
-
-@item @code{--debug}
-Turns on the Expect internal debugging output. Debugging output is
-displayed as part of the @emph{runtest} output, and logged to a file
-called @file{dbg.log}. The extra debugging output does @emph{not} appear
-on standard output, unless the verbose level is greater than 2 (for
-instance, to see debug output immediately, specify @code{--debug -v
--v}). The debugging output shows all attempts at matching the test
-output of the tool with the scripted patterns describing expected
-output.  The output generated with @code{--strace} also goes into
-@file{dbg.log}.
-
-@item @code{--help}
-Prints out a short summary of the @emph{runtest} options, then exits
-(even if you also specify other options).
-
 @item @code{--ignore [name(s)] }
 The name(s) of specific tests to ignore.
 
+@item @code{--log_dialog}
+Emit Expect output to stdout.  The Expect output is usually only written
+to the @file{.log} file. By enabling this option, they are also printed
+to standard output.
+
+@item @code{--mail [address(es)]}
+Send test results to one or more email addresses.
+
 @item @code{--objdir [path]}
 Use @emph{path} as the top directory containing any auxiliary compiled
 test code. The default is '.'.  Use this option to locate pre-compiled
@@ -541,11 +553,6 @@ summary (@file{.sum}) and the detailed log files (@file{.log}).  The
 DejaGnu debug log @file{dbg.log} always appears (when requested) in the
 local directory.
 
-@item @code{--log_dialog}
-Emit Expect output to stdout.  The expect output is usually only written
-to @file{tool.log}. By enabling this option, they are also be printed to
-the stdout of the @emph{runtest} invocation.
-
 @item @code{--reboot [name]}
 Reboot the target board when @code{runtest} starts. When running tests
 on a separate target board, it is safer to reboot the target to be
@@ -561,7 +568,7 @@ subdirectories @file{gdb.*} (with the usual shell-like filename
 expansion).  If you do not use @code{--srcdir}, @emph{runtest} looks for
 test directories under the current working directory.
 
-@item @code{--strace [number]}
+@item @code{--strace [n]}
 Turn on internal tracing for @emph{expect}, to n levels deep. By
 adjusting the level, you can control the extent to which your output
 expands multi-level Tcl statements.  This allows you to ignore some
@@ -569,23 +576,29 @@ levels of @emph{case} or @emph{if} statements.  Each procedure call or
 control structure counts as one ``level''. The output is recorded in the
 same file, @file{dbg.log}, used for output from @code{--debug}.
 
+@item @code{--target [triplet]}
+Use this option to override the default setting (native
+testing). @emph{triplet} is a system triplet of the form
+@emph{cpu-vendor-os}. This option changes the configuration
+@code{runtest} uses for the default tool names, and other setup
+information.
+
 @item @code{--target_board [name(s)]}
-The list of target boards to run tests
-on.
-
-@anchor{--tool [name[s]]}@item @code{--tool [name(s)]} Specifies which
-testsuite to run, and what initialization module to use. @code{--tool}
-is used @emph{only} for these two purposes. It is @emph{not} used to
-name the executable program to test. Executable tool names (and paths)
-are recorded in @file{site.exp} and you can override them by specifying
-Tcl variables on the command line.
-
-For example, including "@code{--tool} gcc" on the @emph{runtest} command
-line runs tests from all test subdirectories whose names match
-@file{gcc.*}, and uses one of the initialization modules named
-@file{config/*-gcc.exp}. To specify the name of the compiler (perhaps as
-an alternative path to what @emph{runtest} would use by default), use
-@emph{GCC=binname} on the @emph{runtest} command line.
+The list of target boards to run tests on.
+
+@item @code{--tool [name(s)]}
+Specifies which testsuite to run, and what initialization module to
+use. @code{--tool} is used @emph{only} for these two purposes. It is
+@emph{not} used to name the executable program to test. Executable tool
+names (and paths) are recorded in @file{site.exp} and you can override
+them by specifying Tcl variables on the command line.
+
+For example, including @code{--tool} gcc on the command line runs tests
+from all test subdirectories whose names match @file{gcc.*}, and uses
+one of the initialization modules named @file{config/*-gcc.exp}. To
+specify the name of the compiler (perhaps as an alternative path to what
+@emph{runtest} would use by default), use @emph{GCC=path-to-gcc} on the
+@emph{runtest} command line.
 
 @item @code{--tool_exec [name]}
 The path to the tool executable to test.
@@ -603,30 +616,24 @@ file, but not in the summary (@file{*.sum}) log file.
 @item @code{-V}, @code{--version}
 Prints out the version numbers of DejaGnu, Expect, and Tcl.
 
-@item @code{--D0}, @code{--D1}
-Start the internal Tcl debugger. The Tcl debugger supports breakpoints,
-single stepping, and other common debugging activities. See the document
-"Debugger for Tcl Applications" by Don Libes. (Distributed in PostScript
-form with @emph{expect} as the file @file{expect/tcl-debug.ps.}. If you
-specify @emph{-D1}, the @emph{expect} shell stops at a breakpoint as
-soon as DejaGnu invokes it. If you specify @emph{-D0}, DejaGnu starts as
-usual, but you can enter the debugger by sending an interrupt (e.g. by
-typing @key{Control}@key{c}).
+@item @code{-x}, @code{--xml=FILE}
+Generate XML output. FILE is optional; if given it is the name of the
+output file.  If not given, the output file is named after the tool.
 
 @item @file{testfile}.exp[=arg(s)]
 Specify the names of testsuites to run. By default, @emph{runtest} runs
 all tests for the tool, but you can restrict it to particular testsuites
 by giving the names of the @emph{.exp expect} scripts that control
-them. @emph{testsuite}.exp may not include path information; use plain
+them. @emph{testsuite}.exp cannot include directory names, only plain
 filenames.
 
-@item @file{testfile}.exp="testfile1 ..."
-Specify a subset of tests in a suite to run. For compiler or assembler
-tests, which often use a single @emph{.exp} script covering many
-different source files, this option allows you to further restrict the
-tests by listing particular source files to compile. Some tools even
-support wildcards here.  The wildcards supported depend upon the tool,
-but typically they are @emph{?}, @emph{*}, and @emph{[chars]}.
+@code{arg(s)} specifies a subset of tests in a suite to run. For
+compiler or assembler tests, which often use a single @emph{.exp} script
+covering many different source files, this option allows you to further
+restrict the tests by listing particular source files to compile. Some
+tools even support wildcards here.  The wildcards supported depend upon
+the tool, but typically @emph{?}, @emph{*}, and @emph{[chars]} are
+recognized.
 
 @item @code{tclvar}=value
 You can define Tcl variables for use by your test scripts in the same
@@ -652,41 +659,35 @@ For example, if the directory @file{gdb/testsuite} contains a collection
 of DejaGnu tests for GDB, you can run them like this:
 
 @example
-
-	  $ cd gdb/testsuite
-	  $ runtest --tool gdb
-	
+$ cd gdb/testsuite
+$ runtest --tool gdb
 @end example
 
 The test output follows, then ends with:
 
 @example
+=== gdb Summary ===
 
-		=== gdb Summary ===
-
-		# of expected passes 508
-		# of expected failures 103
-		/usr/latest/bin/gdb version 4.14.4 -nx
-	
+# of expected passes 508
+# of expected failures 103
+/usr/latest/bin/gdb version 4.14.4 -nx
 @end example
 
 You can use the option @code{--srcdir} to point to some other directory
 containing a collection of tests:
 
 @example
-
-	  $ runtest --srcdir /devo/gdb/testsuite
-	
+$ runtest --srcdir /devo/gdb/testsuite
 @end example
 
 By default, @code{runtest} prints only the names of the tests it runs,
 output from any tests that have unexpected results, and a summary
 showing how many tests passed and how many failed.  To display output
 from all tests (whether or not they behave as expected), use the
-@code{--all} option.  For more verbose output about processes being run,
-communication, and so on, use @code{--verbose}. To see even more output,
-use multiple @code{--verbose} options.  The @code{--help} for a more
-detailed explanation of each @code{runtest} option.
+@code{-a} (all) option.  For more verbose output about processes being
+run, communication, and so on, use @code{-v} (verbose). To see even more
+output, use multiple @code{-v} options.  See @ref{Invoking runtest} for
+a more detailed explanation of each @code{runtest} option.
 
 @node Output Files, , Runtest, Running tests
 @section Output files
@@ -730,7 +731,6 @@ option to select a different output directory.
 @strong{Sample summary log}
 
 @example
-
 	Test Run By bje on Sat Nov 14 21:04:30 AEDT 2015
 
 		 === gdb tests ===
@@ -768,7 +768,6 @@ a different output directory.
 @strong{Sample detailed log for g++ tests}
 
 @example
-
 	Test Run By bje on Sat Nov 14 21:07:23 AEDT 2015
 
                 === g++ tests ===
@@ -815,10 +814,8 @@ pattern it compares with the tool output by each @code{expect} command.
 The log messages begin with a message of the form:
 
 @example
-
 	expect: does @{tool output@} (spawn_id n)
  	   match pattern @{expected pattern@}?
-        
 @end example
 
 For every unsuccessful match, Expect issues a @emph{no} after this
@@ -835,7 +832,6 @@ variables set to describe a successful match.
 GDB test:}
 
 @example
-
 	send: sent @{break gdbme.c:34\n@} to spawn id 6
 	expect: does @{@} (spawn_id 6) match pattern @{Breakpoint.*at.* file
 	gdbme.c, line 34.*\(gdb\) $@}? no
@@ -979,11 +975,9 @@ you run @code{make}.
 @strong{The first section starts with}
 
 @example
-
 	## these variables are automatically generated by make ##
 	# Do not edit here. If you wish to override these values
 	# add them to the last section
-	
 @end example
 
 In the second section, you can override any default values (locally to
@@ -997,9 +991,7 @@ may also be empty, if you do not wish to override any defaults.)
 @strong{The first section ends with this line}
 
 @example
-
 	## All variables above are generated by configure. Do Not Edit ##
-	
 @end example
 
 You can make any changes under this line. If you wish to redefine a
@@ -1016,7 +1008,6 @@ Here's an example local site.exp file, as used for GCC/G++ testing.
 @strong{Local Config File}
 
 @example
-
       ## these variables are automatically generated by make ##
       # Do not edit here. If you wish to override these values
       # add them to the last section
@@ -1036,7 +1027,7 @@ Here's an example local site.exp file, as used for GCC/G++ testing.
 @end example
 
 This file defines the required fields for a local config file, namely
-the three config triplets, and the srcdir. It also defines several other
+the three system triplets, and the srcdir. It also defines several other
 Tcl variables that are used exclusively by the GCC testsuite. For most
 test cases, the CXXFLAGS and LDFLAGS are supplied by DejaGnu itself for
 cross testing, but to test a compiler, GCC needs to manipulate these
@@ -1050,153 +1041,150 @@ wait for a remote test to complete. If not specified,
 @node Global config file, Board config file, Local config file, Customizing DejaGnu
 @section Global config file
 
-The master config file is where all the target specific config variables
-for a whole site get set. The idea is that for a centralized testing lab
-where people have to share a target between multiple developers. There
-are settings for both remote targets and remote hosts.  Here's an
-example of a Master Config File (also called the Global config file) for
-a @emph{Canadian cross}. A Canadian cross is when you build and test a
-cross compiler on a machine other than the one it's to be hosted on.
-
-Here we have the config settings for our California office. Note that
-all config values are site dependent. Here we have two sets of values
-that we use for testing m68k-aout cross compilers. As both of these
-target boards has a different debugging protocol, we test on both of
-them in sequence.
-
-@strong{Global Config file}
+The global configuration file is where all the target specific
+configuration variables for an entire site get set. For example, a
+centralized testing lab where people have to share a target between
+multiple developers. There are settings for both remote targets and
+remote hosts.  Below is an example of a global configuration file for a
+@emph{Canadian cross} environment. A Canadian cross is when you build
+and test a cross-compiler on a platform other than the one it will run
+on (for example, building a Solaris cross MIPS toolchain on a GNU/Linux
+system).  Note that all configuration values below are site-dependent.
+Here we have two sets of values for testing m68k-aout
+cross-compilers. As both of these target boards has a different
+debugging protocol, we test on both of them in sequence.
+
+@strong{Example file}
 
 @example
-
-
-      # Make sure we look in the right place for the board description files.
-      if ![info exists boards_dir] @{
-          set boards_dir @{@}
-      @}
-      lappend boards_dir "/nfs/cygint/s1/cygnus/dejagnu/boards"
-
-      verbose "Global Config File: target_triplet is $target_triplet" 2
-      global target_list
-
-      case "$target_triplet" in @{
-          @{ "native" @} @{
-              set target_list "unix"
-          @}
-          @{ "sparc64-*elf" @} @{
-              set target_list "sparc64-sim"
-          @}
-          @{ "mips-*elf" @} @{
-              set target_list "mips-sim wilma barney"
-          @}
-          @{ "mips-lsi-elf" @} @{
-              set target_list "mips-lsi-sim@{,soft-float,el@}"
-          @}
-          @{ "sh-*hms" @} @{
-              set target_list @{ "sh-hms-sim" "bloozy" @}
-          @}
-      @}
-      
+# Make sure we look in the right place for the board description files.
+lappend boards_dir "/nfs/cygint/s1/cygnus/dejagnu/boards"
+
+verbose "Global config file: target_triplet is $target_triplet" 2
+global target_list
+
+case "$target_triplet" in @{
+    @{ "native" @} @{
+        set target_list "unix"
+    @}
+    @{ "sparc64-*elf" @} @{
+        set target_list "sparc64-sim"
+    @}
+    @{ "mips-*elf" @} @{
+        set target_list "mips-sim wilma barney"
+    @}
+    @{ "mips-lsi-elf" @} @{
+        set target_list "mips-lsi-sim@{,soft-float,el@}"
+    @}
+@}
 @end example
 
 In this case, we have support for several cross compilers, that all run
-on this host. For testing on operating systems that don't support
-Expect, DejaGnu can be run on the local build machine, and it can
-connect to the remote host and run all the tests for this cross compiler
-on that host. All the remote OS requires is a working Telnet server.
-
-As you can see, all one does is set the variable @code{target_list} to
-the list of targets and options to test. The simple settings, like for
-@emph{sparc64-elf} only require setting the name of the single board
-config file. The @emph{mips-elf} target is more complicated. Here it
-sets the list to three target boards. One is the default mips target,
-and both @emph{wilma} @emph{barney} are symbolic names for other mips
+on this host. For testing tools that run on operating systems that
+cannot run Expect natively, DejaGnu can be run on the build machine and
+connect to the remote host to run all the tests for this cross compiler
+on that host.  As you can see, all one does is set the variable
+@code{target_list} to the list of targets and options to test.
+
+The simple settings, like for @emph{sparc64-elf} only require setting
+the name of the single board configuration file. The @emph{mips-elf}
+target is more complicated and sets the list to three target
+boards. @emph{mips-sim} is a symbolic name for a simulator target and
+@emph{wilma} and @emph{barney} are symbolic names for MIPS
 boards. Symbolic names are covered in the @ref{Adding a new board}
-chapter. The more complicated example is the one for
+section. The more complicated example is the entry for
 @emph{mips-lsi-elf}. This one runs the tests with multiple iterations
 using all possible combinations of the @code{--soft-float} and the
-@code{--el} (little endian) option. Needless to say, this last feature
-is mostly compiler specific.
+@code{--el} (little endian) options.  The braced string includes an
+initial comma so that the set of combinations includes no options at
+all. Needless to say, this last target example is mostly specific to
+compiler testing.
 
 @node Board config file, Remote host testing, Global config file, Customizing DejaGnu
 @section Board configuration file
 
-The board config file is where board-specific configuration details are
-stored. A board config file contains all the higher-level configuration
-settings. There is a rough inheritance scheme, where it is possible to
-derive a new board description file from an existing one. There are also
-collections of custom procedures for common environments. For more
-information on adding a new board config file, go to the @ref{Adding a
-new board} section.
+The board configuration file is where board-specific configuration
+details are stored. A board configuration file contains all the
+higher-level configuration settings. There is a rough inheritance
+scheme, where it is possible to derive a new board description file from
+an existing one. There are also collections of custom procedures for
+common environments. For more information on adding a new board config
+file, go to the @ref{Adding a new board} section.
 
-An example board config file for a GNU simulator is as
+An example board configuration file for a GNU simulator is as
 follows. @code{set_board_info} is a procedure that sets the field name
-to the specified value. The procedures in square brackets @emph{[]} are
-@emph{helper procedures}. These are used to find parts of a tool chain
+to the specified value. The procedures mentioned in brackets are
+@emph{helper procedures}. These are used to find parts of a toolchain
 required to build an executable image that may reside in various
-locations. This is mostly of use for when the startup code, the standard
-C libraries, or the tool chain itself is part of your build tree.
-
-@strong{Board Configuration File}
+locations. This is mostly of use when the startup code, the standard C
+libraries, or the toolchain itself is part of your build tree.
 
+@strong{Example file}
 @example
-
-      # This is a list of toolchains that are supported on this board.
-      set_board_info target_install @{sparc64-elf@}
-
-      # Load the generic configuration for this board. This will define any
-      # routines needed by the tool to communicate with the board.
-      load_generic_config "sim"
-
-      # We need this for find_gcc and *_include_flags/*_link_flags.
-      load_base_board_description "basic-sim"
-
-      # Use long64 by default.
-      process_multilib_options "long64"
-
-      setup_sim sparc64
-
-      # We only support newlib on this target. We assume that all multilib
-      # options have been specified before we get here.
-      set_board_info compiler  "[find_gcc]"
-      set_board_info cflags  "[libgloss_include_flags] [newlib_include_flags]"
-      set_board_info ldflags  "[libgloss_link_flags] [newlib_link_flags]"
-      # No linker script.
-      set_board_info ldscript ""
-
-      # Used by a few gcc.c-torture testcases to delimit how large the
-      # stack can be.
-      set_board_info gcc,stack_size 16384
-      # The simulator doesn't return exit statuses and we need to indicate this
-      # the standard GCC wrapper will work with this target.
-      set_board_info needs_status_wrapper 1
-      # We can't pass arguments to programs.
-      set_board_info noargs 1
-      
+# This is a list of toolchains that are supported on this board.
+set_board_info target_install @{sparc64-elf@}
+
+# Load the generic configuration for this board. This will define any
+# routines needed by the tool to communicate with the board.
+load_generic_config "sim"
+
+# We need this for find_gcc and *_include_flags/*_link_flags.
+load_base_board_description "basic-sim"
+
+# Use long64 by default.
+process_multilib_options "long64"
+
+setup_sim sparc64
+
+# We only support newlib on this target. We assume that all multilib
+# options have been specified before we get here.
+
+set_board_info compiler "[find_gcc]"
+set_board_info cflags "[libgloss_include_flags] [newlib_include_flags]"
+set_board_info ldflags "[libgloss_link_flags] [newlib_link_flags]"
+# No linker script.
+set_board_info ldscript ""
+
+# Used by a few gcc.c-torture testcases to delimit how large the
+# stack can be.
+set_board_info gcc,stack_size 16384
+# The simulator doesn't return exit status and we need to indicate this
+# the standard GCC wrapper will work with this target.
+set_board_info needs_status_wrapper 1
+# We can't pass arguments to programs.
+set_board_info noargs 1
 @end example
 
-There are five helper procedures used in this example. The first one,
-@code{find gcc} looks for a copy of the GNU compiler in your build tree,
+There are five helper procedures used in this example:
+
+@itemize
+@item
+@code{find_gcc} looks for a copy of the GNU compiler in your build tree,
 or it uses the one in your path. This will also return the proper
 transformed name for a cross compiler if you whole build tree is
-configured for one. The next helper procedures are
-@code{libgloss_include_flags} & @code{libgloss_link_flags}. These return
-the proper flags to compiler and link an executable image using
-@ref{Libgloss}, the GNU BSP (Board Support Package). The final
-procedures are @code{newlib_include_flag} &
-@code{newlib_include_flag}. These find the Newlib C library, which is a
-reentrant standard C library for embedded systems comprising of non
-GPL'd code.
+configured for one.
 
-@node Remote host testing, Config file values, Board config file, Customizing DejaGnu
-@section Remote host testing
+@item
+@code{libgloss_include_flags} returns the flags to compile using
+@ref{Libgloss, libgloss}, the GNU board support package (BSP).
 
-@quotation
+@item
+@code{libgloss_link_flags} returns the flags to link an executable using
+@ref{Libgloss, libgloss}.
 
-@strong{Note}
+@item
+@code{newlib_include_flags} returns the flags to compile using
+@uref{https://sourceware.org/newlib, newlib}, a re-entrant standard C
+library for embedded systems comprising of non-GPL'd code
 
-Thanks to DJ Delorie for the original paper that this section is based
-on.
-@end quotation
+@item
+@code{newlib_link_flags} returns the flags to link an executable with
+@uref{https://sourceware.org/newlib, newlib}.
+
+@end itemize
+
+@node Remote host testing, Config file values, Board config file, Customizing DejaGnu
+@section Remote host testing
 
 DejaGnu also supports running the tests on a remote host. To set this
 up, the remote host needs an FTP server, and a telnet server. Currently
@@ -1236,15 +1224,12 @@ from releng's area in SV to your machine:
 @strong{Remote host setup}
 
 @example
-
-      cd /usr/local/swamp/testing
-      mkdir boards
-      scp darkstar.welcomehome.org:/dejagnu/cst/bin/MkTestDir .
-      scp darkstar.welcomehome.org:/dejagnu/site.exp .
-      scp darkstar.welcomehome.org:/dejagnu/boards/useless98r2.exp boards/foobar.exp
-      export DEJAGNU=/usr/local/swamp/testing/site.exp
-
-      
+cd /usr/local/swamp/testing
+mkdir boards
+scp darkstar.welcomehome.org:/dejagnu/cst/bin/MkTestDir .
+scp darkstar.welcomehome.org:/dejagnu/site.exp .
+scp darkstar.welcomehome.org:/dejagnu/boards/useless98r2.exp boards/foobar.exp
+export DEJAGNU=/usr/local/swamp/testing/site.exp
 @end example
 
 You must edit the boards/foobar.exp file to reflect your machine; change
@@ -1256,9 +1241,7 @@ Edit the global @file{ site.exp} to reflect your boards directory:
 @strong{Add The Board Directory}
 
 @example
-
-	lappend boards_dir "/usr/local/swamp/testing/boards"
-	
+lappend boards_dir "/usr/local/swamp/testing/boards"
 @end example
 
 Now run MkTestDir, which is in the contrib directory. The first
@@ -1269,9 +1252,7 @@ sh-hms-gcc.exe in your PATH on the PC), do something like this:
 @strong{Setup Cross Remote Testing}
 
 @example
-
-	./MkTestDir sh-hms /usr/dejagnu/src/devo
-	
+./MkTestDir sh-hms /usr/dejagnu/src/devo
 @end example
 
 If you are testing a native PC compiler (ex: you have
@@ -1280,9 +1261,7 @@ gcc.exe in your PATH on the PC), do this:
 @strong{Setup Native Remote Testing}
 
 @example
-
-	./MkTestDir '' /usr/dejagnu/src/devo
-	
+./MkTestDir '' /usr/dejagnu/src/devo
 @end example
 
 To test the setup, @code{ftp} to your PC using the username
@@ -1295,10 +1274,8 @@ default PATH contains the installation you want to test.
 @strong{Run Test Remotely}
 
 @example
-
-	cd /usr/local/swamp/testing
-	make  -k -w check RUNTESTFLAGS="--host_board foobar --target_board foobar -v -v" > check.out 2>&1
-	
+cd /usr/local/swamp/testing
+make  -k -w check RUNTESTFLAGS="--host_board foobar --target_board foobar -v -v" > check.out 2>&1
 @end example
 
 To run a specific test, use a command like this (for
@@ -1308,9 +1285,7 @@ MkTestDir created):
 @strong{Run a Test Remotely}
 
 @example
-
-	make check RUNTESTFLAGS="--host_board sloth --target_board sloth -v compile.exp=921202-1.c"
-	
+make check RUNTESTFLAGS="--host_board sloth --target_board sloth -v compile.exp=921202-1.c"
 @end example
 
 Note: if you are testing a cross-compiler, put in the correct target
@@ -1328,13 +1303,13 @@ part of the array.
 
 @menu
 * Command line option variables::
-* Personal config file::
+* User configuration file::
 @end menu
 
-@node Command line option variables, Personal config file, , Config file values
+@node Command line option variables, User configuration file, , Config file values
 @subsection Command line option variables
 
-In the user editable second section of the @ref{Personal config file}
+In the user editable second section of the @ref{User configuration file}
 you can not only override the configuration variables captured in the
 first section, but also specify default values for all on the
 @code{runtest} command line options.  Save for @code{--debug},
@@ -1345,50 +1320,77 @@ table describes the correspondence between command line options and
 variables you can set in @file{site.exp}.  @ref{Invoking runtest}, for
 explanations of the command-line options.
 
-@strong{Tcl Variables For Command Line Options}
+@multitable @columnfractions 0.2 0.2 0.6
+@item
+@strong{Option}@tab @strong{Tcl variable}@tab @strong{Description}
+
+@item
+-a, --all@tab all_flag@tab display all test results if set
 
-@multitable @columnfractions 0.1 0.2 0.7
 @item
-runtest option@tab Tcl variable@tab description
+--build@tab build_triplet@tab system triplet for the build host
+
 @item
---all@tab all_flag@tab display all test results if set
+--dir@tab cmdline_dir_to_run@tab run only tests in the specified directory
+
 @item
---outdir@tab outdir@tab directory for @file{tool.sum} and
-@file{tool.log.}
+--host@tab host_triplet@tab system triplet for the host
+
+@item
+--host_board@tab host_board@tab host board definition to use
+
+@item
+--ignore@tab ignoretests @tab do not run the specified tests
+
+@item
+--log_dialog@tab log_dialog@tab emit Expect output to standard output
+
+@item
+--outdir@tab outdir@tab directory for @file{.sum} and @file{.log} files
+
 @item
 --objdir@tab objdir@tab directory for pre-compiled binaries
+
 @item
---reboot@tab reboot@tab reboot the target if set to
-@emph{"1"}; do not reboot if set to
-@emph{"0"} (the default).
+--reboot@tab reboot@tab reboot the target if set to 1
+
 @item
 --srcdir@tab srcdir@tab directory of test subdirectories
+
 @item
---strace@tab tracelevel@tab a number: Tcl trace depth
+--target@tab target_triplet@tab system triplet for the target
+
 @item
---tool@tab tool@tab name of tool to test; identifies init, test subdir
+--target_board@tab target_list@tab list of target boards to run tests on
+
 @item
---verbose@tab verbose@tab verbosity level.  As option, use multiple times; as
-variable, set a number, 0 or greater.
+--tool@tab tool@tab name of tool to test (identifies init, test subdirectory)
+
 @item
---target@tab target_triplet@tab The canonical configuration string for the target.
+--tool_exec@tab TOOL_EXECUTABLE@tab path to the executable to test
+
 @item
---host@tab host_triplet@tab The canonical configuration string for the host.
+--tool_opts@tab TOOL_OPTIONS@tab additional options to pass to the tool
+
 @item
---build@tab build_triplet@tab The canonical configuration string for the build
-host.
+--tool_root_dir@tab tool_root_dir@tab tool root directory
+
 @item
---mail@tab address@tab Email the output log to the specified address.
+-v, --verbose@tab verbose@tab verbosity level greater than or equal to 0
+
 @end multitable
 
-@node Personal config file, , Command line option variables, Config file values
-@subsection Personal config file
+@node User configuration file, , Command line option variables, Config file values
+@subsection Per-user configuration file (.dejagnurc)
 
-The personal config file is used to customize @code{runtest's} behaviour
-for each user. It is typically used to set the user's preference for log
-verbosity, and for storing any experimental Tcl procedures. My personal
+The per-user configuration file is named @file{.dejagnurc} in the user's
+home directory.  It is used to customize the behaviour of @code{runtest}
+for each user -- typically the user's preference for log verbosity, and
+for storing any experimental Tcl procedures. An example
 @file{~/.dejagnurc} file looks like:
 
+@strong{Example .dejagnurc}
+
 @example
 set all_flag 1
 set RLOGIN /usr/ucb/rlogin
@@ -1423,8 +1425,8 @@ The testsuite for a new tool should always be located in that tools
 source directory. DejaGnu require the directory be named
 @file{testsuite}. Under this directory, the test cases go in a
 subdirectory whose name begins with the tool name. For example, for a
-tool named @emph{myprog}, each subdirectory containing testsuites must
-start with @emph{"myprog."}.
+tool named @emph{gdb}, each subdirectory containing testsuites must
+start with @samp{gdb.}.
 
 @node Adding a new tool, Adding a new target, Adding a new testsuite, Extending DejaGnu
 @section Adding a new tool
@@ -1442,9 +1444,7 @@ Nevertheless, it is straightforward to start a new testsuite.
 To help orient you further in this task, here is an outline of the steps
 to begin building a testsuite for a program example.
 
-@itemize 
 
-@item
 Create or select a directory to contain your new
 collection of tests. Change into that directory (shown here as
 @file{testsuite}):
@@ -1458,16 +1458,18 @@ write soon.  (For simplicity, we assume the environment is Unix, and use
 
 What else is needed in @file{configure.in} depends on the requirements
 of your tool, your intended test environments, and which configure
-system you use.  This example is a minimal configure.in for use with GNU
-Autoconf.
+system you use.  This example is a minimal @file{configure.ac} for use
+with GNU Autoconf.
+
+@subsection Sample Makefile.in Fragment
 
-@item
 Create @file{Makefile.in} (if using Autoconf), or @file{Makefile.am} (if
 using Automake), the source file used by configure to build your
 @file{Makefile}. If you are using GNU Automake.just add the keyword
 @emph{dejagnu} to the @emph{AUTOMAKE_OPTIONS} variable in your
 @file{Makefile.am} file. This will add all the @file{Makefile} support
-needed to run DejaGnu, and support the @ref{Make Check} target.
+needed to run DejaGnu, and support the @ref{Make Check, make check}
+target.
 
 You also need to include two targets important to DejaGnu: @emph{check},
 to run the tests, and @emph{site.exp}, to set up the Tcl copies of
@@ -1480,165 +1482,125 @@ the @emph{$tool} variable for the name of your program. If the local
 @file{site.exp} file is setup correctly, it is possible to execute the
 tests by merely typing @code{runtest} on the command line.
 
-@strong{Sample Makefile.in Fragment}
-
 @example
-
-	# Look for a local version of DejaGnu, otherwise use one in the path
-	RUNTEST = `if test -f $(top_srcdir)/../dejagnu/runtest; then \
-	      echo $(top_srcdir) ../dejagnu/runtest; \
-	    else \
-	       echo runtest; \
-	     fi`
-
-	# Flags to pass to runtest
-	RUNTESTFLAGS =
-
-	# Execute the tests
-	check: site.exp all
-        $(RUNTEST) $(RUNTESTFLAGS) \
-            --tool $@{example@} --srcdir $(srcdir)
-
-	# Make the local config file
-	site.exp: ./config.status Makefile
-	    @@echo "Making a new config file..."
-            -@@rm -f ./tmp?
-            @@touch site.exp
-
-            -@@mv site.exp site.bak
-            @@echo "## these variables are automatically\
- generated by make ##" > ./tmp0
-	    @@echo "# Do not edit here. If you wish to\
- override these values" >> ./tmp0
-            @@echo "# add them to the last section" >> ./tmp0
-            @@echo "set host_os $@{host_os@}" >> ./tmp0
-            @@echo "set host_alias $@{host_alias@}" >> ./tmp0
-            @@echo "set host_cpu $@{host_cpu@}" >> ./tmp0
-            @@echo "set host_vendor $@{host_vendor@}" >> ./tmp0
-            @@echo "set target_os $@{target_os@}" >> ./tmp0
-            @@echo "set target_alias $@{target_alias@}" >> ./tmp0
-            @@echo "set target_cpu $@{target_cpu@}" >> ./tmp0
-            @@echo "set target_vendor $@{target_vendor@}" >> ./tmp0
-            @@echo "set host_triplet $@{host_canonical@}" >> ./tmp0
-            @@echo "set target_triplet $@{target_canonical@}">>./tmp0
-            @@echo "set tool binutils" >> ./tmp0
-            @@echo "set srcdir $@{srcdir@}" >> ./tmp0
-            @@echo "set objdir `pwd`" >> ./tmp0
-            @@echo "set $@{examplename@} $@{example@}" >> ./tmp0
-            @@echo "## All variables above are generated by\
- configure. Do Not Edit ##" >> ./tmp0
-            @@cat ./tmp0 > site.exp
-            @@sed < site.bak \
-               -e '1,/^## All variables above are.*##/ d' \
-               >> site.exp
-            -@@rm -f ./tmp?
-
-	    
+# Look for a local version of DejaGnu, otherwise use one in the path
+RUNTEST = `if test -f $(top_srcdir)/../dejagnu/runtest; then \
+      echo $(top_srcdir) ../dejagnu/runtest; \
+    else \
+      echo runtest; \
+    fi`
+
+# Flags to pass to runtest
+RUNTESTFLAGS =
+
+# Execute the tests
+check: site.exp all
+        $(RUNTEST) $(RUNTESTFLAGS) --tool $@{example@} --srcdir $(srcdir)
+
+# Make the local config file
+site.exp: ./config.status Makefile
+	@@echo "Making a new config file..."
+        -@@rm -f ./tmp?
+        @@touch site.exp
+
+        -@@mv site.exp site.bak
+        @@echo "## these variables are automatically generated by make ##" > ./tmp0
+	@@echo "# Do not edit here. If you wish to override these values" >> ./tmp0
+        @@echo "# add them to the last section" >> ./tmp0
+        @@echo "set host_os $@{host_os@}" >> ./tmp0
+        @@echo "set host_alias $@{host_alias@}" >> ./tmp0
+        @@echo "set host_cpu $@{host_cpu@}" >> ./tmp0
+        @@echo "set host_vendor $@{host_vendor@}" >> ./tmp0
+        @@echo "set target_os $@{target_os@}" >> ./tmp0
+        @@echo "set target_alias $@{target_alias@}" >> ./tmp0
+        @@echo "set target_cpu $@{target_cpu@}" >> ./tmp0
+        @@echo "set target_vendor $@{target_vendor@}" >> ./tmp0
+        @@echo "set host_triplet $@{host_canonical@}" >> ./tmp0
+        @@echo "set target_triplet $@{target_canonical@}">>./tmp0
+        @@echo "set tool binutils" >> ./tmp0
+        @@echo "set srcdir $@{srcdir@}" >> ./tmp0
+        @@echo "set objdir `pwd`" >> ./tmp0
+        @@echo "set $@{examplename@} $@{example@}" >> ./tmp0
+        @@echo "## All variables above are generated by configure. Do Not Edit ##" >> ./tmp0
+        @@cat ./tmp0 > site.exp
+        @@sed < site.bak \
+            -e '1,/^## All variables above are.*##/ d' \
+            >> site.exp
+        -@@rm -f ./tmp?
 @end example
 
-@item
-Create a directory (in @file{testsuite})
-called @file{config}. Make a @emph{Tool Init
-File} in this directory. Its name must start with the
-@code{target_abbrev} value, or be named
-@file{default.exp} so call it
-@file{config/unix.exp} for our Unix based
-example. This is the file that contains the target-dependent
-procedures.  Fortunately, on a native Unix system, most of
-them do not have to do very much in order
-for @code{runtest} to run.  If the program being
-tested is not interactive, you can get away with this
-minimal @file{unix.exp} to begin with:
-
-@strong{Simple tool init file for batch programs}
+@subsection Simple tool init file for batch programs
 
-@example
+Create a directory (under @file{testsuite}) called @file{config}. Make a
+tool init file in this directory. Its name must start with the
+@code{target_abbrev} value, or be named @file{default.exp} so call it
+@file{config/unix.exp} for our Unix based example. This is the file that
+contains the target-dependent procedures.  Fortunately, on a native Unix
+system, most of them do not have to do very much in order for
+@code{runtest} to run.  If the program being tested is not interactive,
+you can get away with this minimal @file{unix.exp} to begin with:
 
-	  proc myprog_exit @{@} @{@}
-	  proc myprog_version @{@} @{@}
-	  
+@example
+proc myprog_exit @{@} @{@}
+proc myprog_version @{@} @{@}
 @end example
 
 If the program being tested is interactive, however, you might as well
 define a @emph{start} routine and invoke it by using a tool init file
 like this:
 
-@strong{Simple tool init file for interactive programs}
+@subsection Simple tool init file for interactive programs
 
 @example
-
-	  proc myprog_exit @{@} @{@}
-	  proc myprog_version @{@} @{@}
-
-	  proc myprog_start @{@} @{
-	    global $@{examplename@}
-	    spawn $@{examplename@}
-	    expect @{
-	        -re "" @{@}
-	    @}
-	  @}
-
-	  # Start the program running we want to test
-	  myprog_start
-	  
+proc myprog_exit @{@} @{@}
+proc myprog_version @{@} @{@}
+
+proc myprog_start @{@} @{
+     global $@{examplename@}
+     spawn $@{examplename@}
+     expect @{
+	-re "" @{@}
+     @}
+@}
+
+# Start the program running we want to test
+myprog_start
 @end example
 
-@item
-Create a directory whose name begins with your tool's
-name, to contain tests. For example, if your tool's name is
-@emph{myprog}, then the directories all need to start with
-@emph{"myprog."}.
-
-@item
-Create a sample test file. Its name must end with
-@file{.exp}. You can use
-@file{first-try.exp}. To begin with, just write there a
-line of Tcl code to issue a message.
-
-@strong{Testing A New Tool Config}
+Create a directory whose name begins with your tool's name, to contain
+tests. For example, if your tool's name is @emph{example}, then the
+directories all need to start with @samp{example.}.  Create a sample
+test file ending in @file{.exp}. You can use @file{first-try.exp}. To
+begin with, just write one line of Tcl code to issue a message:
 
 @example
-
-
-	  send_user "Testing: one, two...\n"
-
-	  
+send_user "Testing: one, two...\n"
 @end example
 
-@item
-Back in the @file{testsuite} (top level) directory, run
-@code{configure}. Typically you do this while in the build
-directory. You may have to specify more of a path, if a suitable
-configure is not available in your execution path.
+@subsection Testing A New Tool Config
 
-@item
+Back in the @file{testsuite} (top level) directory, run
+@code{configure}. Typically you do this while in the build directory.
 You are now ready to type @code{make check} or @code{runtest}.  You
 should see something like this:
 
-@strong{Example Test Case Run}
-
 @example
+Test Run By bje on Sat Nov 14 15:08:54 AEDT 2015
 
-	  Test Run By bje on Sat Nov 14 15:08:54 AEDT 2015
-
-                === example tests ===
-
-	  Running ./example.0/first-try.exp ...
-	  Testing: one, two...
+          === example tests ===
 
-                === example Summary ===
+Running ./example.0/first-try.exp ...
+Testing: one, two...
 
-	 
+          === example Summary ===
 @end example
 
 There is no output in the summary, because so far the example does not
 call any of the procedures that report a test outcome.
 
-@item
 Write some real tests. For an interactive tool, you should probably
 write a real exit routine in fairly short order. In any case, you should
 also write a real version routine soon.
-@end itemize
 
 @node Adding a new target, Adding a new board, Adding a new tool, Extending DejaGnu
 @section Adding a new target
@@ -1699,9 +1661,7 @@ are similar target environments with just different processors.
 @strong{Testing a New Board Configuration File}
 
 @example
-
-      make check RUNTESTFLAGS="--target_board=newboardfile".
-      
+make check RUNTESTFLAGS="--target_board=newboardfile".
 @end example
 
 Here's an example of a board config file. There are several @emph{helper
@@ -1715,40 +1675,36 @@ execution characters.
 @strong{Example Board Configuration File}
 
 @example
+# Load the generic configuration for this board. This will define a basic
+# set of routines needed by the tool to communicate with the board.
+load_generic_config "sim"
 
+# basic-sim.exp is a basic description for the standard Cygnus simulator.
+load_base_board_description "basic-sim"
 
-      # Load the generic configuration for this board. This will define a basic
-      # set of routines needed by the tool to communicate with the board.
-      load_generic_config "sim"
-
-      # basic-sim.exp is a basic description for the standard Cygnus simulator.
-      load_base_board_description "basic-sim"
-
-      # The compiler used to build for this board. This has *nothing* to do
-      # with what compiler is tested if we're testing gcc.
-      set_board_info compiler "[find_gcc]"
+# The compiler used to build for this board. This has *nothing* to do
+# with what compiler is tested if we're testing gcc.
+set_board_info compiler "[find_gcc]"
 
-      # We only support newlib on this target.
-      # However, we include libgloss so we can find the linker scripts.
-      set_board_info cflags "[newlib_include_flags] [libgloss_include_flags]"
-      set_board_info ldflags "[newlib_link_flags]"
+# We only support newlib on this target.
+# However, we include libgloss so we can find the linker scripts.
+set_board_info cflags "[newlib_include_flags] [libgloss_include_flags]"
+set_board_info ldflags "[newlib_link_flags]"
 
-      # No linker script for this board.
-      set_board_info ldscript "-Tsim.ld"
+# No linker script for this board.
+set_board_info ldscript "-Tsim.ld"
 
-      # The simulator doesn't return exit statuses and we need to indicate this.
-      set_board_info needs_status_wrapper 1
+# The simulator doesn't return exit statuses and we need to indicate this.
+set_board_info needs_status_wrapper 1
 
-      # Can't pass arguments to this target.
-      set_board_info noargs 1
+# Can't pass arguments to this target.
+set_board_info noargs 1
 
-      # No signals.
-      set_board_info gdb,nosignals 1
+# No signals.
+set_board_info gdb,nosignals 1
 
-      # And it can't call functions.
-      set_board_info gdb,cannot_call_functions 1
-
-      
+# And it can't call functions.
+set_board_info gdb,cannot_call_functions 1
 @end example
 
 @node Board file values, Writing a test case, Adding a new board, Extending DejaGnu
@@ -2129,7 +2085,7 @@ Most regression testing as done by DejaGnu is system testing: the
 complete application is tested all at once. Unit testing is for testing
 single files, or small libraries. In this case, each file is linked with
 a test case in C or C++, and each function or class and method is tested
-in series, with the test case having to check private data or global
+in turn, with the test case having to check private data or global
 variables to see if the function or method worked.
 
 This works particularly well for testing APIs and at level where it is
@@ -2152,66 +2108,52 @@ the output messages, and then merge them into DejaGnu's.
 @node C unit testing API, C++ unit testing API, The dejagnu_h header file, Unit testing
 @section C unit testing API
 
-All of the functions that take a @code{msg} parameter use a C char *
-that is the message to be displayed. There currently is no support for
-variable length arguments.
-
-@menu
-* Pass Function: pass function.
-* Fail Function: fail function.
-* Untested Function: untested function.
-* Unresolved Function: unresolved function.
-* Totals Function: totals function.
-@end menu
-
-@node pass function, fail function, , C unit testing API
-@subsection Pass Function
+All of the functions that take a @code{msg} parameter use a C @code{char
+*} that is the message to be displayed. There currently is no support
+for variable length arguments.
 
-This prints a message for a successful test completion.
+@itemize
+@item
+@code{pass} prints a message for a successful test completion.
 
 @quotation
-@t{@b{pass}@{@i{msg}@}}
+@t{@b{pass}(@i{msg});}
 @end quotation
 
-@node fail function, untested function, pass function, C unit testing API
-@subsection Fail Function
-
-This prints a message for an unsuccessful test completion.
+@item
+@code{fail} prints a message for an unsuccessful test completion.
 
 @quotation
-@t{@b{fail}@{@i{msg}@}}
+@t{@b{fail}(@i{msg});}
 @end quotation
 
-@node untested function, unresolved function, fail function, C unit testing API
-@subsection Untested Function
-
-This prints a message for an test case that isn't run for some technical
-reason.
+@item
+@code{untested} prints a message for an test case that isn't run for
+some technical reason.
 
 @quotation
-@t{@b{untested}@{@i{msg}@}}
+@t{@b{untested}(@i{msg});}
 @end quotation
 
-@node unresolved function, totals function, untested function, C unit testing API
-@subsection Unresolved Function
-
-This prints a message for an test case that is run, but there is no
-clear result. These output states require a human to look over the
-results to determine what happened.
+@item
+@code{unresolved} prints a message for an test case that is run, but
+there is no clear result. These output states require a human to look
+over the results to determine what happened.
 
 @quotation
-@t{@b{unresolved}@{@i{msg}@}}
+@t{@b{unresolved}(@i{msg});}
 @end quotation
 
-@node totals function, , unresolved function, C unit testing API
-@subsection Totals Function
-
-This prints out the total numbers of all the test state outputs.
+@item
+@code{totals} prints out the total numbers of all the test state
+outputs.
 
 @quotation
-@t{@b{totals}}
+@t{@b{totals}();}
 @end quotation
 
+@end itemize
+
 @node C++ unit testing API, , C unit testing API, Unit testing
 @section C++ unit testing API
 
@@ -2219,61 +2161,47 @@ All of the methods that take a @code{msg} parameter use a C char * or
 STL string, that is the message to be displayed. There currently is no
 support for variable length arguments.
 
-@menu
-* Pass Method: pass method.
-* Fail Method: fail method.
-* Untested Method: untested method.
-* Unresolved Method: unresolved method.
-* Totals Method: totals method.
-@end menu
+@itemize
 
-@node pass method, fail method, , C++ unit testing API
-@subsection Pass Method
-
-This prints a message for a successful test completion.
+@item
+@code{pass} prints a message for a successful test completion.
 
 @quotation
 @t{@b{TestState::pass}(@i{msg});}
 @end quotation
 
-@node fail method, untested method, pass method, C++ unit testing API
-@subsection Fail Method
-
-This prints a message for an unsuccessful test completion.
+@code{fail} prints a message for an unsuccessful test completion.
 
 @quotation
 @t{@b{TestState::fail}(@i{msg});}
 @end quotation
 
-@node untested method, unresolved method, fail method, C++ unit testing API
-@subsection Untested Method
-
-This prints a message for an test case that isn't run for some reason.
+@code{untested} prints a message for an test case that isn't run for
+some reason.
 
 @quotation
 @t{@b{TestState::untested}(@i{msg});}
 @end quotation
 
-@node unresolved method, totals method, untested method, C++ unit testing API
-@subsection Unresolved Method
-
-This prints a message for an test case that is run, but there is no
-clear result. These output states require a human to look over the
-results to determine what happened.
+@item
+@code{unresolved} prints a message for an test case that is run, but
+there is no clear result. These output states require a human to look
+over the results to determine what happened.
 
 @quotation
 @t{@b{TestState::unresolved}(@i{msg});}
 @end quotation
 
-@node totals method, , unresolved method, C++ unit testing API
-@subsection Totals Method
-
-This prints out the total numbers of all the test state outputs.
+@item
+@code{totals} prints out the total numbers of all the test state
+outputs.
 
 @quotation
 @t{@b{TestState::totals}(@i{});}
 @end quotation
 
+@end itemize
+
 @node Reference, , Unit testing, Top
 @chapter Reference
 
@@ -2295,7 +2223,7 @@ DejaGnu provides these Tcl procedures.
 * Platform Dependent Procedures: platform dependent procedures.
 * Utility Procedures::
 * Libgloss, a free board support package (BSP): Libgloss.
-* Procedures for debugging your scripts: Debugging Procedures.
+* Debugging Procedures::
 @end menu
 
 @node Core Internal Procedures, Procedures For Remote Communication, , Builtin Procedures
@@ -2762,9 +2690,7 @@ the variable @code{compiler_conditional_xfail_data} to the
 fields
 
 @example
-
-	  "[message string] [targets list] [includes list] [excludes list]"
-	  
+"[message string] [targets list] [includes list] [excludes list]"
 @end example
 
 (descriptions below). This is the checked at pass/fail decision time, so
@@ -2805,14 +2731,12 @@ conditional is de-activated.
 @strong{Specifying the conditional xfail data}
 
 @example
-
 	  set compiler_conditional_xfail_data @{ \
 	       "I sure wish I knew why this was hosed" \
                "sparc*-sun*-* *-pc-*-*" \
                @{"-Wall -v" "-O3"@} \
                @{"-O1" "-Map"@} \
           @}
-	  
 @end example
 
 What this does is it matches only for these two targets if
@@ -2838,7 +2762,7 @@ list of configuration target names.  It is only necessary to call
 @table @asis
 
 @item @code{config}
-The configuration triplets to clear.
+The system triplets to clear.
 @end table
 
 @node verbose procedure, load_lib procedure, clear_xfail procedure, Core Internal Procedures
@@ -5166,8 +5090,7 @@ executable image for an embedded systems.
 @node Debugging Procedures, , Libgloss, Builtin Procedures
 @subsection Procedures for debugging your scripts
 
-@file{lib/debugger.exp}defines these utility
-procedures:
+@file{lib/debugger.exp} defines the following procedures:
 
 @menu
 * dumpvars Procedure: dumpvars procedure