mirror of https://github.com/CGAL/cgal
README
autotest_cgal_manual
Purpose: Shell script for automatically running the test suite for the
manuals. Copies the doc_tex files to the manual test directory
(given in the script) and then runs the test and installs the
results.
Usage: autotest_cgal_manual <CGAL-release-num>
backslash_grep
Purpose: Used to check if the html files contain any backslashes, which
often indicates a raw formatting command that didn't get
translated by the cc_manual_to_html program.
Usage: backslash_grep [d1 d2 ...]
If no argument is given, the default is to grep all html files
in the current directory and all subdirectories. Otherwise,
only the html files in subdirectories given as arguments are
searched.
bibmerge
Purpose: Perl script for merging .bib files, names of which are provided
on the command line.
Ouptut is sent to standard output and duplicate entries are
removed.
Usage: bibmerge bibfiles
clean_start
Purpose: for directories that have subdirectories (names of which are
provided in the file <subdir>/'docdirs') creates a new AllMains.tex
file and in each subdirectory named in 'docdirs' adds a link
to ./html_wrapper.
Usage: clean_start [d1 d2 ...]
If a list of directory names is provided on the command line,
only those will be "cleaned".
If directory names are not provided on the command line then
-- if the directory from which this is run contains a wrapper.tex
file, it is assumed that this directory is the one to clean
-- if the directory contains no wrapper.tex file but a docdirs
file then the directories named in the docdirs file are assumed
to be the ones to clean
-- otherwise, nothing is done
copy_log_files
Purpose: to copy the log files created from the test_html and test_tex
scripts to the location of the manual test web pages
Usage: copy_log_files <destination>
if the current directory contains no docdirs file, nothing will
be copied, otherwise the log files from all directories listed
in docdirs will be copied.
create_package_table:
Purpose: create the table entries for a part of the manual with
sub-parts (packages). Prints the output to standard output.
Usage: create_package_table [d1 d2 ...]
If directory names are provided on the command line, use these as
the directories for which test results are prepared. Otherwise,
when in a directory that contains a wrapper.tex file and a docdirs
file assume this is the directory to work in. If the current
directory contains no wrapper.tex file but a docdirs file, this
indicates that a page should be created for the test results of
all subdirectories named in docdirs.
create_test_page
Purpose: create a WWW page of test results for the manual
The name of the WWW page is composed from the version name
supplied on the command line and the suffix '.manual_test.html'
Usage: create_test_page <version_name> <target_dir>
<version_name> should be something like CGAL-2.1-I-27 and
<target_dir> should be the directory where the log files linked
from the web page will be stored.
doublenames
Purpose: Determines if there are duplicate file names in a set of
subdirectories provided either on the command line or in
the file docdirs. (??? I'm not sure why this is needed. ???)
Usage: double_names [d1 d2 ...]
driver
Purpose: Script for creating the postscript and html manuals
Usage: driver [d1 d2 ...]
If no argument is given, the default is to create the manual
for all subdirectories listed in the file 'docdirs'. Otherwise,
only those subdirectories given as arguments are used.
driver_html
Purpose: Script for creating the html manuals
Usage: driver_html [d1 d2 ...]
If no argument is given, the default is to create the manual
for all subdirectories listed in the file 'docdirs'. Otherwise,
only those subdirectories given as arguments are used.
driver_tex
Purpose: Script for creating the postscript manuals
Usage: driver_tex [d1 d2 ...]
If no argument is given, the default is to create the manual
for all subdirectories listed in the file 'docdirs'. Otherwise,
only those subdirectories given as arguments are used.
gif_grep
Purpose: Used to check if the pictures (gif files) linked in the manual
are in their proper places. Creates a web page that contains
the result of a grep for "gif" in each html file. In most
cases, this grep provides enough information so the page contains
simply pictures or "broken picture" icons.
Usage: gif_grep [d1 d2 ...]
If no argument is given, the default is to grep all html files
in the current directory and all subdirectories. Otherwise,
only the html files in subdirectories given as arguments are
searched.
install_manual_files
Puprose: Creates a directory for running the manual test suite (or manual
creation) scripts by copying the "skeleton" of the manual from
the directory doc_tex_skel and the "body" of the manual (stuff
submitted with packages) from the CGAL_autotest directory
(The exact location of this is specified by the variable SOURCE_DIR
in the script.) and then rearranging and editing some of the files
to put them in their proper places and states.
Usage: install_manual_files <version>
where <version> is something line 2.1-I-17
This script must be used in a directory that has doc_tex_skel as
a subdirectory. It creates a directory called CGAL-<version>_doc_tex
in the current directory.
link_html_wrapper
Purpose: creates a link to the file html_wrapper in the current directory
in each "package" subdirectory.
Usage: link_html_wrapper [d1 d2 ...]
If a list of directories is provided on the command line, only
those directories will have links created for them. Otherwise
if this directory contains a wrapper.tex file then this is the
directory whose subdirectories (as listed in the file docdirs)
will have links established. If there is no wrapper.tex file but
there is a docdirs file, then for each subdirectory listed in
docdirs that in turn contains a docdirs file, links will be
established in the subsubdirectories.
make_AllMains
Purpose: create the file AllMains.tex that is included with an
\input{AllMains} command in a wrapper.tex file for a directory
with subdirectories for different parts of the manual.
Usage: make_AllMains [d1 d2 ...]
if a list of directories is provided on the command line, only
those directories will possibily have a AllMains.tex file created.
Otherwise, if this directory has a wrapper.tex file, it is
assumed that this is the directory to possibly create the AllMains
file for. If this directory does not contain a wrapper.tex file
but does contain a docdirs file, then each of the directories
listed in docdirs will possibly have an AllMains.tex file created.
In any case, an AllMains.tex file is created only for directories
that also contain docdir files.
make_docdirs
Purpose: creates a new 'docdirs' file by looking in the current directory
for all subdirectories that contain a main.tex file
NOTE: Since the ordering of the subdirectory names in the docdirs file
determines the order of the chapters in the manual (since this
file is used by clean_start to create the AllMains.tex) THIS
MACRO SHOULD BE USED SPARINGLY.
Usage: make_docdirs
make_new_bib_file
Purpose: create a new cgal-manual.bib file by merging the cgal.bib files
in various subdirectories, removing duplicate entries and all
comments.
Usage: make_new_bib_file [d1 d2 ...]
if a list of directories is provided on the command line, only
those directories will contribute to the new cgal-manual.bib file.
Otherwise, if this directory has a wrapper.tex file, it is
assumed that the cgal.bib files from the subdirectory of this
directory will be used in the merge. If this directory does not
contain a wrapper.tex file but does contain a docdirs file, then
each of the directories listed in docdirs will possibly contribute
to the new cgal-manual.bib (either directly or through their
subdirectories).
ref_grep
Purpose: Used to check if the html files contain any unresolved references
that appear in the form [ref:???]. This usually indicates that
the label referred to at this point in the text was not defined.
Usage: ref_grep [d1 d2 ...]
If no argument is given, the default is to grep all html files
in the current directory and all subdirectories. Otherwise,
only the html files in subdirectories given as arguments are
searched.
rmbibcomments
Purpose: Perl script that will remove LaTeX comments that start somewhere
other than the beginning of the line(?) from the input file
Usage: rmbibcomments file
test_driver
Purpose: Script to run the test_html and test_ps scripts for all (or a given
set of) subdirectories. Also produces the .ps and .html manuals
(excluding the subdirectories that failed the tex test)
Usage: test_driver [d1 d2 ...]
test_html
Purpose: Test the conversion of each part of the manual to html. In each
directory that is tested, a subdirectory html_test is created that
contains the results. Log files named to_html.log are created
for each individual part and placed in the corresponding
subdirectories in html_test.
Usage: test_html [d1 d2 ...]
If directory names are given on the command line, only those
will be tested.
If the current directory has a wrapper.tex file, this is the
directory that will be tested.
If this directory has docdirs file, the directories listed in
this file are tested.
In each directory to be tested, if a 'docdirs' file exists,
each of the subdirectories listed there is assumed to specify
a separate package and is tested separately.
test_tex
Purpose: Test the conversion of each part of the manual to dvi (using LaTeX
and makeindex). Into each directory that is tested, two log files
are copied: main.log and main.ilg.
Usage: test_tex [d1 d2 ...]
If directory names are given on the command line, only those
will be tested.
If the current directory has a wrapper.tex file, this is the
directory that will be tested.
If this directory has docdirs file, the directories listed in
this file are tested.
In each directory to be tested, if a 'docdirs' file exists,
each of the subdirectories listed there is assumed to specify
a separate package and is tested separately.
to_dvi
Purpose: create a .dvi for a specified set of parts of the manual
Usage: to_dvi [d1 d2 ...]
If directory names are provided on the command line, dvi files
will be created only for those directories, otherwise if this
directory contains a wrapper.tex file, a dvi file will be created
for this file. If this directory does not contain a wrapper.tex
file but does contain a docdirs file, dvi files will be created for
each directory listed in the docdirs file. For subdirectories that
have a docdirs file, it is first checked if there is a
corresponding docdirs_passed_tex file. If so, only the directories
that are listed in docdirs_passed_tex are used to create the dvi
file. If not (which indicates that a test run has not been made),
all directories listed in the docdirs file will be used. For
directories without a docdirs file, this has no effect.
NOTE: only one run of LaTeX is performed by this script.
to_html
Purpose: create the .html manual for a specified set of parts of the
manual
Usage: to_html [d1 d2 ...]
If directory names are provided on the command line, html files
will be created only for those directories, otherwise if this
directory contains a wrapper.tex file, html files will be created
for the files in the current directory. If this directory does
not contain a wrapper.tex file but does contain a docdirs file,
html files will be created for each directory listed in the docdirs
file. For subdirectories that have a docdirs file, it is first
checked if there is a corresponding docdirs_passed_html file. If
so, only the directories that are listed in docdirs_passed_html
are used to create the dvi file. If not (which indicates that a
test run has not been made), all directories listed in the docdirs
file will be used. For directories without a docdirs file, this
has no effect.
to_html_w_parts
Purpose: create a specified set of html manual in which each such manual
is divided into two parts (user manual and reference manual).
using the -ref option from cc_manual_to_html
Usage: to_html_w_parts [d1 d2 ...]
Same as for to_html
to_pdf
Purpose: create the PDF manuals
Usage: to_pdf [d1 d2 ...]
If directory names are provided on the command line, .pdf
files will be created only for those directories, otherwise if this
directory contains a wrapper.tex file, a .pdf file will be
created for this file. If this directory does not contain a
wrapper.tex file but does contain a docdirs file, .pdf files
will be created for each directory listed in the docdirs file.
One has to do a separate run through LaTeX to generate the PDF
manuals with bookmarks because otherwise the things that are linked
via the hyperref package are colored in the PostScript manual as
well.
N.B. gs version 6.51 works best for the basic library conversion.
version 6.50 gives up or segmentation faults or does other
nasty things.
to_postscript
Purpose: create the postscript files for the various parts of the
manual from the .dvi files
Usage: to_postscript [d1 d2 ...]
If directory names are provided on the command line, .ps files
will be created only for those directories, otherwise if this
directory contains a wrapper.dvi file, a .ps.gz file will be created
for this file. If this directory does not contain a wrapper.dvi
file but does contain a docdirs file, .ps.gz files will be created
for each directory listed in the docdirs file.
to_postscript_letter
Purpose: create the postscript files that will fit on U.S. letter size paper
for the various parts of the manual from the .dvi files
Usage: to_postscript_letter [d1 d2 ...]
If directory names are provided on the command line, *_letter.ps
files will be created only for those directories, otherwise if this
directory contains a wrapper.dvi file, a _letter.ps file will be
created for this file. If this directory does not contain a
wrapper.dvi file but does contain a docdirs file, _letter.ps files
will be created for each directory listed in the docdirs file.