This branch is now closed. The documentation has been moved to XMLorigin/dejagnu_doc_branch

format on the trunk, so the changes on this branch will be merged
forward and a new documentation branch will be created.

	* doc/overview.sgml: More editorial changes.
	* doc/user.sgml: Likewise.

3 files changed, 79 insertions, 103 deletions

diff --git a/ChangeLog b/ChangeLog
index e350872..ee11265 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2004-02-17  Ben Elliston  <bje@wasabisystems.com>
+
+	This branch is now closed.  The documentation has been moved to
+	XML format on the trunk, so the changes on this branch will be
+	merged forward and a new documentation branch will be created.
+
+2004-02-17  Ben Elliston  <bje@wasabisystems.com>
+
+	* doc/overview.sgml: More editorial changes.
+	* doc/user.sgml: Likewise.
+
 2004-02-04  Ben Elliston  <bje@wasabisystems.com>
 
 	* doc/overview.sgml (revhistory): Update.
diff --git a/doc/overview.sgml b/doc/overview.sgml
index 5ca5e2d..9808aa1 100644
--- a/doc/overview.sgml
+++ b/doc/overview.sgml
@@ -76,6 +76,10 @@ into another language, under the above conditions for modified versions.
         <firstname>Ben Elliston</firstname>
         <affiliation><orgname>Free Software Foundation</orgname></affiliation>
       </author>
+
+      <author>
+        <firstname>Lisa Elliston</firstname>
+      </author>
     </authorgroup>
     <address>
       <email>rob@welcomehome.org</email>
@@ -145,9 +149,9 @@ into another language, under the above conditions for modified versions.
     <sect1 id=whatis xreflabel="What is &dj;?">
       <title>What is &dj;?</title>
 
-    <para><productname>&dj;</productname> is a framework for
-	testing other programs.  Its purpose is to provide a uniform
-	testing environment. Think of it as a library of
+    <para><productname>&dj;</productname> is a framework for testing
+	other programs.  Its purpose is to provide a uniform testing
+	environment. Think of it as a library of
 	<productname>Tcl</productname> procedures to support writing a
 	test harness. A <emphasis>test harness</emphasis> is the
 	testing infrastructure created to support a specific
@@ -156,17 +160,15 @@ into another language, under the above conditions for modified versions.
 	<productname>Expect</productname>, which in turn relies upon
 	<productname>Tcl</productname>. More information on
 	<productname>Tcl</productname> and
-	<productname>Expect</productname> can be found at the <ulink
-	URL="http://www.tcltk.com">Tcl/Tk web site</ulink> and the
-	<ulink URL="http://expect.nist.gov">Expect home page</ulink>,
-	respectively.</para>
+	<productname>Expect</productname> can be found in <xref
+	linkend=appendix>.</para>
 	
    <para>Julia Menapace first coined the term ``&dj;'' to describe an
         earlier testing framework she had written at Cygnus Support
         for testing <command>GDB</command>. When it was replaced it
         with the Expect-based framework, it was like &dj; all over
         again.  More importantly, it was also named after Deja Snow
-        Savoye (13 years old as of September 2003), who was a toddler
+        Savoye (13 years old in September 2003), who was a toddler
         during &dj;'s beginnings.</para>
 
     <para>There are several advantages to testing with &dj;:</para>
@@ -210,7 +212,8 @@ into another language, under the above conditions for modified versions.
     not based on
     <productname>Expect</productname>. <productname>Expect</productname>
     scripts use <emphasis>.exp</emphasis> as a filename extension as a
-    convention.</para>
+    convention.  Testsuites are typically kept in the source tree of
+    the programs that they test.</para>
 	
   </sect1>
   <sect1 id=new xreflabel="Release Notes">
@@ -269,10 +272,10 @@ into another language, under the above conditions for modified versions.
   <sect1 id=designgoals xreflabel="Design Goals">
     <title>Design Goals</title>
 
-    <para>&dj; grew out of the internal needs of Cygnus Solutions,
-    the company formerly known as Cygnus Support. Cygnus maintained
-    and enhanced a variety of free programs in many different
-    environments.  A testing tool was needed that:</para>
+    <para>&dj; grew out of the needs of Cygnus Solutions, the company
+    formerly known as Cygnus Support. Cygnus maintained and enhanced a
+    variety of free programs in many different environments.  A
+    testing tool was needed that:</para>
 
     <itemizedlist mark="bullet">
       <listitem><para>was useful to developers while fixing
@@ -299,10 +302,10 @@ into another language, under the above conditions for modified versions.
     <para>Probably the greatest challenge was testing in a
     cross-development environment.  Most cross-development
     environments are customized by each developer.  Even when buying
-    packaged boards from vendors there are many differences.  The
+    packaged evaluation boards there are many differences.  The
     communication interfaces vary from a serial line to Ethernet.
-    &dj; was designed with a modular communication setup, so that
-    each mode of communication can be added as required and supported
+    &dj; was designed with a modular communication setup, so that each
+    mode of communication can be added as required and supported
     thereafter.  Once a communication procedure is implemented, any
     testsuite can use it.  Currently &dj; can use
     <command>rsh</command>, <command>rlogin</command>,
@@ -475,93 +478,54 @@ into another language, under the above conditions for modified versions.
   <sect1 id=installation xreflabel="Installation">
     <title>Installation</title>
 
-    <para>Once you have the DejaGnu source unpacked and available, you must
-    first configure the software to specify where it is to run (and the
-    associated defaults); then you can proceed to installing it.</para>
+    <para>Once you have obtained the DejaGnu source archive and
+    unpacked it, you must configure the package to specify where it is
+    to be installed.  You may then proceed with installing it.</para>
 
     <sect2 id=configuring xreflabel="Configuring DejaGnu">
       <title>Configuring DejaGnu</title>
 
-      <para>It is usually best to configure in a directory separate from the
-      source tree, specifying where to find the source with the optional
-      <emphasis>--srcdir</emphasis> option to
-      <emphasis>configure</emphasis>. DejaGnu uses the GNU
-      <emphasis>autoconf</emphasis> to configure itself. For more info on using
-      autoconf, read the GNU autoconf manual. To configure, execute the
-      <filename>configure</filename> program, no other options are
-      required. For an example, to configure in a seperate tree for objects,
-      execute the configure script from the source tree like this:</para>
+      <para>It is usually best to configure &dj; in a different
+      directory than the source tree. To configure from a sibling
+      build directory, execute the <filename>configure</filename>
+      script from the source tree like this:</para>
 
       <screen>
         ../dejagnu-&version/configure
       </screen>
 
-      <para>DejaGnu doesn't care at config time if it's for testing a native
-      system or a cross system. That is determined at runtime by using the
-      config files.</para>
+      <para>DejaGnu doesn't distinguish when installed whether it will
+      be testing programs on a native system or a remote system. That
+      is determined at runtime via its own configuration files.</para>
 
-      <para>You may also want to use the <command>configure</command> option
-      <emphasis>--prefix</emphasis> to specify where you want DejaGnu and its
-      supporting code installed.  By default, installation is in subdirectories
-      of <filename>/usr/local</filename>, but you can select any alternate
-      directory <symbol>altdir</symbol> by including
+      <para>You may wish to use the <command>configure</command>
+      option <emphasis>--prefix</emphasis> to specify where you want
+      DejaGnu installed.  The default installation prefix is under
+      <filename>/usr/local</filename>, but you can select any
+      alternate directory <symbol>altdir</symbol> by including
       <option>--prefix</option>{altdir}} on the
-      <command>configure</command> command line. (This value is captured in
-      the Makefile variables <emphasis>prefix</emphasis> and
-      <emphasis>exec</emphasis>prefix}.)</para>
-
-      <para>Save for a small number of example tests, the DejaGnu distribution
-      itself does not include any testsuites; these are available
-      separately. Testsuites for the GNU development tools are included in
-      those releases. After configuring the top-level DejaGnu directory, unpack
-      and configure the test directories for the tools you want to test; then,
-      in each test directory, run <emphasis>make check</emphasis> to build
-      auxiliary programs required by some of the tests, and run the test
-      suites.</para>
+      <command>configure</command> command line.</para>
 
-    </sect2>
+      <para>DejaGnu includes a small testsuite of own, but it does not
+      include other testsuites; these are typically available with the
+      packages that they test.</para>
 
     <sect2 id=installing  xreflabel="Installing DejaGnu">
       <title>Installing DejaGnu</title>
 
-      <para>To install DejaGnu in your filesystem (either in
-      <filename>/usr/local</filename>, or as specified by your
-      <emphasis>--prefix</emphasis> option to <emphasis>configure</emphasis>),
-      execute.</para>
+      <para>Once a build directory is configured, installing &dj; is a
+      simple matter of running:</para>
 
       <screen>
-        eg$ make install
+        $ make install
       </screen>
 
-      <para><emphasis>make install</emphasis>does thes things for
-      DejaGnu:</para>
-
-      <itemizedlist mark=bullet>
-        <listitem><para>Look in the path specified for executables
-          <symbol>$exec_prefix</symbol>) for directories called
-          <filename>lib</filename> and <filename>bin</filename>. If these
-          directories do not exist, <emphasis>make install</emphasis> creates
-          them.</para></listitem>
-
-        <listitem><para>Create another directory in the
-        <filename>share</filename> directory, called
-        <filename>dejagnu</filename>, and copy all the library files into
-        it.</para></listitem>
-
-        <listitem><para>Create a directory in the
-        <filename>dejagnu/share</filename> directory, called
-        <filename>config</filename>, and copy all the configuration files into
-        it.</para></listitem>
-
-	<listitem><para>Copy the <emphasis>runtest</emphasis> shell script into
-	<filename>$exec_prefix/bin</filename>.</para></listitem>
-
-	<listitem><para>Copy <filename>runtest.exp</filename> into
-	<filename>$exec_prefix/lib/dejagnu</filename>. This is the main Tcl
-	code implementing DejaGnu.</para></listitem>
-
-      </itemizedlist>
-  </sect2>
+      <para>The <command>make install</command> output will show what
+      was installed where, but the most important installation step to
+      note is that the <filename>runtest</filename> command is
+      installed into the <filename>$prefix/bin</filename> directory.
+      This program is the driver for &dj;.</para>
+    </sect2>
   </sect1>
 </chapter>
 
diff --git a/doc/user.sgml b/doc/user.sgml
index c711a10..1de4c89 100644
--- a/doc/user.sgml
+++ b/doc/user.sgml
@@ -1,17 +1,17 @@
  <chapter id=runningtests>
     <title>Running Tests</title>
 
-    <para>There are two ways to execute a testsuite. The most common
-    way is to rely upon support in a <filename>Makefile</filename> for
-    a <emphasis>check</emphasis> target. The other way is to execute
-    the <command>runtest</command> program directly. To run
-    <command>runtest</command> directcly from the command line
-    requires either all the correct options, or the <xref
-    linkend=local> must be setup correctly.  Automake can generate a
-    <filename>Makefile</filename> that does all of the right things
-    when the user invokes <command>make check</command> and is the
-    preferred approach.  Both ways of executing a testsuite will be
-    covered in more detail below.</para>
+    <para>There are two ways to run a testsuite. The most common way
+    is to rely on <filename>Makefile</filename> support for a
+    <emphasis>check</emphasis> target. The other way is to invoke the
+    <command>runtest</command> program directly. To invoke
+    <command>runtest</command> from the command line requires either
+    much care to be taken to ensure that all of the correct options
+    are given or that the <xref linkend=local> is set up correctly.
+    Automake can help to produce a <filename>Makefile</filename> that
+    does the right things when the user invokes <command>make
+    check</command> and this is the preferred approach.  Both ways of
+    executing a testsuite will be covered in more detail below.</para>
 
     <sect1 id=makecheck xreflabel="Make Check">
       <title>make check</title>
@@ -746,15 +746,16 @@
 
 <chapter id=tutorial>
     <title>Tutorial</title>
-<para>This chapter was originally written by Niklaus Giger (ngiger@mus.ch) because he lost a week to figure out how DejaGnu works and how to write a first test.</para>
-
-<para>Follow these instructions as closely a possible in order get a
-good insight into how DejaGnu works, otherwise you might run into a
-lot of subtle problems.  The examples given in this chapter were run
-on an AMD K6 machine with a AMD K6 and a Mac Powerbook G3 acting as a
-remote target.  The tests for Windows were run under Windows NT using
-Cygwin. Its target system was a PowerPC embedded system running
-vxWorks.</para>
+
+<para>This chapter was originally written by Niklaus Giger
+(ngiger@mus.ch) because he lost a week to figure out how DejaGnu works
+and how to write a first test.</para>
+
+<para>This tutorial will give a brief, but sound overview into how
+DejaGnu works.  The examples given in this chapter were run on an AMD
+K6 machine with a Mac Powerbook G3 acting as a remote target.  The
+tests for Windows were run under Cygwin. Its target system was a
+PowerPC embedded system running vxWorks.</para>
 
 <sect1>
 <title>Test your installation</title>