* doc/dejagnu.texi: More overhauling.

2 files changed, 226 insertions, 370 deletions

diff --git a/ChangeLog b/ChangeLog
index 47da0d8..b25d6d9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2016-04-03  Ben Elliston  <bje@gnu.org>
+
+	* doc/dejagnu.texi: More overhauling.
+
 2016-04-02  Ben Elliston  <bje@gnu.org>
 
 	* doc/dejagnu.texi: Fill paragraphs.
diff --git a/doc/dejagnu.texi b/doc/dejagnu.texi
index 5f79503..68a2f8d 100644
--- a/doc/dejagnu.texi
+++ b/doc/dejagnu.texi
@@ -10,26 +10,31 @@
 @node Top, Introduction, , (dir)
 @top DejaGnu
 
+@ifnottex
+This file documents DejaGnu version 1.6.
+
+@insertcopying
+@end ifnottex
+
 @menu
 * Introduction::
-* Running Tests::
+* Running tests::
 * Customizing DejaGnu::
 * Extending DejaGnu::
-* Unit Testing::
+* Unit testing::
 * Reference::
 
 @detailmenu
---- The Detailed Node Listing ---
 
 Introduction
 
 * What is DejaGnu?::
-* New In This Release: Release Notes.
-* Design Goals::
+* New in this release: Release Notes.
+* Design goals::
 * A POSIX compliant test framework: A POSIX Conforming Test Framework.
 * Installation::
 
-Running Tests
+Running tests
 
 * Running 'make check': Make Check.
 * Running runtest: Runtest.
@@ -37,31 +42,31 @@ Running Tests
 
 Customizing DejaGnu
 
-* Local Config File::
-* Global Config File::
-* Board Configuration File: Board Config File.
-* Remote Host Testing::
-* Config File Values::
+* Local config file::
+* Global config file::
+* Board config file::
+* Remote host testing::
+* Config file values::
 
 Extending DejaGnu
 
 * Adding a new testsuite::
-* Adding a new tool: Adding A New Tool.
-* Adding A New Target::
+* Adding a new tool::
+* Adding a new target::
 * Adding a new board::
-* Board Configuration File Values: Board File Values.
-* Writing A Test Case::
-* Debugging A Test Case::
+* Board file values::
+* Writing a test case::
+* Debugging a test case::
 * Adding a test case to a testsuite::
-* Hints On Writing A Test Case::
+* Hints on writing a test case::
 * Test case special variables: Test case variables.
 
-Unit Testing
+Unit testing
 
-* What Is Unit Testing?::
+* What is unit testing?::
 * The dejagnu.h header file: The dejagnu_h header file.
-* C Unit Testing API::
-* C++ Unit Testing API::
+* C unit testing API::
+* C++ unit testing API::
 
 Reference
 
@@ -70,13 +75,13 @@ Reference
 @end detailmenu
 @end menu
 
-@node Introduction, Running Tests, Top, Top
+@node Introduction, Running tests, Top, Top
 @chapter Introduction
 
 @menu
 * What is DejaGnu?::
-* New In This Release: Release Notes.
-* Design Goals::
+* New in this release: Release Notes.
+* Design goals::
 * A POSIX compliant test framework: A POSIX Conforming Test Framework.
 * Installation::
 @end menu
@@ -106,7 +111,7 @@ DejaGnu offers several advantages for testing:
 
 @item
 The flexibility and consistency of the DejaGnu framework make it easy to
-write tests for any program, with either batch oriented, or interactive
+write tests for any program, with either batch-oriented, or interactive
 programs.
 
 @item
@@ -136,8 +141,8 @@ on Expect. Expect script filenames conventionally use @emph{.exp} as a
 suffix; for example, the main implementation of the DejaGnu test driver
 is in the file runtest.exp.)
 
-@node Release Notes, Design Goals, What is DejaGnu?, Introduction
-@section New In This Release
+@node Release Notes, Design goals, What is DejaGnu?, Introduction
+@section New in this release
 
 @itemize 
 
@@ -145,8 +150,8 @@ is in the file runtest.exp.)
 A completely new manual.
 @end itemize
 
-@node Design Goals, A POSIX Conforming Test Framework, Release Notes, Introduction
-@section Design Goals
+@node Design goals, A POSIX Conforming Test Framework, Release Notes, Introduction
+@section Design goals
 
 DejaGnu grew out of the internal needs of Cygnus Solutions (formerly
 Cygnus Support). Cygnus maintained and enhanced a variety of free
@@ -189,7 +194,7 @@ thereafter.  Once a communication procedure is written, any test can use
 it.  Currently DejaGnu can use @code{ssh}, @code{rsh}, @code{rlogin},
 @code{telnet}, @code{tip}, and @code{kermit} for remote communications.
 
-@node A POSIX Conforming Test Framework, Installation, Design Goals, Introduction
+@node A POSIX Conforming Test Framework, Installation, Design goals, Introduction
 @section A POSIX compliant test framework
 
 DejaGnu conforms to the POSIX 1003.3 standard for test frameworks. Rob
@@ -325,15 +330,15 @@ tools you want to test; then, in each test directory, run @emph{make
 check} to build auxiliary programs required by some of the tests, and
 run the test suites.
 
-@node Running Tests, Customizing DejaGnu, Introduction, Top
-@chapter Running Tests
+@node Running tests, Customizing DejaGnu, Introduction, Top
+@chapter Running tests
 
 There are two ways to execute a testsuite. The most common way is when
 there is existing support in the @file{Makefile} of the tool being
 tested. This usually consists of a @emph{check} target. The other way is
 to execute the @code{runtest} program directly. To run @code{runtest}
 directly from the command line requires either all of the correct
-command line options, or a @ref{Local Config File} must be set up
+command line options, or a @ref{Local config file} must be set up
 correctly.
 
 @menu
@@ -342,7 +347,7 @@ correctly.
 * Output files: Output Files.
 @end menu
 
-@node Make Check, Runtest, , Running Tests
+@node Make Check, Runtest, , Running tests
 @section Running 'make check'
 
 To run tests from an existing collection, first use @code{configure} as
@@ -371,7 +376,7 @@ 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}.
 
-@node Runtest, Output Files, Make Check, Running Tests
+@node Runtest, Output Files, Make Check, Running tests
 @section Running runtest
 
 @code{runtest} is the test driver for DejaGnu. You can specify two kinds
@@ -683,7 +688,7 @@ 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.
 
-@node Output Files, , Runtest, Running Tests
+@node Output Files, , Runtest, Running tests
 @section Output files
 
 DejaGnu always writes two kinds of output files.  Summary output is
@@ -898,7 +903,7 @@ make the actions for fail-safe patterns produce messages starting with
 @emph{ERROR} on standard output, and in the detailed log file.
 @end itemize
 
-@node Customizing DejaGnu, Extending DejaGnu, Running Tests, Top
+@node Customizing DejaGnu, Extending DejaGnu, Running tests, Top
 @chapter Customizing DejaGnu
 
 The site configuration file, @file{site.exp}, captures
@@ -944,15 +949,15 @@ of any @file{site.exp}, or by setting variables on the @code{runtest}
 command line.
 
 @menu
-* Local Config File::
-* Global Config File::
-* Board Configuration File: Board Config File.
-* Remote Host Testing::
-* Config File Values::
+* Local config file::
+* Global config file::
+* Board config file::
+* Remote host testing::
+* Config file values::
 @end menu
 
-@node Local Config File, Global Config File, , Customizing DejaGnu
-@section Local Config File
+@node Local config file, Global config file, , Customizing DejaGnu
+@section Local config file
 
 It is usually more convenient to keep these @emph{manual overrides} in
 the @file{site.exp} local to each test directory, rather than in the
@@ -1042,8 +1047,8 @@ The local @file{site.exp} may also set Tcl variables such as
 wait for a remote test to complete. If not specified,
 @code{test_timeout} defaults to 300 seconds.
 
-@node Global Config File, Board Config File, Local Config File, Customizing DejaGnu
-@section Global Config File
+@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
@@ -1112,16 +1117,16 @@ 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.
 
-@node Board Config File, Remote Host Testing, Global Config File, Customizing DejaGnu
-@section Board Configuration File
+@node Board config file, Remote host testing, Global config file, Customizing DejaGnu
+@section Board configuration file
 
-The board config file is where board specific config data is stored. A
-board config file contains all the higher-level configuration
+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
-base a new board description file on an existing one. There are also
+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} chapter.
+new board} section.
 
 An example board config file for a GNU simulator is as
 follows. @code{set_board_info} is a procedure that sets the field name
@@ -1182,8 +1187,8 @@ procedures are @code{newlib_include_flag} &
 reentrant standard C library for embedded systems comprising of non
 GPL'd code.
 
-@node Remote Host Testing, Config File Values, Board Config File, Customizing DejaGnu
-@section Remote Host Testing
+@node Remote host testing, Config file values, Board config file, Customizing DejaGnu
+@section Remote host testing
 
 @quotation
 
@@ -1312,24 +1317,24 @@ Note: if you are testing a cross-compiler, put in the correct target
 board. You'll also have to download more .exp files and modify them for
 your local configuration. The -v's are optional.
 
-@node Config File Values, , Remote Host Testing, Customizing DejaGnu
-@section Config File Values
+@node Config file values, , Remote host testing, Customizing DejaGnu
+@section Config file values
 
-DejaGnu uses a named array in Tcl to hold all the info for
-each machine. In the case of a Canadian cross, this means host
-information as well as target information. The named array is
-called @code{target_info}, and it has two indices. The
-following fields are part of the array.
+DejaGnu uses a Tcl associative array to hold all the info for each
+machine. In the case of a Canadian cross, this means host information as
+well as target information. The named array is called
+@code{target_info}, and it has two indices. The following fields are
+part of the array.
 
 @menu
-* Command Line Option Variables: Option Variables.
-* Personal Config File::
+* Command line option variables::
+* Personal config file::
 @end menu
 
-@node Option Variables, Personal Config File, , Config File Values
-@subsection Command Line Option Variables
+@node Command line option variables, Personal config 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{Personal config 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},
@@ -1342,19 +1347,12 @@ explanations of the command-line options.
 
 @strong{Tcl Variables For Command Line Options}
 
-@multitable @columnfractions 0.333333333333333 0.333333333333333 0.333333333333333
+@multitable @columnfractions 0.1 0.2 0.7
 @item
 runtest option@tab Tcl variable@tab description
 @item
 --all@tab all_flag@tab display all test results if set
 @item
---baud@tab baud@tab set the default baud rate to something other than
-9600.
-@item
---connect@tab connectmode@tab @code{ssh}, @code{rlogin},
-@code{telnet}, @code{rsh},
-@code{kermit}, or @code{tip}
-@item
 --outdir@tab outdir@tab directory for @file{tool.sum} and
 @file{tool.log.}
 @item
@@ -1383,52 +1381,42 @@ host.
 --mail@tab address@tab Email the output log to the specified address.
 @end multitable
 
-@node Personal Config File, , Option Variables, Config File Values
-@subsection Personal Config File
+@node Personal config file, , Command line option variables, Config file values
+@subsection Personal config file
 
-The personal config file is used to customize
-@code{runtest's} behaviour for each person. It is
-typically used to set the user preferred setting for verbosity,
-and any experimental Tcl procedures. My personal
+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
 @file{~/.dejagnurc} file looks like:
 
-@strong{Personal Config File}
-
 @example
-
-	set all_flag 1
-	set RLOGIN /usr/ucb/rlogin
-	set RSH /usr/local/sbin/ssh
-	
+set all_flag 1
+set RLOGIN /usr/ucb/rlogin
+set RSH /usr/local/sbin/ssh
 @end example
 
-Here I set @code{all_flag} so I see all the test
-cases that PASS along with the ones that FAIL. I also set
-@code{RLOGIN} to the BSD version. I have
-Kerberos installed, and when I rlogin
-to a target board, it usually isn't supported. So I use the non
-secure version rather than the default that's in my path. I also
-set @code{RSH} to the SSH
-secure shell, as rsh is mostly used to test unix
-machines within a local network here.
-
-@node Extending DejaGnu, Unit Testing, Customizing DejaGnu, Top
+Here @code{all_flag} is set so that I see all the test cases that PASS
+along with the ones that FAIL. I also set @code{RLOGIN} to the BSD
+(non-Kerberos) version.  I also set @code{RSH} to the SSH secure shell,
+as rsh is mostly used to test Unix machines within a local network.
+
+@node Extending DejaGnu, Unit testing, Customizing DejaGnu, Top
 @chapter Extending DejaGnu
 
 @menu
 * Adding a new testsuite::
-* Adding a new tool: Adding A New Tool.
-* Adding A New Target::
+* Adding a new tool: Adding a new tool
+* Adding a new target::
 * Adding a new board::
-* Board Configuration File Values: Board File Values.
-* Writing A Test Case::
-* Debugging A Test Case::
+* Board file values::
+* Writing a test case::
+* Debugging a test case::
 * Adding a test case to a testsuite::
-* Hints On Writing A Test Case::
+* Hints on writing a test case::
 * Test case special variables: Test case variables.
 @end menu
 
-@node Adding a new testsuite, Adding A New Tool, , Extending DejaGnu
+@node Adding a new testsuite, Adding a new tool, , Extending DejaGnu
 @section Adding a new testsuite
 
 The testsuite for a new tool should always be located in that tools
@@ -1438,7 +1426,7 @@ 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."}.
 
-@node Adding A New Tool, Adding A New Target, Adding a new testsuite, Extending DejaGnu
+@node Adding a new tool, Adding a new target, Adding a new testsuite, Extending DejaGnu
 @section Adding a new tool
 
 In general, the best way to learn how to write code, or even prose, is
@@ -1483,8 +1471,8 @@ needed to run DejaGnu, and support the @ref{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
-configuration-dependent values. This is called the @ref{Local Config
-File} The @emph{check} target must invoke the @code{runtest} program to
+configuration-dependent values. This is called the @ref{Local config
+file} The @emph{check} target must invoke the @code{runtest} program to
 run the tests.
 
 The @emph{site.exp} target should usually set up (among other things)
@@ -1652,16 +1640,15 @@ 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
+@node Adding a new target, Adding a new board, Adding a new tool, Extending DejaGnu
+@section Adding a new target
 
 DejaGnu has some additional requirements for target support, beyond the
-general-purpose provisions of configure. DejaGnu must actively
-communicate with the target, rather than simply generating or managing
-code for the target architecture.  Therefore, each tool requires an
-initialization module for each target.  For new targets, you must supply
-a few Tcl procedures to adapt DejaGnu to the target.  This permits
-DejaGnu itself to remain target independent.
+general-purpose provisions of a @code{configure} script. DejaGnu must
+actively communicate with the target, rather than simply generating or
+managing code for the target architecture.  Therefore, each tool
+requires an initialization module for each target.  For new targets, you
+must supply a few Tcl procedures to adapt DejaGnu to the target.
 
 Usually the best way to write a new initialization module is to edit an
 existing initialization module; some trial and error will be
@@ -1669,11 +1656,10 @@ required. If necessary, you can use the @code{--debug} option to see
 what is really going on.
 
 When you code an initialization module, be generous in printing
-information controlled by the @code{verbose} procedure.  In
-cross-development environments, most of the work is in getting the
-communications right. Code for communicating via TCP/IP networks or
-serial lines is available in a DejaGnu library files such as
-@file{lib/telnet.exp}.
+information using the @code{verbose} procedure.  In cross-development
+environments, most of the work is in getting the communications
+right. Code for communicating via TCP/IP networks or serial lines is
+available in a DejaGnu library files such as @file{lib/telnet.exp}.
 
 If you suspect a communication problem, try running the connection
 interactively from Expect.  (There are three ways of running Expect as
@@ -1689,7 +1675,7 @@ arguments in @code{$targetname}, to establish a connection.  You should
 at least be able to get a prompt from any target that is physically
 connected.
 
-@node Adding a new board, Board File Values, Adding A New Target, Extending DejaGnu
+@node Adding a new board, Board file values, Adding a new target, Extending DejaGnu
 @section Adding a new board
 
 Adding a new board consists of creating a new board configuration
@@ -1765,19 +1751,18 @@ execution characters.
       
 @end example
 
-@node Board File Values, Writing A Test Case, Adding a new board, Extending DejaGnu
-@section Board Configuration File Values
+@node Board file values, Writing a test case, Adding a new board, Extending DejaGnu
+@section Board configuration file values
 
 These fields are all in the @code{board_info} array.  These are all set
 by using the @code{set_board_info} and @code{add_board_info} procedures
 as required. The parameters are the field name, followed by the value
-that the field is set to or is added to the field, respectively.
-
-@strong{Common Board Info Fields}
+that the field is set to or is added to the field, respectively.  Some
+common board info fields are shown below.
 
-@multitable @columnfractions 0.333333333333333 0.333333333333333 0.333333333333333
+@multitable @columnfractions 0.2 0.2 0.6
 @item
-Field@tab Sample Value@tab Description
+@strong{Field} @tab @strong{Sample value} @tab @strong{Description}
 @item
 compiler@tab "[find_gcc]"@tab The path to the compiler to use.
 @item
@@ -1834,16 +1819,12 @@ gdb_sect_offset@tab "0x41000000";@tab
 @item
 gdb_stub_ldscript@tab "-Wl,-Teva-stub.ld"@tab The linker script to use with a GDB stub.
 @item
-gdb,cannot_call_functions@tab 1@tab Whether GDB can call functions on the target,
-@item
 gdb,noargs@tab 1@tab Whether the target can take command line arguments.
 @item
 gdb,nosignals@tab 1@tab Whether there are signals on the target.
 @item
 gdb,short_int@tab 1@tab 
 @item
-gdb,start_symbol@tab "_start";@tab The starting symbol in the executable.
-@item
 gdb,target_sim_options@tab "-sparclite"@tab Special options to pass to the simulator.
 @item
 gdb,timeout@tab 540@tab Timeout value to use for remote communication.
@@ -1866,8 +1847,6 @@ gdb_stub_offset@tab "0x12010000"@tab
 @item
 use_gdb_stub@tab 1@tab Whether to use a GDB stub.
 @item
-use_vma_offset@tab 1@tab 
-@item
 wrap_m68k_aout@tab 1@tab 
 @item
 gcc,no_label_values@tab 1@tab 
@@ -1878,7 +1857,7 @@ gcc,no_varargs@tab 1@tab
 @item
 gcc,stack_size@tab 16384@tab Stack size to use with some GCC testcases.
 @item
-ieee_multilib_flags@tab "-mieee";@tab 
+ieee_multilib_flags@tab "-mieee"@tab 
 @item
 is_simulator@tab 1@tab 
 @item
@@ -1890,38 +1869,32 @@ no_long_long@tab 1@tab
 @item
 noargs@tab 1@tab 
 @item
-nullstone,lib@tab "mips-clock.c"@tab 
-@item
-nullstone,ticks_per_sec@tab 3782018@tab 
-@item
-sys_speed_value@tab 200@tab 
-@item
 target_install@tab @{sh-hms@}@tab 
 @end multitable
 
-@node Writing A Test Case, Debugging A Test Case, Board File Values, Extending DejaGnu
-@section Writing A Test Case
+@node Writing a test case, Debugging a test case, Board file values, Extending DejaGnu
+@section Writing a test case
 
 The easiest way to prepare a new test case is to base it on an existing
 one for a similar situation.  There are two major categories of tests:
-batch or interactive.  Batch oriented tests are usually easier to write.
+batch-oriented and interactive.  Batch-oriented tests are usually easier
+to write.
 
-The GCC tests are a good example of batch oriented tests.  All GCC tests
+The GCC tests are a good example of batch-oriented tests.  All GCC tests
 consist primarily of a call to a single common procedure, since all the
 tests either have no output, or only have a few warning messages when
-successfully compiled.  Any non-warning output is a test failure.  All
-the C code needed is kept in the test directory.  The test driver,
-written in Tcl, need only get a listing of all the C files in the
-directory, and compile them all using a generic procedure. This
+successfully compiled.  Any non-warning output constitutes a test
+failure.  All the C code needed is kept in the test directory.  The test
+driver, written in Tcl, need only get a listing of all the C files in
+the directory, and compile them all using a generic procedure. This
 procedure and a few others supporting for these tests are kept in the
-library module @file{lib/c-torture.exp} in the GCC test suite. Most
-tests of this kind use very few Expect features, and are coded almost
-purely in Tcl.
+library module @file{lib/c-torture.exp} of the GCC testsuite. Most tests
+of this kind use very few Expect features, and are coded almost purely
+in Tcl.
 
 Writing the complete suite of C tests, then, consisted of these steps:
 
 @itemize 
-
 @item
 Copying all the C code into the test directory.  These tests were based
 on the C-torture test created by Torbjorn Granlund (on behalf of the
@@ -1950,8 +1923,8 @@ cases.  Accordingly, the best approach was simply to encapsulate the
 existing GDB tests, for reporting purposes. Thereafter, new GDB tests
 built up a family of Tcl procedures specialized for GDB testing.
 
-@node Debugging A Test Case, Adding a test case to a testsuite, Writing A Test Case, Extending DejaGnu
-@section Debugging A Test Case
+@node Debugging a test case, Adding a test case to a testsuite, Writing a test case, Extending DejaGnu
+@section Debugging a test case
 
 These are the kinds of debugging information available
 from DejaGnu:
@@ -1999,7 +1972,7 @@ actions to the expect standard output, to the detailed log file, and (if
 @code{--debug} is on) to @file{dbg.log}.
 @end itemize
 
-@node Adding a test case to a testsuite, Hints On Writing A Test Case, Debugging A Test Case, Extending DejaGnu
+@node Adding a test case to a testsuite, Hints on writing a test case, Debugging a test case, Extending DejaGnu
 @section Adding a test case to a testsuite
 
 There are two slightly different ways to add a test case. One is to add
@@ -2050,8 +2023,8 @@ To add support in the new directory for configure and make, you must
 also create a @file{Makefile.in} and a @file{configure.in}.
 @end itemize
 
-@node Hints On Writing A Test Case, Test case variables, Adding a test case to a testsuite, Extending DejaGnu
-@section Hints On Writing A Test Case
+@node Hints on writing a test case, Test case variables, Adding a test case to a testsuite, Extending DejaGnu
+@section Hints on writing a test case
 
 It is safest to write patterns that match all the output generated by
 the tested program; this is called closure.  If a pattern does not match
@@ -2100,7 +2073,7 @@ misleading. Ideally, a test in this sort of situation should not fail
 either. Instead, print an error message by calling one of the DejaGnu
 procedures @code{error} or @code{warning}.
 
-@node Test case variables, , Hints On Writing A Test Case, Extending DejaGnu
+@node Test case variables, , Hints on writing a test case, Extending DejaGnu
 @section Test case special variables
 
 There are special variables that contain other information from
@@ -2130,7 +2103,7 @@ in turn be executed to complete a test.
 
 @item $comp_output
 This is the output from a @code{$@{tool@}_start} command.  This is
-conventionally used for batch oriented programs, like GCC and GAS, that
+conventionally used for batch-oriented programs, like GCC and GAS, that
 may produce interesting output (warnings, errors) without further
 interaction.
 
@@ -2139,18 +2112,18 @@ The output from the last command. This is an internal variable set by
 Expect. More information can be found in the Expect manual.
 @end table
 
-@node Unit Testing, Reference, Extending DejaGnu, Top
-@chapter Unit Testing
+@node Unit testing, Reference, Extending DejaGnu, Top
+@chapter Unit testing
 
 @menu
-* What Is Unit Testing?::
+* What is unit testing?::
 * The dejagnu.h header file: The dejagnu_h header file.
-* C Unit Testing API::
-* C++ Unit Testing API::
+* C unit testing API::
+* C++ unit testing API::
 @end menu
 
-@node What Is Unit Testing?, The dejagnu_h header file, , Unit Testing
-@section What Is Unit Testing?
+@node What is unit testing?, The dejagnu_h header file, , Unit testing
+@section What is unit testing?
 
 Most regression testing as done by DejaGnu is system testing: the
 complete application is tested all at once. Unit testing is for testing
@@ -2164,7 +2137,7 @@ easier to debug them, than by needing to trace through the entire
 application. Also if there is a specification for the API to be tested,
 the testcase can also function as a compliance test.
 
-@node The dejagnu_h header file, C Unit Testing API, What Is Unit Testing?, Unit Testing
+@node The dejagnu_h header file, C unit testing API, What is unit testing?, Unit testing
 @section The dejagnu.h header file
 
 DejaGnu uses a single header file, @file{dejagnu.h} to assist in unit
@@ -2176,8 +2149,8 @@ standardized, DejaGnu can be made to work with this test case, without
 writing almost any Tcl. The library module, dejagnu.exp, will look for
 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
+@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
@@ -2191,7 +2164,7 @@ variable length arguments.
 * Totals Function: totals function.
 @end menu
 
-@node pass function, fail function, , C Unit Testing API
+@node pass function, fail function, , C unit testing API
 @subsection Pass Function
 
 This prints a message for a successful test completion.
@@ -2200,7 +2173,7 @@ This prints a message for a successful test completion.
 @t{@b{pass}@{@i{msg}@}}
 @end quotation
 
-@node fail function, untested function, pass function, C Unit Testing API
+@node fail function, untested function, pass function, C unit testing API
 @subsection Fail Function
 
 This prints a message for an unsuccessful test completion.
@@ -2209,7 +2182,7 @@ This prints a message for an unsuccessful test completion.
 @t{@b{fail}@{@i{msg}@}}
 @end quotation
 
-@node untested function, unresolved function, fail function, C Unit Testing API
+@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
@@ -2219,7 +2192,7 @@ reason.
 @t{@b{untested}@{@i{msg}@}}
 @end quotation
 
-@node unresolved function, totals function, untested function, C Unit Testing API
+@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
@@ -2230,7 +2203,7 @@ results to determine what happened.
 @t{@b{unresolved}@{@i{msg}@}}
 @end quotation
 
-@node totals function, , unresolved function, C Unit Testing API
+@node totals function, , unresolved function, C unit testing API
 @subsection Totals Function
 
 This prints out the total numbers of all the test state outputs.
@@ -2239,14 +2212,12 @@ This prints out the total numbers of all the test state outputs.
 @t{@b{totals}}
 @end quotation
 
-@node C++ Unit Testing API, , C Unit Testing API, Unit Testing
-@section C++ Unit Testing API
+@node C++ unit testing API, , C unit testing API, Unit testing
+@section C++ unit testing API
 
-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.
+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.
@@ -2256,7 +2227,7 @@ length arguments.
 * Totals Method: totals method.
 @end menu
 
-@node pass method, fail method, , C++ Unit Testing API
+@node pass method, fail method, , C++ unit testing API
 @subsection Pass Method
 
 This prints a message for a successful test completion.
@@ -2265,7 +2236,7 @@ This prints a message for a successful test completion.
 @t{@b{TestState::pass}(@i{msg});}
 @end quotation
 
-@node fail method, untested method, pass method, C++ Unit Testing API
+@node fail method, untested method, pass method, C++ unit testing API
 @subsection Fail Method
 
 This prints a message for an unsuccessful test completion.
@@ -2274,17 +2245,16 @@ This prints a message for an unsuccessful test completion.
 @t{@b{TestState::fail}(@i{msg});}
 @end quotation
 
-@node untested method, unresolved method, fail method, C++ Unit Testing API
+@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 technical
-reason.
+This 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
+@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
@@ -2295,7 +2265,7 @@ results to determine what happened.
 @t{@b{TestState::unresolved}(@i{msg});}
 @end quotation
 
-@node totals method, , unresolved method, C++ Unit Testing API
+@node totals method, , unresolved method, C++ unit testing API
 @subsection Totals Method
 
 This prints out the total numbers of all the test state outputs.
@@ -2304,7 +2274,7 @@ This prints out the total numbers of all the test state outputs.
 @t{@b{TestState::totals}(@i{});}
 @end quotation
 
-@node Reference, , Unit Testing, Top
+@node Reference, , Unit testing, Top
 @chapter Reference
 
 @menu
@@ -2332,7 +2302,6 @@ DejaGnu provides these Tcl procedures.
 @subsection Core Internal Procedures
 
 @menu
-* mail_file Procedure: mail_file procedure
 * open_logs Procedure: open_logs procedure
 * close_logs Procedure: close_logs procedure
 * isbuild Procedure: isbuild procedure
@@ -2341,13 +2310,9 @@ DejaGnu provides these Tcl procedures.
 * ishost Procedure: ishost procedure
 * istarget Procedure: istarget procedure
 * isnative Procedure: isnative procedure
-* unknown Procedure: unknown procedure
-* clone_output Procedure: clone_output procedure
-* reset_vars Procedure: reset_vars procedure
 * log_and_exit Procedure: log_and_exit procedure
 * log_summary Procedure: log_summary procedure
 * setup_xfail Procedure: setup_xfail procedure
-* record_test Procedure: record_test procedure
 * pass Procedure: pass procedure
 * fail Procedure: fail procedure
 * xpass Procedure: xpass procedure
@@ -2360,8 +2325,6 @@ DejaGnu provides these Tcl procedures.
 * untested Procedure: untested procedure
 * unresolved Procedure: unresolved procedure
 * unsupported Procedure: unsupported procedure
-* init_testcounts Procedure: init_testcounts procedure
-* incr_count Procedure: incr_count procedure
 * transform Procedure: transform procedure
 * check_conditional_xfail Procedure: check_conditional_xfail procedure
 * clear_xfail Procedure: clear_xfail procedure
@@ -2369,22 +2332,11 @@ DejaGnu provides these Tcl procedures.
 * load_lib Procedure: load_lib procedure
 @end menu
 
-@node mail_file procedure, open_logs procedure, , Core Internal Procedures
-@subsubsection mail_file Procedure
-
-@quotation
-@t{@b{mail_file}@{@i{file to
-subject}@}}
-@end quotation
-
-@table @asis
-
-@item @code{}
-@end table
-
-@node open_logs procedure, close_logs procedure, mail_file procedure, Core Internal Procedures
+@node open_logs procedure, close_logs procedure, , Core Internal Procedures
 @subsubsection open_logs Procedure
 
+Open the output logs.
+
 @quotation
 @t{@b{open_logs}}
 @end quotation
@@ -2392,6 +2344,7 @@ subject}@}}
 @node close_logs procedure, isbuild procedure, open_logs procedure, Core Internal Procedures
 @subsubsection close_logs Procedure
 
+Close the output logs.
 
 @quotation
 @t{@b{close_logs}}
@@ -2420,22 +2373,18 @@ string, then it returns the name of the build canonical configuration.
 @node is_remote procedure, is3way procedure, isbuild procedure, Core Internal Procedures
 @subsubsection is_remote Procedure
 
+Is @i{board} remote? Return a non-zero value, if so.
 
 @quotation
-@t{@b{is_remote}@{@i{board}@}}
+@t{@b{is_remote} @{@i{ board }@}}
 @end quotation
 
-@table @asis
-
-@item @code{}
-@end table
-
 @node is3way procedure, ishost procedure, is_remote procedure, Core Internal Procedures
 @subsubsection is3way Procedure
 
 Tests for a Canadian cross. This is when the tests will be run on a
-remotely hosted cross compiler. If it is a Canadian cross, then the
-result is @emph{1}; otherwise the result is @emph{0}.
+remotely hosted cross-compiler. If it is a Canadian cross, then the
+result is @emph{1}; otherwise @emph{0}.
 
 @quotation
 @t{@b{is3way}}
@@ -2472,14 +2421,14 @@ syntax, to specify sets of names). If it is passed a @emph{NULL} string,
 then it returns the name of the build canonical configuration.
 
 @quotation
-@t{@b{istarget}@{@i{args}@}}
+@t{@b{istarget} @{ @i{args} @}}
 @end quotation
 
 @table @asis
 @item @code{}
 @end table
 
-@node isnative procedure, unknown procedure, istarget procedure, Core Internal Procedures
+@node isnative procedure, log_and_exit procedure, istarget procedure, Core Internal Procedures
 @subsubsection isnative Procedure
 
 Tests whether the current configuration has the same host and
@@ -2490,40 +2439,7 @@ target. When it runs in a native configuration this procedure returns a
 @t{@b{isnative}}
 @end quotation
 
-@node unknown procedure, clone_output procedure, isnative procedure, Core Internal Procedures
-@subsubsection unknown Procedure
-
-
-@quotation
-@t{@b{unknown}@{@i{args}@}}
-@end quotation
-
-@table @asis
-@item @code{args}
-@end table
-
-@node clone_output procedure, reset_vars procedure, unknown procedure, Core Internal Procedures
-@subsubsection clone_output Procedure
-
-
-@quotation
-@t{@b{clone_output}@{@i{message}@}}
-@end quotation
-
-@table @asis
-
-@item @code{message}
-@end table
-
-@node reset_vars procedure, log_and_exit procedure, clone_output procedure, Core Internal Procedures
-@subsubsection reset_vars Procedure
-
-
-@quotation
-@t{@b{reset_vars}}
-@end quotation
-
-@node log_and_exit procedure, log_summary procedure, reset_vars procedure, Core Internal Procedures
+@node log_and_exit procedure, log_summary procedure, isnative procedure, Core Internal Procedures
 @subsubsection log_and_exit Procedure
 
 
@@ -2543,7 +2459,7 @@ target. When it runs in a native configuration this procedure returns a
 @item @code{args}
 @end table
 
-@node setup_xfail procedure, record_test procedure, log_summary procedure, Core Internal Procedures
+@node setup_xfail procedure, pass procedure, log_summary procedure, Core Internal Procedures
 @subsubsection setup_xfail Procedure
 
 Declares that the test is expected to fail on a particular set of
@@ -2585,23 +2501,7 @@ failure.
 The optional bugid, used to tie this test case to a bug tracking system.
 @end table
 
-@node record_test procedure, pass procedure, setup_xfail procedure, Core Internal Procedures
-@subsubsection record_test Procedure
-
-
-@quotation
-@t{@b{record_test}@{@i{type}
-@i{message}
-@i{args}@}}
-@end quotation
-
-@table @asis
-@item @code{type}
-@item @code{message}
-@item @code{args}
-@end table
-
-@node pass procedure, fail procedure, record_test procedure, Core Internal Procedures
+@node pass procedure, fail procedure, setup_xfail procedure, Core Internal Procedures
 @subsubsection pass Procedure
 
 Declares a test to have passed. @code{pass} writes in the log files a
@@ -2609,14 +2509,13 @@ message beginning with @emph{PASS} (or @emph{XPASS}, if failure was
 expected), appending the argument @code{string}.
 
 @quotation
-@t{@b{pass}@{@i{string}@}}
+@t{@b{pass} @{ @i{message} @}}
 @end quotation
 
 @table @asis
 
-@item @code{string}
-The string to use for this PASS
-message.
+@item @code{message}
+The message to use in the PASS result.
 @end table
 
 @node fail procedure, xpass procedure, pass procedure, Core Internal Procedures
@@ -2627,33 +2526,29 @@ message beginning with @emph{FAIL} (or @emph{XFAIL}, if failure was
 expected), appending the argument @code{string}.
 
 @quotation
-@t{@b{fail}@{@i{string}@}}
+@t{@b{fail} @{ @i{message} @}}
 @end quotation
 
 @table @asis
-
 @item @code{string}
-The string to use for this FAIL
-message.
+The message to use in the FAIL result.
 @end table
 
 @node xpass procedure, xfail procedure, fail procedure, Core Internal Procedures
 @subsubsection xpass Procedure
 
-Declares a test to have unexpectedly passed, when it was expected to be
-a failure.  @code{xpass} writes in the log files a message beginning
-with @emph{XPASS} (or @emph{XFAIL}, if failure was expected), appending
-the argument @code{string}.
+Declares a test to have passed when it was expected to fail.
+@code{xpass} writes in the log files a message beginning with
+@emph{XPASS} (or @emph{XFAIL}, if failure was expected), appending the
+argument @code{string}.
 
 @quotation
-@t{@b{xpass}@{@i{string}@}}
+@t{@b{xpass} @{ @i{message} @}}
 @end quotation
 
 @table @asis
-
-@item @code{string}
-The string to use for this output
-state.
+@item @code{message}
+The message to use in the XPASS result.
 @end table
 
 @node xfail procedure, set_warning_threshold procedure, xpass procedure, Core Internal Procedures
@@ -2661,19 +2556,12 @@ state.
 
 Declares a test to have expectedly failed. @code{xfail} writes in the
 log files a message beginning with @emph{XFAIL} (or @emph{PASS}, if
-success was expected), appending the argument @code{string}.
+success was expected), appending the @code{message} argument.
 
 @quotation
-@t{@b{xpass}@{@i{string}@}}
+@t{@b{xpass} @{ @i{message} @}}
 @end quotation
 
-@table @asis
-
-@item @code{string}
-The string to use for this output
-state.
-@end table
-
 @node set_warning_threshold procedure, get_warning_threshold procedure, xfail procedure, Core Internal Procedures
 @subsubsection set_warning_threshold Procedure
 
@@ -2723,14 +2611,13 @@ outcome doesn't become @emph{UNRESOLVED}. This can be used for errors
 with no known side effects.
 
 @quotation
-@t{@b{warning}@{@i{string}
-@i{number}
-@}}
+@t{@b{warning} @{ @i{messsage} @i{number} @}}
 @end quotation
 
 @table @asis
 
-@item @code{string}
+@item @code{message}
+The warning message.
 
 @item @code{number}
 The optional number to set the error counter. This is only used to fake
@@ -2755,14 +2642,12 @@ function, and the following test outcome doesn't become
 effects.
 
 @quotation
-@t{@b{perror}@{@i{string}
-@i{number}
-@}}
+@t{@b{perror} @{ @i{message} @i{number} @}}
 @end quotation
 
 @table @asis
-
-@item @code{string}
+@item @code{message}
+The message to be logged.
 
 @item @code{number}
 The optional number to set the error counter. This is only used to fake
@@ -2781,7 +2666,7 @@ needed in the log file regardless of the verbosity level use
 @code{note}.
 
 @quotation
-@t{@b{note}@{@i{string}@}}
+@t{@b{note} @{ @i{string} @}}
 @end quotation
 
 @table @asis
@@ -2799,14 +2684,12 @@ message beginning with @emph{UNTESTED}, appending the argument
 only role is to record that a test does not yet exist for some feature.
 
 @quotation
-@t{@b{untested}@{@i{string}@}}
+@t{@b{untested} @{ @i{message} @}}
 @end quotation
 
 @table @asis
-
-@item @code{string}
-The string to use for this output
-state.
+@item @code{message}
+The message to use.
 @end table
 
 @node unresolved procedure, unsupported procedure, untested procedure, Core Internal Procedures
@@ -2819,17 +2702,15 @@ as expected, and a human being must go over results to determine if it
 passed or failed (and to improve the test case).
 
 @quotation
-@t{@b{unresolved}@{@i{string}@}}
+@t{@b{unresolved} @{ @i{message} @}}
 @end quotation
 
 @table @asis
-
 @item @code{string}
-The string to use for this output
-state.
+The message to use.
 @end table
 
-@node unsupported procedure, init_testcounts procedure, unresolved procedure, Core Internal Procedures
+@node unsupported procedure, transform procedure, unresolved procedure, Core Internal Procedures
 @subsubsection unsupported Procedure
 
 Declares that a test case depends on some facility that does not
@@ -2838,41 +2719,15 @@ writes in the log file a message beginning with
 @emph{UNSUPPORTED}, appending the argument string.
 
 @quotation
-@t{@b{unsupported}@{@i{string}@}}
-@end quotation
-
-@table @asis
-
-@item @code{string}
-The string to use for this output
-state.
-@end table
-
-@node init_testcounts procedure, incr_count procedure, unsupported procedure, Core Internal Procedures
-@subsubsection init_testcounts Procedure
-
-
-@quotation
-@t{@b{init_testcounts}}
-@end quotation
-
-@node incr_count procedure, transform procedure, init_testcounts procedure, Core Internal Procedures
-@subsubsection incr_count Procedure
-
-
-@quotation
-@t{@b{incr_count}@{@i{name}
-@i{args}@}}
+@t{@b{unsupported} @{ @i{message} @}}
 @end quotation
-
 @table @asis
 
-@item @code{name}
-
-@item @code{args}
+@item @code{message}
+The message to use.
 @end table
 
-@node transform procedure, check_conditional_xfail procedure, incr_count procedure, Core Internal Procedures
+@node transform procedure, check_conditional_xfail procedure, unsupported procedure, Core Internal Procedures
 @subsubsection transform Procedure
 
 Generates a string for the name of a tool as it was configured and
@@ -2990,15 +2845,15 @@ The configuration triplets to clear.
 @subsubsection verbose Procedure
 
 Test cases can use this function to issue helpful messages depending on
-the number of @code{--verbose} options on the runtest command line.  It
-prints string if the value of the variable @code{verbose} is higher than
-or equal to the optional number. The default value for number is
-@emph{1}.  Use the optional @code{-log} argument to cause string to
-always be added to the log file, even if it won't be printed.  Use the
-optional @code{-x} argument to log the test results into a parsable XML
-file.  Use the optional @code{-n} argument to print string without a
-trailing newline.  Use the optional @code{--} argument if string begins
-with "-".
+the number of @code{-v}/@code{--verbose} options passed to runtest on
+the command line.  It prints @i{string} if the value of the variable
+@code{verbose} is higher than or equal to the optional @i{loglevel}. The
+default log level is 1.  Use the optional @code{-log} argument to cause
+string to always be added to the log file, even if it won't be printed.
+Use the optional @code{-x} argument to log the test results into a
+parsable XML file.  Use the optional @code{-n} argument to print string
+without a trailing newline.  Use the optional @code{--} argument if
+string begins with "-".
 
 @quotation
 @t{@b{verbose}@{@i{-log}
@@ -3006,7 +2861,7 @@ with "-".
 @i{-n}
 @i{-r}
 @i{string}
-@i{number}@}}
+@i{loglevel}@}}
 @end quotation
 
 @table @asis
@@ -4338,6 +4193,7 @@ This is the filename to download.
 @node reboot_target procedure, target_assemble procedure, push_config procedure, Procedures For Target Boards
 @subsubsection reboot_target Procedure
 
+Reboot the target.
 
 @quotation
 @t{@b{reboot_target}}
@@ -4700,7 +4556,7 @@ was a communication error.
 Starts a particular tool.  For an interactive tool,
 @code{$@{tool@}_start} starts and initializes the tool, leaving the tool
 up and running for the test cases; an example is @code{gdb_start}, the
-start function for GDB. For a batch oriented tool,
+start function for GDB. For a batch-oriented tool,
 @code{$@{tool@}_start} is optional; the recommended convention is to let
 @code{$@{tool@}_start} run the tool, leaving the output in a variable
 called @code{comp_output}.  Test scripts can then analyze
@@ -4723,7 +4579,7 @@ tool).
 
 Loads something into a tool. For an interactive tool, this conditions
 the tool for a particular test case; for example, @code{gdb_load} loads
-a new executable file into the debugger. For batch oriented tools,
+a new executable file into the debugger. For batch-oriented tools,
 @code{$@{tool@}_load} may do nothing---though, for example, the GCC
 support uses @code{gcc_load} to load and run a binary on the target
 environment.  Conventionally, @code{$@{tool@}_load} leaves the output of
@@ -4941,8 +4797,7 @@ The second file to compare.
 @node setenv procedure, unsetenv procedure, diff procedure, Utility Procedures
 @subsubsection setenv Procedure
 
-Sets the environment variable @emph{var} to the
-value @emph{val}.
+Sets the environment variable @emph{var} to the value @emph{val}.
 
 @quotation
 @t{@b{setenv}@{@i{var}
@@ -4971,8 +4826,7 @@ Unsets the environment variable
 @table @asis
 
 @item @code{var}
-The environment variable to
-unset.
+The environment variable to unset.
 @end table
 
 @node getenv procedure, prune_system_crud procedure, unsetenv procedure, Utility Procedures
@@ -5009,12 +4863,10 @@ date.
 @table @asis
 
 @item @code{system}
-The system error messages to look for to screen out
-.
+The system error messages to look for to screen out.
 
 @item @code{text}
-The Tcl variable containing the
-text.
+The Tcl variable containing the text.
 @end table
 
 @node Libgloss, Debugging Procedures, Utility Procedures, Builtin Procedures