#############################################################################
##
#W  README            README for GAP manual test files         Volkmar Felsch
##
#H  $Id: README,v 1.5.2.3 2007/09/18 09:19:15 gap Exp $
##
#Y  Copyright (C) 2002, Lehrstuhl D fuer Mathematik, RWTH Aachen, Germany
##
#############################################################################

(1) The scripts 'mktest.sh' and 'mkdiff.sh' in the 'gap/doc/test' directory
    are tools to test the GAP manual examples.

(2) You can, for instance, run a test over all GAP manual examples by
    just calling

          cd ref  (to get to the directory 'gap/doc/test/ref')
          ../mktest.sh -p ../../ref/
          ../mkdiff.sh -p ../../ref/

    'mktest.sh' produces for each manual file 'gap/doc/ref/<file>.tex' a test
    file '<file>.tst' (in your present working directory 'gap/doc/test/ref')
    which is essentially a copy of the given manual file, but updated with
    respect to the results of the examples,

    'mkdiff.sh' produces a file 'diffs' which provides a list of all
    differences between the manual files and the corresponding test files.

(3) You may use the options -i, -o, or -d to get, in addition, for each
    manual file 'gap/doc/ref/<file>.tex' the corresponding GAP input file
    '<file>.in', the output file '<file>.out', or a file '<file>.dif' which
    lists all diffences between that particular manual file and its test
    file.

    Note that all files created by 'mktest.sh' or 'mkdiff.sh' are in your
    present working directory 'gap/doc/test/ref'.
    The files in the manual directory 'gap/doc/ref' are not affected.

(4) If you do not want to check all manual files but only a few of them you
    may save time by specifying these files in the call.

          cd ref
          ../mktest.sh -p ../../ref/ -i groups grpfp grphomom
          ../mkdiff.sh groups grpfp grphomom
          ../mkdiff.sh -c groups

(5) If you do not specify any files when calling 'mktest.sh', it will work off
    all '.tex' files that are available in the manual directory
    'gap/doc/ref'. This does not make sense for some of these files (e.g. for
    files like 'manual.tex' or 'refcover.tex'), but it does not do any harm.
    The advantage of this convention is that one cannot miss to handle any
    relevant manual files.

(6) If you do not specify any files when calling 'mkdiff.sh', it will work off
    all '.tst' files that are available in your present working directory
    'gap/doc/test/ref'.

(7) If you specify the option -c in the call of 'mktest.sh' or 'mkdiff.sh' the
    resulting lists of differences will be created by using the context
    format of the 'diff' command.

(8) The above remarks concerning the 'ref' directories apply quite
    analogously to the 'ext', 'new', 'prg', or 'tut' directories.

(9) In general, 'mktest.sh' runs all examples given in the form

          \beginexample
          ...
          \endexample

    However, it ignores all those examples which are immediately preceded by
    a special Latex comment line:

          %notest
          \beginexample
          ...
          \endexample

    You may enforce 'mktest.sh' to run a full test over all examples including
    the "no test" examples by specifying the option -f.

          cd ref
          ../mktest.sh -f mloop
          ../mkdiff.sh mloop

(10) In some packages the test is applied to XML files (with suffix '.xml')
     instead of TeX files (see the documentation of the package RCWA for an
     example). In these files the ordinary examples are expected to have the
     form

          <Example>
          ...
          </Example>

     and the "no test" examples to have the form

          <Log>
          ...
          </Log>

(11) The general format of the calls is

          mktest.sh [-f] [-i] [-o] [-d] [-c] [file1 file2 ...]
     and
          mkdiff.sh [-c] [file1 file2 ...]

#############################################################################