cgal/Packages/Manual

========================================================================
Contents of the directory
========================================================================

This directory contains:
   README               -- this file
   demo                 -- link to the current release's demo directory
                           (needed for inclusion of demo programs in doc and
                            created by install_manual_files)
   doc_tex_skel/        -- directory containing the "skeleton" of the tex manual
                           (i.e., those files not submitted with packages but 
                            needed to create the manual)
   examples             -- link to the current release's examples directory
                           (needed for inclusion of example programs in doc and
                            created by install_manual_files)
   INSTALL              -- directions for how to INSTALL this package in order
                           to create the manuals and run the tests
   scripts/             -- directory of scripts used for creating the manual
   web_pages/           -- directory containing the extra files needed for
                           the manual on the web site.

========================================================================
How to run the test suite:
========================================================================

In this directory (or some other directory in which you have created a 
copy of the directory doc_tex_skel) you can simply type

   % autotest_cgal_manual <version>

where <version> is something like CGAL-2.3-I-90.  This will autotmatically
install a doc_tex directory (from the $SOURCE_DIR set in install_manual_files) 
for this release in this directory, run the test, collect the results and send 
mail to cgal-develop when it is done.

The test page created is
   $(TEST_DESTINATION)/<version>.manual_test.html
(and  $(TEST_DESTINATION)/index.html is a copy of this)

In addition, the page
   $(TEST_DESTINATION)/($TEST_SUBDIR)/html/gif_grep_list.html
is created, which contains a listing of the results of the gif_grep
script run by the test script.  Follow the links on this page to see
the grep results.  Though it doesn't catch all problems, it can show 
you if some gif files are missing from the html manual.

========================================================================
Running the test suite manually:
========================================================================

In this directory (or some other directory in which you have created a 
directory doc_tex_skel containing the files not submitted with packages but 
necessary to create the whole manual) type

   % install_manual_files <version_num>

where <version_num> is something like 2.1-I-17.  This will create a
directory called CGAL-<version_num>_doc_tex and copy from 

   $SOURCE_DIR

(set in install_manual_files) the .tex files submitted with the indicated 
release and copy from doc_tex_skel the necessary extra files to create the 
proper directory structure.  This should alert you to new manual 
subdirectories or missing subdirectories so you can edit the appropriate 
docdirs files if necessary.  

Then go to the directory created

   % cd CGAL-<version_num>_doc_tex

To run the test suite do

    % make test

This creates the log files for all various programs and parts of the
manual and then generates an HTML document in the current directory
with the name CGAL-<version_num>.manual_test.html.

To install the test suite results in the location indicated by the
TEST_DESTINATION and TEST_SUBDIR variables, use

    % make install_test

This copies the HTML document created by 'make test' to TEST_DESTINATION
and copies the log files, .ps.gz files, and .html files to 
TEST_DESTINATION/TEST_SUBDIR

========================================================================
How to create a release manual: 
========================================================================
If the manual files were installed from an internal release, you will
probably need to change the \cgalrelease command in the */wrapper.tex files
to correspond to the current release number.  Also,  modify the VERSION_NUM
variable in the makefile.

To create a version of the manual do

    % make 

This calls the script "driver", which creates postscript and html manuals
for all subdirectories.  It also calls the to_pdf script to create the PDF
versions.  

To install the manual you can do

    % make install_all

This will do the same thing as the following three commands.

1) To install the manual files in $(DESTINATION) and also the include files 
   and the frames for the manual do.

    % make install

2) To create the tar files for documentation downloading, do

    % make pack

   This should be done *AFTER* a 'make install' as it packs the versions that
   are installed with this command.  This copies the .tar.gz and .zip files to
   $(DOC_DOWNLOAD_DIR)

3)  To compress the individual .ps files located in $(DOC_PS_DESTINATION), do 

    % make dest_zip_ps

If you want to update the manual for only a certain subdiriectory, 
then use

    % make <directory>_update

This does *not* update the files in $(DOC_DOWNLOAD_DIR).