Merge branch 'peppe/common_test_r14_dev_2' into dev

* peppe/common_test_r14_dev_2:
  Misc documentation updates
  Add documentation for run_test program
  Step vsn for test_server to 3.4
  Make {repeat*,N} property in group execute the group N times exactly
  Fix so that ct_run converts relative diretories in the code path to absolute
  Fix bug in handling framework:end_tc timeouts
  Fix bug that prevents the interactive shell mode to start properly
  Fix failing multiply timetrap test case
  Minor fixes in code and test suites
  Add support for executing pre-loaded suites (e.g. modules loaded as binaries)
  Add test suite for remote loading of binary suites
  Fix error with {repeat,0} property in groups causing double iterations
  Add support for config info functions (e.g. init_per_suite/0)
  Add support for dynamic timetrap handling
  Have end_per_testcase run even after timetrap_timeout and abort_testcase
  Flush old DOWN messages in demonitor
  Add groups in test specifications
  Add new tests for test case groups and test specifications
  Improve and fix various test suites
  Add event_handler_init start flag that can pass init arguments to event handlers
  ...

OTP-8703 peppe/common_test_r14_dev_2

1 files changed, 67 insertions, 72 deletions

diff --git a/lib/common_test/doc/src/install_chapter.xml b/lib/common_test/doc/src/install_chapter.xml
index e1ff5abf6a..828588a673 100644
--- a/lib/common_test/doc/src/install_chapter.xml
+++ b/lib/common_test/doc/src/install_chapter.xml
@@ -4,7 +4,7 @@
 <chapter>
   <header>
     <copyright>
-      <year>2007</year><year>2009</year>
+      <year>2007</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>Installation</title>
@@ -33,82 +33,77 @@
     <marker id="general"></marker>
     <title>General information</title>
 
-    <p>The two main interfaces for running tests with Common Test 
-    are an executable Bourne shell script named <c>run_test</c> and an
-    erlang module named <c>ct</c>. The shell script will work on Unix/Linux
-    (and Linux-like environments such as Cygwin on Windows) and the
-    <c>ct</c> interface functions can be called from the Erlang shell
-    (or from any Erlang function) on any supported platform.</p>
-    
-    <p>The Common Test application is installed with the Erlang/OTP
-    system and no explicit installation is required to start using
-    Common Test by means of the interface functions in the <c>ct</c>
-    module. If you wish to use <c>run_test</c>, however, this script
-    needs to be generated first, according to the instructions below.</p>
-    </section>
+    <p>The two main interfaces for running tests with Common Test
+      are an executable program named run_test and an
+      erlang module named <c>ct</c>. The run_test program
+      is compiled for the underlying operating system (e.g. Unix/Linux
+      or Windows) during the build of the Erlang/OTP system, and is
+      installed automatically with other executable programs in
+      the top level <c>bin</c> directory of Erlang/OTP.
+      The <c>ct</c> interface functions can be called from the Erlang shell,
+      or from any Erlang function, on any supported platform.</p>
+
+    <p>A legacy Bourne shell script - also named run_test - exists,
+      which may be manually generated and installed. This script may be used
+      instead of the run_test program mentioned above, e.g. if the user
+      wishes to modify or customize the Common Test start flags in a simpler
+      way than making changes to the run_test C program.</p>
 
-  <section>
-    <title>Unix/Linux</title>
-
-    <p>Go to the <c><![CDATA[common_test-<vsn>]]></c> directory, located
-    among the other OTP applications (under the OTP lib directory). Here you
-    execute the <c>install.sh</c> script with argument <c>local</c>:</p>
-
-    <p><c> 
-    $ ./install.sh local 
-    </c></p>    
+    <p>The Common Test application is installed with the Erlang/OTP
+      system and no additional installation step is required to start using
+      Common Test by means of the run_test executable program, and/or the interface
+      functions in the <c>ct</c> module. If you wish to use the legacy Bourne
+      shell script version of run_test, however, this script needs to be
+      generated first, according to the instructions below.</p>
+
+    <p><note>Before reading on, please note that since Common Test version
+	1.5, the run_test shell script is no longer required for starting
+	tests with Common Test from the OS command line. The run_test
+	program (descibed above) is the new recommended command line interface
+	for Common Test. The shell script exists mainly for legacy reasons and
+	may not be updated in future releases of Common Test. It may even be removed.
+    </note></p>
+
+    <p>Optional step to generate a shell script for starting Common Test:</p>
+    <p>To generate the run_test shell script, navigate to the
+      <c><![CDATA[common_test-<vsn>]]></c> directory, located among the other
+      OTP applications (under the OTP lib directory). Here execute the
+      <c>install.sh</c> script with argument <c>local</c>:</p>
+
+    <p><c>
+	$ ./install.sh local
+    </c></p>
     
-    <p>This generates the executable <c>run_test</c> script in the 
-    <c><![CDATA[common_test-<vsn>/priv/bin]]></c> directory. The script
-    will include absolute paths to the Common Test and Test Server
-    application directories, so it's possible to copy or move the script to
-    a different location on the file system, if desired, without having to
-    update it. It's of course possible to leave the script under the
-    <c>priv/bin</c> directory and update the PATH variable accordingly (or
-    create a link or alias to it).</p>
-
-    <p>If you, for any reason, have copied Common Test and Test Server 
-    to a different location than the default OTP lib directory, you can
-    generate a <c>run_test</c> script with a different top level directory, 
-    simply by specifying the directory, instead of <c>local</c>, when running
-    <c>install.sh</c>. Example:</p>
-
-    <p><c> 
-    $ install.sh /usr/local/test_tools
+    <p>This generates the executable run_test script in the
+      <c><![CDATA[common_test-<vsn>/priv/bin]]></c> directory. The script
+      will include absolute paths to the Common Test and Test Server
+      application directories, so it's possible to copy or move the script to
+      a different location on the file system, if desired, without having to
+      update it. It's of course possible to leave the script under the
+      <c>priv/bin</c> directory and update the PATH variable accordingly (or
+      create a link or alias to it).</p>
+
+    <p>If you, for any reason, have copied Common Test and Test Server
+      to a different location than the default OTP lib directory, you can
+      generate a run_test script with a different top level directory,
+      simply by specifying the directory, instead of <c>local</c>, when running
+      <c>install.sh</c>. Example:</p>
+
+    <p><c>
+	$ install.sh /usr/local/test_tools
     </c></p>
 
     <p>Note that the <c><![CDATA[common_test-<vsn>]]></c> and
-    <c><![CDATA[test_server-<vsn>]]></c> directories must be located under the
-    same top directory. Note also that the install script does not copy files 
-    or update environment variables. It only generates the <c>run_test</c> 
-    script.</p> 
+      <c><![CDATA[test_server-<vsn>]]></c> directories must be located under the
+      same top directory. Note also that the install script does not copy files
+      or update environment variables. It only generates the run_test
+      script.</p>
     
-    <p>Whenever you install a new version of Erlang/OTP, the <c>run_test</c>
-    script needs to be regenerated, or updated manually with new directory names
-    (new version numbers), for it to "see" the latest Common Test and Test Server
-    versions.</p>
+    <p>Whenever you install a new version of Erlang/OTP, the run_test
+      script needs to be regenerated, or updated manually with new directory names
+      (new version numbers), for it to "see" the latest Common Test and Test Server
+      versions.</p>
 
-    <p>For more information on the <c>run_test</c> script and the <c>ct</c>
-    module, please see the reference manual.</p>
-    </section>
-
-  <section>
-    <title>Windows</title>
-
-    <p>On Windows it is very convenient to use Cygwin (<c>www.cygwin.com</c>)
-    for running Common Test and Erlang, since it enables you to use the
-    <c>run_test</c> script for starting Common Test. If you are a Cygwin
-    user, simply follow the instructions above for generating the <c>run_test</c>
-    script.</p>
-
-    <p>If you do not use Cygwin, you have to rely on the API functions
-    in the <c>ct</c> module (instead of <c>run_test</c>) for running
-    Common Test as described initially in this chapter.</p>
-
-    <p>If you, for any reason, have chosen to store Common Test and Test Server 
-    in a different location than the default OTP lib directory, make 
-    sure the <c>ebin</c> directories of these applications are included 
-    in the Erlang code server path (so the application modules can be loaded).</p>
     </section>
 </chapter>