Navigation: Up, Table of Contents,  Short Table of Contents,  Package Overview,  Bibliography,  Index,  Title Page

Chapter 2
Specification Documentation

Susan Hert (hert@mpi-sb.mpg.de)
Lutz Kettner (kettner@mpi-sb.mpg.de)

There are two ways of constructing a software design. One way is to make it so simple that there are obviously no deficiencies. And the other way is to make it so complicated that there are no obvious deficiencies.

C. A. R. Hoar

CGAL is physically structured into packages , which is reflected in the SVN package structure, see Chapter 3. Generally, each package in the library will contribute some chapters to the manuals, some might only contribute a section to some larger chapter.

The following is the current plan and in the process of realization

CGAL is logically presented to the users in modules . A module consists of one or several packages. A package can be part of several modules. An example for a module would be the CGAL Kernel, and also the whole library.

Generally, a manual is created for a particular module. Such a manual consists of a wrapper file that will include the manual parts from the individual packages that comprise the module. However, manuals can be created for individual packages, mostly for editing and reviewing, and also only reasonably if the package contributes a whole chapter.

The division into different manuals is currently under revision. We merge several manuals into one manual with different parts.

The official CGAL documentation is currently divided into six separate manuals:

Not surprisingly, the Installation Guide describes how to install CGAL and the Use of STL manual describes features of STL that are used and extended in CGAL.

Documentation of new packages and features will likely be included in the Kernel, Basic Library, and Support Library documentation. See Section 1.3 for a description of what these three parts of the library contain. Each of these manuals is further subdivided into two parts: a Users' Manual and a Reference Manual. Sections 2.3 and 2.4 below describe the contents of these two parts.

The manuals are produced from input files in PostScript, PDF, and HTML format. We provide a set of style files with numerous commands that are used to format the manuals in a (more or less) uniform fashion. The conversion from input to HTML output is done with our own latex_to_html converter program that in particular understands our manual style files. Section 2.1 describes how to organize your documentation files and what is required for submitting documentations. Section 2.2 provides the basic information about these tools and style files that you will need to produce the documentation for your package. Sections 2.4 and 2.3 describe the contents and the macros provided in our style files for the Users' Manual and the Reference Manual, respectively. Sections 2.5 and 2.6 give information about including figures in your documentation and inserting indexing commands, respectively. Section 2.7 describes the manual test suite run for each internal release of the library. Section 2.8 discusses common problems and solutions. Section 2.9 concludes with the requirements and recommendations for the specification documentation.

2.1   File and directory organization

We start with the organization of the documentation of a package. After that, we describe the organization of a module documentation.

Generally, each package in the library will have its own chapter in both the reference manual and the users' manual , some might only contribute a section to some larger chapter. So, in principle, the documentation of a package starts with the \chapter command. Note, that each chapter, in particular the \chapter command, needs to be in a different file. A wrapper file may then include all chapters.

The Polyhedron package can serve as an example for the manual organization.

It is required that the documentation submitted with a package be organized according to a specific directory structure, which is described more completely in Section 4.2. In summary, all .tex source files and corresponding figures are kept in a doc_tex subdirectory of the package. The following rules describe the details:

This is all that is needed for a package manual and the cgal_manual program mentioned in Section 2.2.1 will create the necessary wrapper file automatically on the fly to create PostScript, PDF, or HTML manuals for an individual package.

For modules, an additional wrapper file is needed. The following rules describe the details, and Section 2.2.5 lists an example wrapper file:

2.2   The manual tools

As a package author, it suffices to learn from this section that you need to install two SVN packages, how to use the cgal_manual program, and what style files are available in the automatically generated wrapper for packages. Occasionally, you might need to add a new entry in the globally maintained Bib file.

For module authors, we list an example wrapper file and document the commands available in particular for wrapper files and for handling dependencies between packages. The example wrapper file might also be helpful for package authors to understand the context in which the package chapter is formatted.

All programs, style files, and other supporting files for the creation of the manuals are contained in two SVN packages:

Manual_tools
contains the style files for C++ manual page formatting and the to HTML converter program. These style files and the converter can be used independently from CGAL. Stable snapshots are also released at http://www.cgal.org/Members/Manual_tools/.
Manual
contains the CGAL specific wrapper files with the customization for the CGAL manuals and a top-level driver script to run and the latex_to_html converter consistently in the manual file structure of CGAL manuals. It contains also the additional auxiliary files for creating the CGAL manuals that are not particular to individual packages. These are figures like the CGAL logo or the bibliography file doc_tex/Manual/cgal_manual.bib for Bib.

In a nutshell, it is mandatory to install the Manual_tools package properly on your system. From the Manual package one needs only the program Manual/developer_scripts/cgal_manual in the execution path and the package itself should be placed side-by-side with your own package(s) that you develop (the cgal_manual script finds then automatically the other files in the Manual package). Side-by-side means that the package directory Manual is in the same directory as the package directory Package that you develop.

2.2.1   Program cgal_manual in the Manual package

The cgal_manual program is a bash script residing in the developer_scripts/ directory. It is called in the doc_tex/ directory of a CGAL package or of an internal release.

This script is the driver program for creating CGAL manuals. It makes use of , PDF, Bib, makeindex, latex_to_html, and other tools to create the PostScript, PDF, and HTML manuals for individual SVN Packages as well as custom Modules and its Sub-Modules. It encodes the conventions of how CGAL manuals are organized and how the general purpose tools need to be called to create the manuals. We specify these conventions here in the developers manual. Note that a brief documentation is also kept in the script itself, these documentations need to be kept synchronized!

SVN Package
 

Development unit in CGAL hosted on our SVN server. A package has a fixed directory structure. Let's assume the package is called Geom, then the documentation must reside in a directory doc_tex/ within the package Geom. Here, individual subdirectories, typically Geom/ and Geom_ref/, contain the users' and the reference manual respectively. The individual subdirectories contain a main.tex file that contains the manual chapter, possibly several and possibly using several other input files, but all included with relative paths from the doc_tex/ directory, where the tools and this script will run.

In general, all individual subdirectories that contain a main.tex file are processed. If they exist in pairs, we assume that doc_tex/*/main.tex and doc_tex/*_ref/main.tex are corresponding users' and reference manual entries in the table of contents.

The main.tex files are not stand-alone files. They are chapters, i.e., do not contain \begin{document} commands etc. This script provides the necessary wrapper file.

Modules
 

Presentation unit of modularity towards the user, assembled from SVN Packages. For a module of name Algo it is assumed that in the doc_tex/ directory the necessary driver file Algo.tex exists. This driver is a complete file including the \begin{document} command and such. It includes the various chapters from the packages.

Sub-Modules
 

Another presentation unit on top of modules. A sub-module only contains a subset of the packages in a module. The numbering of pages, chapters, equations et cetera is inherited from the module, while the table of context and the index is shrink-wrapped to the sub-module.

Generally, for some module m.tex, a sub-module sub is defined in a file m__sub.only.tex that contains commands to be executed before the document starts. The most obvious command therein is probably \includeonly. Note: packages split into user manual and reference manual need two entries in the
includeonly command. Sub-modules have to adhere to the filenaming scheme from above, in order to be found by the cgal_manual script. There can be multiple sub-modules for each module. Sub-modules of sub-modules are not supported.

For example, consider a module stored in cgal_manual.tex. A sub-module Geom should be built, restricting the module to user and reference manual of the package Geom. It could be stored in a file called cgal_manual__Geom.only.tex, only containing the command \includeonly{Geom/main,Geom_ref/main}.

When building a module with the cgal_manual script, the default is to produce no sub-modules of it. The desired sub-modules can be specified by -sub-modules=mod1,mod2.. where sub-modules are given as a comma-separated list. Only the sub-module name has to be given, not the filename under which it is stored. A special sub-module is all, which matches all sub-modules present in the current directory.

This script can create individual package documentation given the name of the individual subdirectories in doc_tex/. It creates module documentations given the name of the module driver file.

The default is to create package manuals for all */main.tex files, where */main.tex and corresponding *_ref/main.tex are kept in one manual, and to create manuals for all *_[Mm]anual.tex, which are representing modules.

This script can be used in three different environments of CGAL sources. It decides automatically in which situation it is and adapts the necessary search paths for style files and bibliographies.

  1. CGAL Internal Release: The style and bibliography files are relative from the doc_tex directory in the subdirectory Manual/.

  2. Individual CGAL Packages + CGAL Package Manual: The style and bibliography files are relative from the doc_tex directory reachable with the path ../../Manual/doc_tex/Manual/.

  3. All other environments: The style and bibliography files need to be installed properly from the SVN package Manual, such that the tools can find them, for example, through the search paths defined in the environment variables TEXINPUTS, BIBINPUTS, and LATEX_CONV_INPUTS. The program checks if the files are actually in the search paths and issues an error message otherwise.

This script properly adds entries in TEXINPUTS, BIBINPUTS, and LATEX_CONV_INPUTS so that bib and style files are found. It also adds ../examples:../demo to these paths so that example source codes are properly found.

The result of run of cgal_manual are the specified manuals in the corresponding ../doc_ps, ../doc_pdf, and ../doc_html directories. A logfile with suffix .cgallog is created with a logfile summary from the individual logfiles .log, .blg, .ilg, .pdflg, and .hlg. The logfiles are kept in case of warnings and error messages.

The screen output reports the progress and result status of each module (abbreviated as Mod) and package (abbreviated as Pck) for each manual type, i.e., PostScript, PDF, and HTML.

This script also serves for the test-suite. It can be configured to create the test-suite result tables also at your local configuration (and without sending the email notification to cgal-develop ;-). The default settings are encoded and documented at the beginning of the script in a clearly marked region. For individual customizations, the script reads the individual resource file ${HOME}/.cgalmanualrc after the default initialization.

When the -testsuite option is used the script will copy all the manuals and logfiles to ${TestSuiteResultPath}/CGAL-${CgalVersion}/ and creates an HTML summary page index.html in that subdirectory. The latest result is also always accessible at ${TestSuiteResultPath}/LAST/index.html. Furthermore, the script will cleanup old results. For the most recent number ${TestSuiteFullHistory} of test suites the full results including the manuals are kept. Older test suites will have their manuals deleted to save space. In total only ${TestSuiteHistory} many test suites are kept. The history of test suites is managed in a shift register like fashion using files of defined names History.<i> that contain the name of the i-th test suite subdirectory. The 1st is the most recent test suite and corresponds to the LAST directory. If the test suite is repeated for the same internal release number, the new results will overwrite the old results. 

Usage: cgal_manual [<options>] [<module-files...>] [<package-dirs...>]
Options:
    -ps                 PostScript manuals.
    -pdf                PDF manuals.
    -html               HTML manuals (incl. a LaTeX run).
    -wrapper            creates the LaTeX wrapper files only.
    -testsuite          runs testsuite, installs results and sends email. Use
                        only after reading the config section of this script.
    -h                  help.
    -V                  version.
    -v                  verbose: repeats logfiles on stderr.
    -k                  keep logfiles (default: delete after a clean run).
    -n                  no logfile: delete logfiles always.
    -s                  create a summary logfile .sum .
    -quiet              no progress messages.
    -realquiet          suppresses also error messages.

    -cmdlog             create a logfile "cmd_log" containing all commands
                          that were issued during execution

    -sub-modules=mod1,mod2...
                          build specified sub-modules, given as a comma-
                          separated list.

2.2.2   SVN package Manual_tools

The SVN package Manual_tools and the release tar ball from http://www.cgal.org/Members/Manual_tools/ keep all files in the subdirectory called Manual_tools, which itself has the following subdirectories:

doc/
- directory containing the documentation for the style files and the converter program
example/
- directory containing example documentation
format/
- directory containing the style files used for formatting the manual
scripts/
- directory containing various support scripts
src/
- directory containing the style files and program source code for the to HTML converter.

There are also README and CHANGES files provided for information. It is mandatory to install this package properly on your system following the description in the INSTALLATION file. Linux and Sun Solaris are supported platforms.

2.2.3   Style files in the Manual_tools package

The manuals are written with macros provided in the following style files provided in the Manual_tools package. When properly installed, these style files are in the search paths of and latex_to_html. The most prominent macros are introduced in this chapter. For the full documentation please see to the files with corresponding names in the Manual_tools/doc directory .

2.2.4   Programs in the Manual_tools package

The latex_to_html program is the main program provided by the Manual_tools package. It is in fact a bash-shell script and uses itself a number of other programs, which are not detailed here. In addition, a couple of programs come with this package that can be of independent interest.

2.2.5   Example wrapper file for a module manual

The cgal_manual program can be used with the option -wrapper to create the default wrapper file for a particular package. This can be used as a good (more minimal) starting point for a new module. Larger examples can be studied looking at existing modules, such as the cgal_manual.tex in the Manual/doc_tex/ directory that contains the whole CGAL manual. The following is a short wrapper file that came out of the call cgal_manual -wrapper Polyhedron Polyhedron_ref. Note that improvements in these tools might change the actual outcome. For the custom \cgal... commands see the next Section 2.2.6 for their definition. 

% +------------------------------------------------------------------------+
% | Polyhedron.tex
% | LaTeX Wrapper File for CGAL User and Reference Manual
% | Automatically generated by 'cgal_manual' for CGAL Packages
% +------------------------------------------------------------------------+

\documentclass{book}
\usepackage{cgal_manual}

\makeindex

% Make the table of contents use two columns
\lcHtml{\lcTwoColumnToc}

\begin{document}

\cgaltitlepage{Polyhedron Package}

\cgalchapters{
    %\entryleftright{\part{User Manual}}{\part{Reference Manual}}
    \lcTex{\entryright{\listofrefpages}}
    \packageleftright{Polyhedron}{Polyhedron_ref}
}
\bibliographystyle{alpha}
\bibliography{cgal_manual,geom}

\printindex

\end{document}

Uncommenting the line with the \part commands would add parts to the manual as they are used for large modules, but they would be wasteful for individual package manuals.

2.2.6   Style file cgal_manual.sty in the Manual package

The style of the CGAL manuals is encoded in the style file

Manual/cgal_manual.sty

which is located at Manual/doc_tex/Manual/cgal_manual.sty. It determines the page size, pulls in several other style files, and defines CGAL specific macros. The style files currently pulled in are:

cc_manual alltt graphicx psfrag
cc_manual_index ifthen epsfig rotating
latex_to_html makeidx ipe longtable
path amssymb pslatex
The additional macros defined are:

\cgalversion
 

Expands to the current CGAL version. This is either the version number, e.g., Release 3.1-I-58, that is contained in the version.tex file of an internal release if it exists, or otherwise the dummy text Separate Build.

\cgalversiondate
 

Expands to the date of the current CGAL version. This is either the date, e.g., 18 January 2004, that is contained in the version.tex file of an internal release if it exists, or otherwise the current date from the macro \today.

\cgaltitlepage{quoted-package-name}
 

Creates a title page for the CGAL package named quoted-package-name. Note that underscores in the quoted-package-name need to be quoted, i.e., written as \_. This macro will be used by the cgal_manual program to generate automatic title pages for manuals of individual packages.

\cgaldeclarepackage{package-name}
 

Remembers the package name, such that it can be tested later with the \cgalifpackage{package-name} macro. The package-name can be given literally without quoting underscores and such. This macro will be used in the \cgalchapters expansion to declare all packages used in a module before they are included. So packages can check for the existence of other packages in a manual even if thus package is included later.

\cgalifpackage{package-name}{yes-text}{no-text}
 

Tests if package-name was previously declared with \cgaldeclarepackage{package-name}, and if so expands to the yes-text, and otherwise expands to the no-text.

\cgalreinit
 

Re-initializes some style parameters of the C++ manual layout. It is typically used before each package chapter to give a package a clean start.

\cgalchapters{body}
 

In a wrapper file for a CGAL manual the different user manual and reference manual chapters are grouped in this body using the macros \entryleft, \entryright, \entryleftright, \packageleft, \packageright, and \packageleftright explained below. The body is evaluated several times, let us call them the declaration pass, the left pass, and the right pass. The declaration pass applies the \cgaldeclarepackage macro to all arguments of all \package...macros, so that all packages are declared in the following passes.

The next passes are tailored for the idea in the HTML output to have a table-of-contents with two columns; one on the left for the user manual chapters, and one on the right for the reference manual chapters. This two-columns layout is optional. If it is activated (the default for CGAL manuals) only another, second evaluation of body is necessary and each macro is evaluated as if it would be the left pass and then immediately afterwards as if it would be the right pass. For the processing and for a single-column table-of-contents in the HTML manual the left pass and the right pass are two separate evaluations of the body, effectively placing the reference manual behind the user manual.

The two-columns layout for the HTML table-of-contents organizes the table-of-contents in blocks on the left and right side. Entries on the same side are aggregated to a block until the side is switched. A switch from left to right closes the left block and opens a block on the right that is aligned with this left block. A switch from right to left closes the right block and opens a new left block below all other blocks. A block can be explicitly closed with the \lcTocSync command that effectively starting the next block below all others.

The following macros can be used in the body, and if suitable, also combined with \lcTex{...} and \lcHtml{...} macros. See Section 2.2.5 for an example.

\entryleft{left-text}
 

Expands left-text when evaluated for the left pass of \cgalchapters. Can be used, for example, to place \part{...} commands in the left-text.

\entryright{right-text}
 

Expands right-text when evaluated for the right pass of \cgalchapters.

\entryleftright{left-text}{right-text}
 

For HTML output, synchronizes the block structure of the table-of-contents with \lcTocSync before and after expanding the texts. Expands left-text when evaluated for the left pass and expands right-text when evaluated for the right pass of \cgalchapters.

\packageleft{left-package-name}
 

Expands to \cgaldeclarepackage{left-package-name} in the declaration pass of \cgalchapters. Expands to \cgalreinit\include{left-package-name/main} when evaluated for the left pass. It is typically used to include a package documentation in the manual with its own chapter, for example, with \packageleft{Kernel_23}. The \cgalreinit command re-initializes some style parameters to give the chapter a clean start.

\packageright{right-package-name}
 

Same as \packageleft, but expanding for the right pass instead for the left pass of \cgalchapters.

\packageleftright{left-package-name}{right-package-name}
 

Same as \packageleft{left-package-name} followed by \packageright{right-package-name} and enclosed by \lcTocSync to synchronizes the block structure of the table-of-contents for HTML output.

2.3   Users' manual

In contrast to the reference manual, the users' manual is intended to be read by users who are first considering whether to use part of the library. Thus the descriptions provided here should give sufficient information for a user to understand the functionality provided by the packages, but this does not mean, for example, that all functions and classes need to be described in great detail. Descriptions should be given in a more general way than in the reference manual. For example, one might mention that there is a function called ch_jarvis that implements the Jarvis march convex hull algorithm, but one need not explicitly state what the arguments of this function are, what the traits class requirements are, or the template parameters. The users' manual should also provide examples that are more lengthy than the ones provided in the reference manual. The examples should naturally be accompanied by sufficient explanation of the code in order for them to be understandable, and one should aim for examples that illustrate the most interesting features of a package and not necessarily the most complicated ones.

You should mention the precise name of the class(es) or function(s) being described (although NOT in the table of contents) so if the user wants the functionality being described it will be easy to find the thing that provides it. If the precise name is given (i.e., the name given at the top of the reference page), then a hyperlink can be created automatically.

As a rule, each chapter should include:

The table of contents reflects the organization of the manual, and it should be a concise but informative listing. These specific guidelines regarding the organization are provided:

In general, one should describe things at a level of detail that gives people enough information to determine if they want to refer to the reference page for the full details and one should use the precise name of a reference manual item so that cross-linking (by humans or the HTML converter) is possible. For example, you might say:

The fact that points are required to be chocolate in order to compute a Hundink cone means that the traits class for a Hundink cone must provide flavored predicates. The precise description of the requirements is given by the concept HundinkConeTraits_6. The class Hundink_cone_traits_6 is a model of this concept.

2.4   Reference manual

The reference manual is meant to be a place where programmers already familiar with the library can look to find information about specific parts of the library they want to use. It should provide detailed descriptions of the functions, classes, concepts, etc. provided in the library and should not be weighted down with lengthy explanations of the design philosophy or complicated examples; these things belong, if anywhere, in the users' manual. Because the reference manual and users' manual are meant to be independent documents, there is going to be some overlap between the two (e.g., text that introduces a package chapter), but this overlap should be kept to a minimum.

There are currently nine categories of reference pages that are supported by the manual tools. These are: class, function object class, concept, function object concept, enum, function, macro, constant, and variable. For each of these categories there is an environment that takes a single argument, which is the identifier plus an optional list of template arguments (for classes). Function parameters, function template declarations and macro parameters are not given here. The result of entering one of these environments is the production of a section heading that has the category followed by the identifier provided as the argument. For all categories except concepts and function object concepts, this identifier is prefixed by the global scope name that has been defined using \ccDefGlobalScope. By default, this scope is empty. For example the following commands 

   \ccDefGlobalScope{CGAL::}
   \begin{ccRefClass}{Some_Class<T>} ... \end{ccRefClass}

produce the heading

If \ccNewRefManualStyle has been set to \ccTrue, each new reference manual environment will also produce a new page and will decorate the first page of each environment with a tab in the side margin. The macro \ccRefPageBreak can be used to turn off page breaks for very short reference pages (e.g., for constants).

Below we briefly describe what should be documented in each of the ccRef* environments and list some of the most useful commands for each section. See Manual_tools/doc/cc_manual.ps.gz for a full description of these environments and the other commands available.

Some_Class<T>

2.4.1   Section headings

The following commands defined in cc_manual.sty produce non-numbered section headings under which various aspects of an item should be documented. The commands are listed in the order in which they should be used. Sections that are empty for a particular item should, obviously, be left out.

\ccDefinition Definition including template parameters
\ccInheritsFrom Inherits From base classes
\ccRefines Refines concept names
\ccHasModels Has Models models for concepts
\ccIsModel Is Model for the Concept concept names
\ccTypes Types local type definitions
\ccConstants Constants constant values
\ccCreation Creation constructors, assignment
\ccOperations Operations functions and operators
\ccAccessFunctions Access Functions member access
\ccQueryFunctions Query Functions query functions
\ccPredicates Predicates predicates
\ccModifiers Modifiers insert, delete, update
\ccSeeAlso See Also other classes, functions
\ccImplementation Implementation running time, memory
\ccExample Example program examples

2.4.2   Classes

Classes are described using the ccRefClass environment. The types provided by the class should be described using\ccTypedef followed by a description of each member function, its parameters, and pre- and postconditions (using either \ccMethod, \ccMemberFunction, or \ccConstructor). The types and functions provided by a class should be documented in the order indicated by the ordering of the section commands listed in Section 2.4.1. Just after the definition section, a command \ccInclude should be used to indicate in which file the class is defined.

Note that it is NOT generally sufficient to say simply that this class provides all types and operations required by a concept it models. The point is to document the implementation details here so people can find out, for example, exactly what type of point is being used in the computation.

2.4.3   Concepts

Concepts should be described using the ccRefConcept environment. Concepts are abstractions that are defined by a set of syntactical and semantical requirements. These requirements include data, types, and functions. You should describe the concept under a \ccDefinition heading and describe the requirements using as many of the headings listed in Section 2.4.1 as appropriate. In particular, under the heading produced by \ccHasModels you should list the classes in the library that are models for this concept.

2.4.4   Constants

Global constants should be described using the ccRefConstant environment. The name of the constant should be provided as the argument to the environment. Under a \ccDefinition heading, the meaning of the constant should be described. Just after the definition, a command \ccInclude should be used to indicate in which file the constant is defined. Following this, the complete declaration of the constant should be formatted using \ccGlobalVariable. Another possible section heading here is \ccSeeAlso.

2.4.5   Enums

Global enums should be described using the ccRefEnum environment. The name of the enum is provided as an argument to this environment. Within this environment the \ccGlobalEnum macro should be used to format the complete enum declaration. You should describe the enum and its values under a \ccDefinition heading and use as many of the other section headings listed in Section 2.4.1 as appropriate (e.g., \ccSeeAlso, or \ccExample).

2.4.6   Functions

Global functions should be described using the ccRefFunction environment. The name of the function, excluding template declarations and parameters, is provided as the argument to this environment. Under a \ccDefinition heading, the purpose of the function should be described. Just after the definition, a command \ccInclude should be used to indicate in which file the function is defined. Following this, the macro \ccGlobalFunction should be used to format the function together with its template declarations and parameters. Preconditions and postconditions of the function should be documented using \ccPrecond and \ccPostcond. Other possible section headings here are \ccSeeAlso, \ccImplementation, and \ccExample.

2.4.7   Function Object Classes

Function object classes should be documented using the ccRefFunctionObjectClass environment. Just after the definition section, a command \ccInclude should be used to indicate in which file the class is defined. Following this, the concepts that this class is a model for should be listed under the heading \ccIsModel and then the list of member functions (a set of operator() functions) should be listed. Another possible heading here is \ccSeeAlso.

2.4.8   Function Object Concepts

Function object classes should be documented using the ccRefFunctionObjectConcept environment. The name of the concept is provided as the argument to this environment. Under the \ccDefinition heading, the concept should be described followed by the set of required functions (one or more operator() methods). Under the heading \ccRefines you should list concepts that this one ``inherits'' from and under \ccHasModels list the classes that are models of this concept.

2.4.9   Macros

Global macros should be describe using the ccRefMacro environment. The name of the macro, excluding its arguments, is provided as the argument to this environment. Under a \ccDefinition heading, the purpose of the macro should be described. Just after the definition, a command \ccInclude should be used to indicate in which file the macro is defined. Following this, the macro together with its arguments should be formatted using \ccc.

2.4.10   Variables

Global variables should be described using the ccRefVariable environment. The name of the variable should be provided as the argument to the environment. Under a \ccDefinition heading, the meaning of the variable should be described. Just after the definition, a command \ccInclude should be used to indicate in which file the variable is defined. Following this, the complete declaration of the variable should be formatted using \ccGlobalVariable. Another possible section heading here is \ccSeeAlso.

2.5   Figures

When including pictures in your documentation, you must provide versions of the pictures for the PostScript, PDF, and HTML versions of the manuals. This generally means providing both a .ps or .eps file for PostScript manuals, a .pdf or .png file for PDF manuals, and a .gif, .jpg, or .png file for HTML manuals. You should take care that the figures are readable in both formats and that they are neither too large nor too small. Also, all figures used in the HTML documentation should have transparent backgrounds. You can achieve this using the giftrans program distributed with LaTeX or by using one of the scripts available at http://www.cgal.org/Members/Manual_tools for converting from LaTeX to gif, Encapsulated PostScript to gif, PostScript to gif, and from ipe to gif .

We use currently PDF to create the PDF manuals. The \includegraphics macro can be used conveniently for the PostScript images as well as the PDF images. One has just to omit the file suffix, and the \includegraphics macro uses automatically an .eps or .ps file (whatever exits) for the run, and uses a .pdf file or .png file for the PDF run.

To convert an existing .eps file to the corresponding .pdf file one can use the epstopdf script (e.g. available under Linux), which has the benefit of respecting the bounding box. (The pstopdf script ignores the bounding box.) Ipe users should save their files as .eps files and also use the epstopdf script to get a proper conversion respecting the bounding box and placement on paper. Recent Ipe versions have a CropBox option which also allows to respect the bounding box.

The program that converts to HTML does not currently support the commands that input PostScript figures into a document (since the figures for the HTML manual will be in a different format). Thus for each figure you must provide the raw HTML command that inserts the .gif, .jpg, or .png file in the document. For example: 

\begin{figure}[htbp]
\begin{ccTexOnly}
\begin{center}
\includegraphics{orient} % omit suffix .eps to supprt PS and PDF
\end{center}
\end{ccTexOnly}
\caption{Orientation of a cell (3-dimensional case)
\label{Triangulation3-fig-orient}}

\begin{ccHtmlOnly}
<CENTER>
<IMG BORDER=0 SRC="./orient.gif" ALIGN=center ALT="Orientation of a cell
(3-dimensional case)">
</CENTER>
\end{ccHtmlOnly}
\end{figure}

Note above that only the parts that include the two different figure files are enclosed in the ccTexOnly and ccHtmlOnly environments. The figure, caption, and label commands will be processed for both and latex_to_html. Note also that the caption and label are placed above the HTML picture. This is done so references to this figure will go to the top of the picture instead of the bottom (and thus be visible in the browser).

2.6   Indexing

In order to be truly useful, a manual needs to have an index. The latex_to_html program produces an index for the HTML manual automatically. The style file cc_manual_index.sty was developed in order to provide a means for producing an index for the PostScript version of the manual. Though there is also some automatic indexing done by the cc_manual_index.sty file in conjunction with cc_manual.sty, this indexing is not sufficient as it can index only things that are given as arguments to the formatting macros. When writing your documentation, you should add other indexing commands in the text in order to achieve the following goals:

You should also take care that the index entries produced by the automatic indexing are in keeping with these goals, and, when not, use the commands provided in cc_manual_index.sty to turn off the automatic indexing. See the file Manual_tools/doc/cc_manual_index.ps.gz for a description of the commands available and a full description of what should and should not be indexed.

2.7   Test suite

With each internal release of the library, a test suite is run on the manuals to make sure that the documentation submitted makes it through all the programs and scripts without a problem. Each package and each module manual is tested with both (and its companion programs makeindex and bibtex) and latex_to_html. The results of the test suite are currently available at

http://www.cgal.org/Members/Manual_test/LAST/

It is a given, of course, that developers should test that their packages' documentation works with both and latex_to_html before submitting. The test suite is meant simply to assure that all the parts fit together nicely and all references to other parts of the manual get resolved correctly. Each time you submit a package with modified documentation, you should check these test results to make sure your documentation did not cause any problems.

2.8   Common problems and solutions

Problem - Undesired Links in HTML Manual

Cause:
Any occurrence of the name of a class, function, etc. that is documented in the reference manual is automatically crosslinked to the definition of that entity.

Solution:
Sometimes, the preferred solution is to chosse a better name for the entity under consideration. For example, a traits class for a planar map should be called Planar_map_traits rather than Traits. Another possibility is to add the command \ccHtmlNoClassLinks before the \begin{ccClass}{Traits} command to globally turn off linking of the word Traits. To disable links from one word only, use the command \ccHtmlNoLinksFrom. For example, \ccHtmlNoLinksFrom{Traits} will not create links for this particular occurrence of the word Traits.

Problem - Nontransparent backgrounds for HTML figures

Cause:
The .gif file was produced without a transparent background.

Solution:
Use either the giftrans program distributed with LaTeX or one of the scripts ps2gif, ipe2gif, or latex2gif that are available from http://www.cgal.org/Members/Manual_tools (which use giftrans and work for figures with white backgrounds) to make the background transparent.

Problem - Unresolved figure references in HTML

Cause:
This problem is generally caused by the absence of a \label command inside the HTML figure environment.

Solution:
The easiest way to solve this problem is to put the \label command in the text that is processed by the HTML converter, as the following example illustrates: 

\begin{figure}[htbp]
\begin{ccTexOnly}
\begin{center}
\includegraphics{orient} % omit suffix .eps to supprt PS and PDF
\end{center}
\caption{Orientation of a cell (3-dimensional case)
\label{Triangulation3-fig-orient}}
\end{ccTexOnly}
\lcHtml{\label{Triangulation3-fig-orient}}
\begin{ccHtmlOnly}
<CENTER>
<IMG BORDER=0 SRC="./orient.gif" ALIGN=center ALT="Orientation of a cell
(3-dimensional case)">
</CENTER>
\end{ccHtmlOnly}
\end{figure}

This will produce a centered figure without a caption in the HTML manual. References to the label Triangulation3-fig-orient will produce a link that refers to the top of this figure. If you want the caption with the HTML figure as well, then simply move the \end{ccTexOnly} command above the \caption command and remove the \lcHtml command. See also Section 2.5.

Problem - Raw LaTeX commands in HTML manual

Cause:
This problem is generally caused by the use of commands that are not supported by the HTML converter. See latex_to_html.ps.gz for a list of these unsupported commands.

Solution:
Either remove the offending command altogether or enclose it in a \lcTex command or an lcTexBlock environment (which are both defined in latex_converter.sty) .

Problem - Included files cannot be found

Cause:
This problem is generally caused by a wrong relative path given in the \input command (or its derivative) or the absence of a directory from the appropriate environment variable.

Solution:
Paths to source files in other directories must generally be provided relative to the place where and latex_to_html are run, not relative to the place where the file containing the command is. When producing the manual, these programs are run in the doc_tex directory, so paths should be relative to this directory.

An exception is for example and demo programs included in the documentation. . These should always be programs that are in the distribution (and thus in the test suite) and should be included using the command ccIncludeExampleCode. For programs you need only specify the path relative to the directory CGAL_ROOT/examples or CGAL_ROOT/demo as the environment variables TEXINPUTS and LATEX_CONV_INPUTS are set so these directories are searched when the manuals are created with the cgal_manual program from Section 2.2.1. (See Manual_tools/doc/latex_to_html.ps.gz for more details.) For example, you would use the following command 

   \ccIncludeExampleCode{Polygon/PolygonDemo.C}
to include the source file CGAL_ROOT/demo/Polygon/PolygonDemo.C. Obviously, you could have problems if you have an example program and a demo program with the same name in the same package, so try to avoid this.

2.9   Requirements and recommendations

Requirements:

Recommendations:

Next chapter: SVN Server
Navigation: Up, Table of Contents,  Short Table of Contents,  Package Overview,  Bibliography,  Index,  Title Page
CGAL Open Source Project. Release 3.2.1. 13 July 2006.