texinfo/texi2html/test/README

$Id$
texinfo/texi2html/tests/README

  Copyright (C) 2010 Free Software Foundation, Inc.

  Copying and distribution of this README file, with or without
  modification, are permitted in any medium without royalty provided the
  copyright notice and this notice are preserved.

Files anywhere within the test/ subdirectory which have no other
copyright notice are hereby placed in the public domain.


Test results are not in CVS.  To download them, you need wget.  To get the
archives, and then unpack them, run
  ./manage_test_archives.sh get
  ./manage_test_archives.sh unpack

To clean up archives and download directory, run
  ./manage_test_archives.sh clean

To run the tests, it should be necessary to configure and build texi2html.
To do that, in the texi2html directory, run
  autoreconf && ./configure && make


Prerequisites
=============
To run this testsuite, sed (with -i), awk, diff, mktemp are used. To 
find the same results, tex4ht, latex2HTML, html2wiki, perl with unicode 
support and the Text::Unidecode perl module have to be installed (with their 
dependencies).  It is possible that some test results involving latex2HTML,
tex4ht or html2wiki depend on the setup and version of these tools, so you may 
get false negative.  If tex4ht, latex2HTML or html2wiki are not found, the 
corresponding tests are skipped.

Some tests also require a case insensitive filesystem (especially in 
encodings/).


Running the testsuite
=====================
This testsuite can be run 

* using the makefile rules: check for the base tests, long-check for 
  the long tests, or all-checks for both.

* using ./tests.sh with the list of directories in argument one want to
  run the tests in. In general you should give all as first tests.sh
  argument, like
./tests.sh all <directories...>

* by going in one directory and running ../run_test_all.sh, like
$ cd formatting
$ ../run_test_all.sh
* by going in one directory and running one specific test, like
$ cd formatting
$ ../run_test_all.sh quotes
(see below for info on how test names are specified).

The test results are in the out directories; the reference results are
in res directories; there are 3 out and res directories, out/ and res/
for the html results in the texi2html style, out_info and res_info
for the info output a la makeinfo and out_all and res_all 
for the texi2any output. diffs are put in diffs. 

If a test failed,
 F: a_test_directory 
is printed, if there is a diff with the references, a
 D: a_test_directory
is printed. If there are no reference to compare with, 
 no res: a_test_directory
is printed.

If a whole directory check run using './tests.sh all' had no failure, 
the directory name is printed followed by a 0; it is followed 
by a 1 if there was a failure.

The test results are in a directory below the out directories. This 
directory name can be considered as the test name. Let's call it a_test
for the remaining of the explanation. The stderr output is in 
out/a_test/a_test.2, stdout output is in out/a_test/a_test.1. All 
the commands called are output in tests.log.

giving -copy in argument to tests.sh all or ../run_test_all.sh will 
cause the references to be regenerated. This can also be achieved with 
the copy-tests make target.


Tests specification
===================
Test runs are driven by the content of the tests.txt file. It is a line
oriented file. A # starts a comment. Each line describes a test.  The
first word on the line is the test name which corresponds also with the
resulting directory (what we called a_test above).  It is followed by
the source manual name. The source manual name has to have the .texi
extension. Optionnally additional arguments can be given on the
remaining of the line.

So, for example, the line

a_test manual.texi

specifies that for the a_test test, the file manual.texi is processed and
results are put are put in the a_test directory.  The line:

a_test_split_chapter manual.texi --split chapter

specifies that the results of the processing of manual.texi with additional
command line arguments --split chapter will be in the a_test_split_chapter
directory.

Using "texi" as the test name is special. In that case the directory name 
is constructed by appending _ followed by the manual name without the .texi
extension to "texi". And the result is not processed normally, but instead
macros are expanded and regions that are not processed removed and the 
result is put in a file with the same name than the manual. Similar result 
files but with include file, macro and line number informations are put in 
files with the .texi extension replaced by .passtexi and .passfirst. More
precisely, the .passtexi file corresponds with the texi after the first 
pass and the .passfirst file corresponds with the result after the second 
pass.

So, for example, the tests.txt line 

texi manual.texi

results in the following: in the directory out/texi_manual the file
manual.texi will have macros expanded and ignored regions removed, and
the files manual.passtexi and manual.passfirst will contain the
additional include file and line number informations corresponding with
the texinfo at the end of the first and second pass.


LaTeX2html
==========
For the tests that use latex2html, to avoid the test failing if there is 
a dot in the cwd, mktemp is used to create a temporary directory, hopefully
in /tmp, and the directory is passed through on the command line.


Common .texi
============
A common .texi file should be in the top-level directory (there is such an
example with coverage_macro.texi). Currently there is no support for common
init file, but it could be added easily.