$Id: README 5191 2013-02-23 00:11:18Z karl $ 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 * 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.