mirror of https://github.com/CGAL/cgal
2146 lines
97 KiB
TeX
2146 lines
97 KiB
TeX
% |#########################################################################|
|
|
% | |
|
|
% | Manual for the C++ Reference Manual Indexing Style cc_manual_index.tex |
|
|
% | ------------------------------------------------------------- |
|
|
% | |
|
|
% | 23.09.1999 Susan Hert hert@mpi-sb.mpg.de |
|
|
% | Saarbruecken, Germany |
|
|
% | $Revision$ |
|
|
% | $Date$ |
|
|
% |_________________________________________________________________________|
|
|
% |#########################################################################|
|
|
|
|
\documentclass[11pt]{article}
|
|
\usepackage{cprog}
|
|
\usepackage{cc_manual}
|
|
\usepackage{supertabular}
|
|
\usepackage{makeidx}
|
|
\usepackage{latex_to_html}
|
|
\usepackage{epsfig}
|
|
|
|
\makeindex
|
|
|
|
|
|
% page dimensions
|
|
% ---------------
|
|
\textwidth 15.4cm
|
|
\textheight 24 cm
|
|
\topmargin -14mm
|
|
\evensidemargin 3mm
|
|
\oddsidemargin 3mm
|
|
|
|
{
|
|
\begingroup
|
|
\catcode`\|=0
|
|
\catcode`\[=1
|
|
\catcode`\]=2
|
|
\catcode`\{=12
|
|
\catcode`\}=12
|
|
\catcode`\\=12
|
|
|gdef|Open[[|tt {]]
|
|
|gdef|Close[[|tt }]]
|
|
|gdef|Backslash[[|tt \]]
|
|
|endgroup
|
|
}
|
|
|
|
|
|
\newenvironment{indexex}{\begin{tabbing}
|
|
xxxx\=xxx\=\kill}{\end{tabbing}}
|
|
|
|
\newcommand{\Mindex}[1]{\index{#1@\protect\Backslash{\tt #1}}}
|
|
\newcommand{\Eindex}[1]{\index{#1 environment@{\tt #1} environment}}
|
|
\newcommand{\ccIndexEntry}[1]{\index{cc#1@\protect\Backslash{\tt cc#1}}}
|
|
\newcommand{\TTindex}[1]{\index{#1@{\tt #1}}}
|
|
\newcommand{\Dindex}[1]{#1\index{#1}}
|
|
\newcommand{\VarText}[1]{$<${\em #1}$>$}
|
|
|
|
\title{\cgal\ Reference Manual Index Specification \\
|
|
and Style File Documentation}
|
|
|
|
\author{Susan Hert}
|
|
|
|
\date{\ccRevision. \ccDate}
|
|
|
|
\begin{document}
|
|
|
|
\maketitle
|
|
|
|
|
|
\section{Introduction}
|
|
\label{introduction}
|
|
|
|
This document provides a specification of the format and content of
|
|
the index to be produced for the \cgal\ reference manual, and documentation
|
|
of tools that may be used to produce such an index.
|
|
The specification and tools described in this document
|
|
were written with the following goals in mind:
|
|
\begin{itemize}
|
|
\item All key words, phrases, topics, and concepts should be indexed.
|
|
\item All \cgal\ \CC\ identifiers described in the manual should be indexed.
|
|
\item There should be listings in the index for any pages on which an
|
|
item is introduced, defined, or described as well as any pages
|
|
where key uses for or instances of these things are described.
|
|
\item There should be sufficient cross referencing to allow users
|
|
to find things starting from many different points.
|
|
\item There should NOT be entries for every mention of every item in the
|
|
manual.
|
|
\end{itemize}
|
|
|
|
One \LaTeX\ style file and two Perl scripts have been written to assist in
|
|
the attainment of these goals. The style file, \verb|cc_manual_index.sty|,
|
|
was written as a companion
|
|
to the style file \verb|cc_manual.sty|\TTindex{cc\_manual.sty} and is meant
|
|
to be used in
|
|
conjunction with \LaTeX's {\tt makeindex} program. Minor changes to
|
|
\verb|cc_manual.sty| have been made to provide automatic indexing where
|
|
possible. These changes are documented here as well. The Perl scripts,
|
|
{\tt add\_part\_num}\TTindex{add\_part\_num} and {\tt index\_fix}\TTindex{index\_fix},
|
|
modify the index files generated by
|
|
\LaTeX\ and {\tt makeindex}, respectively, to generate an index as specified
|
|
in this document.
|
|
|
|
The general layout of the index is described in Section~\ref{layout}.
|
|
There, the specification of how page numbers will appear, which fonts
|
|
will be used, how the entries will be ordered, and what vertical and
|
|
horizontal spacing will be used is given. This section also provides
|
|
a listing of the categories of things that will be indexed.
|
|
Before delving into a detailed discussion of the contents of the style
|
|
file (Section~\ref{style_file}) and how indexing will be done for
|
|
each category of items identified in Section~\ref{layout}
|
|
(Section~\ref{how_to_index}), the basic steps necessary for producing
|
|
an index that conforms to the layout described in Section~\ref{layout}
|
|
is provided in Section~\ref{producing_index}.
|
|
|
|
%A sample index produced using these indexing tools has been included
|
|
%at the end of the document. This index was produced from {\tt .tex} files,
|
|
%for Chapters 1 through 5 of Part 1 and Chapter 8 of Part 2 of
|
|
%the \cgal\ Reference Manual, release 1.1, and
|
|
%updated to reflect the introduction of the \cgal\ namespace.
|
|
|
|
\section{General layout}
|
|
\label{layout}
|
|
|
|
\subsection{Page numbering}%
|
|
\label{page_numbering}
|
|
|
|
There will be a single, global index for all parts of the manual.
|
|
To distinguish the pages in each separately numbered part of the manual,
|
|
page numbers in the index will be of the form $p.n$, where $p$ is the part
|
|
number and $n$ is the page number in that part\index{part numbers}. Should
|
|
the manual not
|
|
be divided into separately numbered parts, the part number prefixes will
|
|
not be added (Section~\ref{producing_index}).
|
|
|
|
Items with descriptions spanning several pages will be indexed using page
|
|
ranges ({\it e.g.}, 34--43), since the {\tt makeindex} program can handle
|
|
this quite nicely.
|
|
To accomplish this, the beginning and end of the descriptive
|
|
text must be marked with indexing commands. Macros and environments
|
|
are provided to do this for all appropriate categories of items.
|
|
|
|
Multiple page numbers for a single entry will be in numerical order, separated
|
|
by commas. In most cases, {\tt makeindex} will eliminate duplicate page
|
|
numbers for a given entry, but it will not do this when, for example,
|
|
the same page number is listed in two different fonts. In such cases,
|
|
the program will print a warning in its log file. Such warnings should
|
|
be heeded and attempts should be made to remove them so as to avoid
|
|
entries such as:
|
|
\begin{indexex}
|
|
convex hull, 1, {\bf 1}
|
|
\end{indexex}%
|
|
|
|
|
|
\subsection{Fonts}%
|
|
\index{font|(}
|
|
\label{fonts}
|
|
|
|
There will be three fonts used in the index:
|
|
\begin{itemize}
|
|
\item {\verb|\ccFont| } -- \CC\ identifiers will appear in \verb|\ccFont|,
|
|
the same font as in the manual\index{font!ccFont@\verb+\ccFont+}.
|
|
\item {\bf boldface} -- Page numbers on which definitions
|
|
of index entries appear will be in boldface\index{font!boldface}%
|
|
\index{definition}.
|
|
\item {default font} -- All other things will be in default font
|
|
of the rest of the manual\index{font!default}.
|
|
\end{itemize}
|
|
|
|
In the indexing style file, fonts are defined for each of the categories
|
|
of items that are not \CC\ names to allow for the easy introduction of other
|
|
fonts to distinguish these items in the index should it seem necessary.
|
|
All of these fonts are currently defined to be the default font.
|
|
(Actually, they are defined to be empty, but the result is the same.)%
|
|
\index{font|)}
|
|
|
|
\subsection{Ordering of entries}%
|
|
\index{ordering of entries|(}%
|
|
\label{ordering}
|
|
|
|
Entries in the index will be in lexicographical order without regard to
|
|
case, with the following exception and additions:
|
|
\begin{itemize}
|
|
\item words containing capital letters will come before words with
|
|
only lower case letters when the words
|
|
are otherwise the same
|
|
({\em e.g.}, the entry for \ccc{\ccFont Orientation} will
|
|
immediately precede the one for \ccc{\ccFont orientation});
|
|
\item nonalphabetic symbols will be in order by ASCII value, before
|
|
alphabetic entries;
|
|
\item non-\CC\ names will come before \CC\ names
|
|
({\em e.g.}, the entry for the member function \ccc{\ccFont vector}
|
|
will follow the entry for vector, the general term.)
|
|
\end{itemize}
|
|
\index{ordering of entries|)}%
|
|
|
|
\subsection{Spacing}%
|
|
\index{spacing|(}
|
|
\label{spacing}
|
|
|
|
The index is formatted in two columns with indexed page numbers
|
|
separated by a comma from the
|
|
text of an entry. There are three levels of index entries available:
|
|
items, subitems, and subsubitems. Subitems are indented approximately
|
|
4 characters from the column in which items begin; subsubitems are indented
|
|
approximately 2 characters from the column in which subitems begin.
|
|
|
|
There will be one blank line before each main entry that starts with a new
|
|
letter. There will also be a blank line before each main item that begins
|
|
with the \ccc{CGAL_} prefix and a new letter after the prefix.
|
|
|
|
At times there may be two (or more) options for an entry's presentation, one
|
|
that uses fewer lines but more text per line and one that uses shorter
|
|
entries but more lines. For example:
|
|
\begin{indexex}
|
|
conversion \\
|
|
\> Cartesian to homogeneous, 1.15 \\
|
|
\> homogeneous to Cartesian, 1.15 \\
|
|
\> point to vector, 1.20 \\
|
|
\> vector to point, 1.20
|
|
\end{indexex}
|
|
|
|
OR
|
|
\begin{indexex}
|
|
conversion \\
|
|
\> between number representations, 1.15 \\
|
|
\> between point and vector, 1.20
|
|
\end{indexex}
|
|
|
|
Both of these entries will fit in the index without any lines wrapping, but
|
|
since column width is more limited than the number of pages used, when such
|
|
an option presents itself it would be prudent, when in doubt, to opt for
|
|
shorter entries with more lines.%
|
|
\index{spacing|)}
|
|
|
|
\subsection{What to index}
|
|
\label{what_to_index}
|
|
|
|
There are two groups of things that need to be indexed. The first group
|
|
consists of the \CC\ names of all things in \cgal\ that the user has access
|
|
to that are mentioned in the manual. This group includes the names of:
|
|
\begin{itemize}
|
|
\item assertion flags
|
|
\item classes
|
|
\item enums
|
|
\item enum tags
|
|
% \item global constants
|
|
\item global functions
|
|
\item global operators
|
|
\item global structs
|
|
\item global variables
|
|
\item macros
|
|
\item public member functions
|
|
\item typedefs
|
|
\end{itemize}
|
|
|
|
The second group consists, unfortunately, of things that are not as well
|
|
defined. These are things other than the \CC\ code
|
|
that a user may want or needs to know about in order
|
|
to use the library. These include:
|
|
\begin{itemize}
|
|
\item abbreviations ({\em e.g.}, CH, DCEL)
|
|
\item concepts ({\em e.g.}, circulator, point, representation class, tree)
|
|
\item functionalities ({\em e.g.}, converting between points and vectors,
|
|
traversal of a polygon, intersections, distances)
|
|
% \item generic data structures ({\em e.g.}, tree, circle, polygon)
|
|
\item hints about how to do specific things ({\em e.g.}, choosing a
|
|
representation class)
|
|
\item other libraries ({\em e.g.}, \leda, STL, Geomview)
|
|
\item packages with no associated class name ({\em e.g}, convex hull)
|
|
\item terms ({\em e.g.}, point, polyhedron, halfedge data structure)
|
|
\end{itemize}
|
|
|
|
Section~\ref{how_to_index} provides more details about how items in each of
|
|
these categories will be indexed.
|
|
It is hoped that most things that need to be indexed will fall into exactly
|
|
one of these categories (or, at least, fall most naturally into one category).
|
|
For items that do not fall into these categories, entries should be
|
|
constructed in keeping with the goals described in the introduction.
|
|
These exceptional items can be indexed using the generic
|
|
indexing macros described in Section~\ref{generic_macros}.
|
|
|
|
\section{Producing the index}
|
|
\label{producing_index}
|
|
|
|
The indexing macros in \verb|cc_manual_index.sty| together with the
|
|
{\tt makeindex} program do almost everything that is required for
|
|
producing the index that conforms to the layout described in
|
|
Section~\ref{layout}. For what they are not able to do, two Perl
|
|
scripts have been provided, one of which modifies the {\tt .idx}
|
|
that is produced by \LaTeX\, and the other of which modifies the
|
|
{\tt .ind} file produced by {\tt makeindex}. Thus there are
|
|
seven steps necessary to produce an indexed (part of the) reference
|
|
manual.
|
|
|
|
\begin{enumerate}
|
|
\item Add the following lines to the appropriate {\tt .tex} file
|
|
in the appropriate places:
|
|
\begin{verbatim}
|
|
\usepackage{cc_manual_index} % in the preamble
|
|
\usepackage{makeidx} % in the preamble
|
|
\makeindex % in the preamble
|
|
\printindex % where you want the index to appear
|
|
\end{verbatim}
|
|
\item Add calls to the indexing macros in appropriate places
|
|
in the document (Section~\ref{how_to_index}).
|
|
\item Run \LaTeX, as per usual, until everything settles down.
|
|
\item Add a part number prefix to the page numbers in the generated
|
|
\verb|.idx| file using the {\tt add\_part\_num}\TTindex{add\_part\_num}\index{part numbers} script. The proper
|
|
usage for this script is
|
|
\begin{quote}
|
|
\verb|% add_part_num| $p$ \verb|<filename>.idx|
|
|
\end{quote}
|
|
where $p$ is an integer corresponding to the part number.
|
|
The original \verb|.idx| file is copied to a file with the
|
|
suffix \verb|.idx.nopart|.
|
|
\item Run makeindex
|
|
\begin{quote}
|
|
\verb|% makeindex <filename>|
|
|
\end{quote}
|
|
\item Run the {\tt index\_fix}\TTindex{index\_fix} script on the generated
|
|
\verb|.ind| file. The proper usage for this script is:
|
|
\begin{quote}
|
|
\verb|% index_fix [-p] <filename>.ind|
|
|
\end{quote}
|
|
|
|
The script performs the following six functions:
|
|
\begin{itemize}
|
|
\item adds a sentence at the beginning of the index explaining the
|
|
use of boldface;\index{font!boldface}
|
|
\item strips trailing commas from ``see also'' entries\index{see also entries};
|
|
\item adds blank lines between CGAL-prefixed entries when the
|
|
letter after the prefix changes\index{spacing};
|
|
\item adds hyphenation clues for names with underscores\index{hyphenation};
|
|
\item puts a space in between the two characters of ``( )'' and
|
|
``[ ]'' operators\index{spacing};
|
|
\item if the {\tt -p} option is specified, reformats the integer
|
|
page numbers in the file into the $p.n$ format by using the
|
|
first digit of the page number as the value of $p$.
|
|
If the {\tt -p} option is not used, no reformatting of page
|
|
numbers is done\index{part numbers}.
|
|
\end{itemize}
|
|
The original \verb|.ind| file is copied to a file with the suffix
|
|
\verb|.ind.unfixed|.
|
|
\item Run \LaTeX\ one more time to put the index in place in the document.
|
|
\end{enumerate}
|
|
|
|
|
|
\section{The file {\tt cc\_manual\_index.sty}}
|
|
\label{style_file}
|
|
|
|
This section provides a discussion of the contents of
|
|
the \verb|cc_manual_index.sty| style file and how to use the indexing
|
|
macros provided therein to achieve the best results.
|
|
General guidelines for the use of the macros are given
|
|
in Section~\ref{general_guidelines}, followed in
|
|
Section~\ref{auto_index} by an outline of the changes that have been made
|
|
to \verb|cc_manual.sty| to produce index entries automatically.
|
|
Section~\ref{how_to_stop} documents the commands that may be
|
|
used to prevent index entries from being created, either automatically
|
|
or otherwise.
|
|
|
|
In Section~\ref{generic_macros}, the description
|
|
of the indexing commands begins with a listing of the 14 general-purpose
|
|
commands, which may be used for indexing items in any of
|
|
the identified categories as well as items that do not fall into these
|
|
categories. The remaining indexing commands, which are for specific
|
|
categories of items, are described in Section~\ref{how_to_index} along
|
|
with the indexing specifications for their respective categories.
|
|
|
|
\subsection{General guidelines and comments}
|
|
\label{general_guidelines}
|
|
|
|
|
|
To achieve the best results, the following things should be
|
|
kept in mind when using the indexing macros.
|
|
\begin{itemize}
|
|
\item An indexing command should be placed\index{placement of commands}
|
|
immediately after the
|
|
item that is to be indexed, with no spaces or punctuation
|
|
in between. This will assure that the proper page number is used.
|
|
However, the commands should not, in general, be placed inside the
|
|
arguments of other commands.
|
|
\item The following types of arguments\index{arguments} are allowed:
|
|
\begin{itemize}
|
|
\item plain text ({\it e.g.}, \verb|\ccIndexMainItem[t]{circulator}|);
|
|
\item plain text with a font%
|
|
\index{font!in macro arguments}\index{arguments!with fonts} \\
|
|
({\it e.g.}, \verb|\ccIndexSubitem[t]{representation class}{\ccFont Cartesian}|);
|
|
\item one of these 3 shortcut commands defined in
|
|
\verb|cc_manual.sty|: \verb|\stl|\Mindex{stl},
|
|
\verb|\leda|\Mindex{leda}, \verb|\cgal|\Mindex{cgal}
|
|
({\it e.g.}, \verb|\ccIndexMainItem[l]{\leda}|);
|
|
\item macros that expand to plain, unformatted text \\
|
|
({\it e.g.}, \verb|\ccIndexMainItem[C]{\ccPureClassName}|)
|
|
\index{arguments!macros as!with plain text}.
|
|
\end{itemize}
|
|
\item The following types of arguments are NOT allowed:
|
|
\begin{itemize}
|
|
\item text enclosed in a \verb|\ccc| or \verb|\ccStyle| command.
|
|
If you want this, please use \verb|\ccFont| as the text font
|
|
({\it i.e.}, \verb|\ccIndexSubitem{main}{\ccFont subitem}|).
|
|
The macros will detect the presence of \verb|\ccFont|
|
|
and do the right thing\index{arguments!in \verb+\ccFont+}%
|
|
\index{arguments!with \verb+\ccc+ or \verb+\ccStyle+}.
|
|
\item macros that expand to formatted text\index{arguments!macros as!with formatted text}.
|
|
For example, the use of \verb|\ccClassName| instead of
|
|
\verb|\ccPureClassName|\index{arguments!class name as} will
|
|
cause very nasty things to happen.
|
|
|
|
Also, if you have defined a command that expands
|
|
to something like \verb|{\bf text}| (with or without the
|
|
braces), this will cause {\tt makeindex} to complain since
|
|
the indexing macros cannot pick off the font in order to
|
|
produce the proper
|
|
formatting of ``text''. (The shortcut commands such as
|
|
\verb|\leda|, which are allowed as stand-alone arguments,
|
|
are handled as special cases.)
|
|
\end{itemize}
|
|
\item The following type of argument is not recommended:
|
|
\begin{itemize}
|
|
\item text that contains formatting commands in the interior%
|
|
\index{arguments!with formatting commands}
|
|
({\it i.e.}, something other than a font at the beginning, as,
|
|
for example, \verb|\ccIndexSubitem{main}{my \leda\ subitem}|).
|
|
It is not possible to do all the necessary parsing of these
|
|
arguments ({\it e.g.}, to pick out a font at the beginning
|
|
or to detect a modifier at the end). When such an
|
|
argument is detected, a warning message will be produced and,
|
|
if possible, an index entry will be created, but be warned
|
|
that it may not be correct.
|
|
\end{itemize}
|
|
\item There are two ways to produce a range of pages ({\em e.g.}, 34 -- 45)
|
|
\index{page range} in the index. For some categories of items, there
|
|
are environments
|
|
defined; the first and last pages in the ranges are indexed when
|
|
you enter and leave the environments, respectively. There are also
|
|
several generic commands of the form \verb|\ccIndexXBegin| and
|
|
\verb|\ccIndexXEnd|, where {\tt X} is the level of the entry begin
|
|
produced (Section~\ref{generic_macros}). These commands must
|
|
appear in pairs, and the construction of both commands in any such
|
|
pair must be {\bf exactly} the same
|
|
except for the ``{\tt Begin}'' or ``{\tt End}'' in the command name.
|
|
|
|
There may be multiple page ranges for a single item, but the
|
|
ranges may not overlap\index{page range!multiple}.
|
|
\item Subitems may be created for non-existent main items%
|
|
\index{subitems!for non-existant main items}.
|
|
The {\tt makeindex} program will do the right thing and list a
|
|
page number for only the subitem and not for the main item
|
|
(cf. the member function macro below). The same is true for
|
|
subsubitems created for non-existent main items and/or subitems%
|
|
\index{subsubitems!for non-existant entries}.
|
|
\item When creating subitems and subsubitems for existing main items
|
|
and subitems\index{subitems!for existing main items}%
|
|
\index{subsubitems!for existing entries}, care
|
|
must be taken to assure that the texts of the main item and the
|
|
subitem given as arguments to these commands are {\bf exactly}
|
|
the same, including fonts, as the text used to create
|
|
the original main item and subitem.
|
|
\item Where possible, the indexing commands produce the desired cross
|
|
referencing\index{cross referencing} entries automatically. See
|
|
the descriptions of the
|
|
specific commands to discover precisely when this is done, and
|
|
see Section~\ref{how_to_stop} to find out how to prevent this
|
|
from happening.
|
|
\end{itemize}
|
|
|
|
\subsection{Changes made to {\tt cc\_manual.sty} for automatic indexing}%
|
|
\index{automatic indexing|(}
|
|
\label{auto_index}
|
|
|
|
Seventeen commands in \verb|cc_manual.sty|\TTindex{cc\_manual.sty} have been
|
|
modified to produce automatic indexing of \CC\ items. They are:
|
|
|
|
\begin{itemize}
|
|
\item \verb|\begin{ccClass}| and \verb|\end{ccClass}|\Eindex{ccClass}
|
|
(Section~\ref{classes})
|
|
|
|
\item \verb|\begin{ccClassTemplate}| and \verb|\end{ccClassTemplate}|%
|
|
\Eindex{ccClassTemplate} (Section~\ref{classes})
|
|
|
|
\item \verb|\begin{ccRefClass}| and \verb|\end{ccRefClass}|%
|
|
\Eindex{ccRefClass} (Section~\ref{classes})
|
|
|
|
\item \verb|\ccFunction| (Section~\ref{enums_etc})\ccIndexEntry{Function}
|
|
|
|
\item \verb|\ccMemberFunction| and \verb|\ccMethod|%
|
|
\ccIndexEntry{MemberFunction}\ccIndexEntry{Method}
|
|
(Section~\ref{member_functions})
|
|
|
|
\item \verb|\begin{ccRefFunction}| and \verb|\end{ccRefFunction}|%
|
|
\Eindex{ccRefFunction} (Section~\ref{member_functions})
|
|
|
|
\item \verb|\ccEnum|\ccIndexEntry{Enum} (Section~\ref{enums_etc})
|
|
|
|
\item \verb|\begin{ccRefEnum}| and \verb|\end{ccRefEnum}|%
|
|
\Eindex{ccRefEnum} (Section~\ref{enums_etc})
|
|
|
|
|
|
\item \verb|\ccStruct|\ccIndexEntry{Struct} (Section~\ref{enums_etc})
|
|
|
|
\item \verb|\ccTypedef|\ccIndexEntry{Typedef} (Section~\ref{enums_etc})
|
|
|
|
\item \verb|\ccVariable|\ccIndexEntry{Variable} (Section~\ref{enums_etc})
|
|
|
|
\item \verb|\begin{ccRefVariable}| and \verb|\end{ccRefVariable}|%
|
|
\Eindex{ccRefVariable} (Section~\ref{enums_etc})
|
|
|
|
\item \verb|\begin{ccRefMacro}| and \verb|\end{ccRefMacro}|%
|
|
\Eindex{ccRefMacro} (Section~\ref{macros})
|
|
|
|
\item \verb|\begin{ccRefConcept}| and \verb|\end{ccRefConcept}|%
|
|
\Eindex{ccRefConcept} (Section~\ref{concepts})
|
|
|
|
\end{itemize}
|
|
|
|
For descriptions of precisely what these commands do (and don't
|
|
do) with respect to the index, see the sections indicated after
|
|
their names.
|
|
|
|
In addition, three new environments, one for packages and two for
|
|
traits classes, have been defined to facilitate automatic indexing.
|
|
These environments are:
|
|
\begin{itemize}
|
|
\item \verb|\begin{ccPackage}{package}| \ldots
|
|
\verb|\end{ccPackage}|\Eindex{ccPackage} (Section~\ref{packages})
|
|
\item \verb|\begin{ccTraitsClass}{traits_class}{class list}{package list}|
|
|
|
|
\ldots
|
|
|
|
\verb|\end{ccTraitsClass}|\Eindex{ccTraitsClass} (Section~\ref{classes})
|
|
\item \verb|\begin{ccTraitsClassTemplate}{traits_class}{class list}{package list}|
|
|
|
|
\ldots
|
|
|
|
\verb|\end{ccTraitsClassTemplate}|\Eindex{ccTraitsClassTemplate} (Section~\ref{classes})
|
|
\end{itemize}
|
|
|
|
The package environment\index{packages} requires a single argument, which is
|
|
the name
|
|
of the package begin described. The traits class environments\index{traits classes}
|
|
each require three arguments: the first argument supplies the name
|
|
of the traits class; the second argument should be a semicolon-separated
|
|
list of classes for which this is a traits class; the third argument
|
|
should be a semicolon-separated list of packages for which this is a
|
|
traits class. For example:
|
|
\begin{verbatim}
|
|
\begin{ccTraitsClass}{traits_class}{class_1; class_2}{package}
|
|
. . . <description of traits_class> . . .
|
|
\end{ccTraitsClass}
|
|
\end{verbatim}
|
|
Note that the list of names in the second argument should be simple
|
|
class names without template parameters or any other decoration.
|
|
Either of the last two arguments for the traits class environments
|
|
may be empty.
|
|
|
|
But for the index entries produced,
|
|
the traits class environments behave exactly
|
|
the same as the {\tt ccClass} and {\tt ccClassTemplate} environments,
|
|
respectively.
|
|
|
|
In some (hopefully rare) cases, the automatic indexing that is done
|
|
by these commands may not be desirable. The following section describes how
|
|
to turn off the automatic indexing.
|
|
\index{automatic indexing|)}
|
|
|
|
\subsection{How to stop indexing}%
|
|
\index{preventing indexing|(}
|
|
\label{how_to_stop}
|
|
|
|
Any text that is designated as \verb|\ccHidden|\ccIndexEntry{Hidden} obviously
|
|
produces no index
|
|
entries, but there may be other cases when you wish to prevent commands from
|
|
producing index entries. For example, when the text of a main entry
|
|
contains a comma ({\em e.g.}, {\tt tree, segment}) it is assumed that
|
|
the text after the comma is a modifier\index{modifiers} and therefore a
|
|
cross-referencing
|
|
entry of the form ``{\tt segment tree,} {\em see} {\tt tree, segment}''
|
|
should be generated unless the text after the comma is one of ``2D'',
|
|
``3D'', or ``dD'' (Section~\ref{generic_macros}). If you do not want such
|
|
cross referencing\index{cross referencing} to
|
|
be done, then you can turn off this cross referencing using the
|
|
command \verb|\ccModifierCrossRefOff|\ccIndexEntry{ModifierCrossRefOff}.
|
|
For example:
|
|
\begin{verbatim}
|
|
\ccModifierCrossRefOff
|
|
. . .point\ccIndexMainItem{point, 9D}
|
|
\ccModifierCrossRefOn
|
|
\end{verbatim}
|
|
|
|
Also, as described in Section~\ref{how_to_index},
|
|
some commands automatically produce two entries in the index, one of which
|
|
can be considered a cross-referencing entry. To prevent the creation of
|
|
this second entry while still allowing automatic cross referencing for
|
|
text that contains modifiers, the command \verb|\ccNonmodifierCrossRefOff|\ccIndexEntry{NonmodifierCrossRefOff}
|
|
can be used. For example:
|
|
\begin{verbatim}
|
|
\ccNonmodifierCrossRefOff
|
|
. . . CH\ccIndexAbbreviation{CH}{convex hull}
|
|
\ccNonmodifierCrossRefOn
|
|
\end{verbatim}
|
|
To turn off both kinds of automatic cross referencing, the command
|
|
\verb|\ccCrossRefOff|\ccIndexEntry{CrossRefOff} should be used.
|
|
|
|
There are five pairs of commands defined in \verb|cc_manual_index.sty| for
|
|
the purpose of turning off (and on) various kinds of automatic indexing. They
|
|
are listed here roughly in order by the number of automatic
|
|
indexing commands that are affected.
|
|
\begin{itemize}
|
|
\item \verb|\ccModifierCrossRefOff|\ccIndexEntry{ModifierCrossRefOff} and
|
|
\verb|\ccModifierCrossRefOn|\ccIndexEntry{ModifierCrossRefOn}\index{modifiers!no cross referencing}
|
|
-- Commands in text that is between these two commands
|
|
will not produce cross-referencing entries for main items
|
|
that contain commas in their text (which normally indicate
|
|
modifiers following the comma).
|
|
\item \verb|\ccNonmodifierCrossRefOff|\ccIndexEntry{NonmodifierCrossRefOff} and
|
|
\verb|\ccNonmodifierCrossRefOn|\ccIndexEntry{NonmodifierCrossRefOn}\index{cross referencing!nonmodifier}
|
|
-- Commands in text that is between these two commands
|
|
will produce cross-referencing entries automatically for only those
|
|
main items that contain commas in their text.
|
|
\item \verb|\ccCrossRefOff|\ccIndexEntry{CrossRefOff} and
|
|
\verb|\ccCrossRefOn|\ccIndexEntry{CrossRefOn}\index{cross referencing!turning off}
|
|
-- Commands in text that is between these two commands
|
|
will produce NO cross-referencing entries of any kind
|
|
automatically. Thus each command produces a single entry
|
|
for the index.
|
|
\item \verb|\ccAutoIndexingOff|\ccIndexEntry{AutoIndexingOff} and
|
|
\verb|\ccAutoIndexingOn|\ccIndexEntry{AutoIndexingOn}\index{automatic indexing!turning off}
|
|
-- Commands in text that is between these two commands will
|
|
not generate index entries automatically, but any of the indexing
|
|
macros used explicitly will produce entries (including cross
|
|
references) as per usual.
|
|
\item \verb|\ccIndexingOff|\ccIndexEntry{IndexingOff} and
|
|
\verb|\ccIndexingOn|\ccIndexEntry{IndexingOn}
|
|
-- Commands in text that is between these two commands will produce
|
|
NO index entries, automatic or otherwise.
|
|
\end{itemize}
|
|
The first three pairs of commands should be used sparingly.
|
|
% and the last is
|
|
%probably useful only for debugging purposes, but is included here for
|
|
%completeness.
|
|
\index{preventing indexing|)}
|
|
|
|
\subsection{General-purpose indexing macros}%
|
|
\index{generic macros|(}
|
|
\label{generic_macros}
|
|
|
|
The general-purpose macros listed in this section are to be used for
|
|
creating items, subitems, and subsubitems in the index, as their names imply.
|
|
Each of them takes an optional argument, which should be used to
|
|
specify the category of the entry\index{generic macros!optional argument}
|
|
\index{categories of entries}. The valid values for this argument are:
|
|
\begin{itemize}
|
|
\item {\tt C[++]} (for any \CC\ name)
|
|
\item {\tt c[oncept]}
|
|
% \item {\tt d[ata structure]}
|
|
\item {\tt f[unctionality]}
|
|
\item {\tt h[int]}
|
|
\item {\tt l[ibrary]}
|
|
\item {\tt p[ackage]}
|
|
\item {\tt t[erm]}
|
|
\end{itemize}
|
|
Only the first character of this optional argument is used, so you could
|
|
use, for example, ``{\tt laugh}'' or ``{\tt lachen}'' or any other word that
|
|
begins with ``{\tt l}'' to indicate a library.
|
|
By default, the argument is blank, which indicates that the
|
|
item being indexed is one without an established category. In this
|
|
case, no formatting of any of the text arguments is done by the command,
|
|
unless fonts are provided in the text arguments.
|
|
When one of the non-default values is supplied for the argument, the
|
|
appropriate font\index{font!main item} is used to format the text
|
|
of the main item only. The default font is used for the
|
|
text of subitems\index{font!subitem}
|
|
and subsubitems\index{font!subsubitem}. If some other font is required for
|
|
the subitem or subsubitem
|
|
text, the font should be included as part of the argument. A font may also
|
|
be supplied with the main item text\index{font!main item}, in which case this
|
|
font overrides
|
|
the font that would be used for the category specified by the optional argument.
|
|
|
|
When a main item is indexed with text of the form ``{\tt item, modified}''
|
|
(or ``{\tt $\backslash$font item, modified}''),
|
|
the indexing macros will automatically generate a cross-referencing
|
|
entry of the form ``modified item, {\em see} item, modified''\index{modifiers}%
|
|
\index{cross referencing!modifiers}.
|
|
The modifier is assumed to be everything that follows the first comma in
|
|
the text. This happens for all main items with text that contains a
|
|
comma\index{commas in main text}, except in the case when the modifier is one
|
|
of ``2D'', ``3D'', or ``dD'', when no cross-referencing entry is
|
|
required\index{modifiers!2D, 3D, or dD}. If you do not want the
|
|
cross-referencing entry to appear,
|
|
either do not use a comma in the text of the main item or precede
|
|
the command by a \verb|\ccModifierCrossRefOff| or \verb|\ccCrossRefOff|
|
|
command
|
|
(Section~\ref{how_to_stop}). This former option is to be preferred.
|
|
|
|
There are four commands each for items, subitems, and subsubitems.
|
|
These commands allow you to create, for each kind of entry, a listing
|
|
with a single page number, a range of page numbers, or a boldface page
|
|
number (to indicate definitions). Additionally, there are two commands
|
|
for generating ``see also'' entries either as subitems or as subsubitems.
|
|
These entries will be listed with no associated page numbers.
|
|
|
|
\noindent{\bf Main items}%
|
|
\index{main items|(}
|
|
|
|
\begin{itemize}
|
|
\item single page number-- {\verb|\ccIndexMainItem[|{\em category\/}\verb|]{item}|}\ccIndexEntry{IndexMainItem}
|
|
% creates a main item labeled with ``item'' (and formatted
|
|
% in the appropriate font if a category argument is supplied) with
|
|
% a single page number.
|
|
\item range of pages -- {\verb|\ccIndexMainItemBegin[|{\em category\/}\verb|]{item}|}\ccIndexEntry{IndexMainItemBegin} and \\
|
|
{\verb|\ccIndexMainItemEnd[|{\em category\/}\verb|]{item}|}\ccIndexEntry{IndexMainItemEnd}\index{page range}
|
|
% create a main item labeled with ``item'' (and formatted in the
|
|
% appropriate font if a category argument is supplied) with the range
|
|
% of pages corresponding to the pages on which these two commands occur.
|
|
\item boldface page number -- {\verb|\ccIndexMainItemDef[|{\em category\/}\verb|]{item}|}\ccIndexEntry{IndexMainItemDef}\index{definition}
|
|
% creates a main item labeled with ``item'' (and formatted in the
|
|
% appropriate font if a category argument is supplied) with a single
|
|
% page number if boldface.
|
|
\end{itemize}
|
|
\index{main items|)}
|
|
|
|
\noindent{\bf Subitems}
|
|
\index{subitems|(}
|
|
\begin{itemize}
|
|
\item single page number -- {\verb|\ccIndexSubitem[|{\em category\/}\verb|]{item}{subitem}|}\ccIndexEntry{IndexSubitem}
|
|
% creates a subitem labeled ``subitem'' in the default font under the
|
|
% main item labeled ``item'' (formatted in the appropriate font if a
|
|
% category argument is supplied) with a single page number.
|
|
\item range of pages -- {\verb|\ccIndexSubitemBegin[|{\em category\/}\verb|]{item}{subitem}|}\ccIndexEntry{IndexSubitemBegin} and \\
|
|
{\verb|\ccIndexSubitemEnd[|{\em category\/}\verb|]{item}{subitem}|}\ccIndexEntry{IndexSubitemEnd}\index{page range}
|
|
|
|
% create a subitem labeled ``subitem'' in the default font under the
|
|
% main item labeled ``item'' (formatted in the appropriate font if a
|
|
% category argument is supplied) with a range of pages corresponding
|
|
% to the pages on which these two commands occur.
|
|
\item boldface page number-- {\verb|\ccIndexSubitemDef[|{\em category\/}\verb|]{item}{subitem}|}\ccIndexEntry{IndexSubitemDef}\index{definition}
|
|
% creates a subitem labeled ``subitem'' in the default font under the
|
|
% main item labeled with ``item'' (formatted in the
|
|
% appropriate font if a category argument is supplied) with a single
|
|
% page number if boldface.
|
|
\item see also entry -- {\verb|\ccIndexSubitemSeeAlso[|{\em category\/}\verb|]{item}{subitem}|}\ccIndexEntry{IndexSubitemSeeAlso}\index{see also entries!subitem}
|
|
% creates a subitem labeled ``{\em see also} subitem'' in the default font
|
|
% under the main item labeled with ``item'' (formatted in the
|
|
% appropriate font if a category argument is supplied) with no page number
|
|
% following the subitem.
|
|
\end{itemize}
|
|
\index{subitems|)}
|
|
|
|
\noindent{\bf Subsubitems}%
|
|
\index{subsubitems|(}
|
|
\begin{itemize}
|
|
\item single page number -- {\verb|\ccIndexSubsubitem[|{\em category\/}\verb|]{item}{subitem}{subsubitem}|}\ccIndexEntry{IndexSubsubitem}
|
|
\item range of pages -- {\verb|\ccIndexSubsubitemBegin[|{\em category\/}\verb|]{item}{subitem}{subsubitem}|}\ccIndexEntry{IndexSubsubitemBegin} and \\
|
|
{\verb|\ccIndexSubsubitemEnd[|{\em category\/}\verb|]{item}{subitem}{subsubitem}|}\ccIndexEntry{IndexSubsubitemEnd}\index{page range}
|
|
\item boldface page number -- {\verb|\ccIndexSubsubitemDef[|{\em category\/}\verb|]{item}{subitem}{subsubitem}|}\ccIndexEntry{IndexSubsubitemDef}\index{definition}
|
|
\item see also entry -- {\verb|\ccIndexSubsubitemSeeAlso[|{\em category\/}\verb|]{item}{subitem}{subsubitem}|}\ccIndexEntry{IndexSubsubitemSeeAlso}\index{see also entries!subsubitem}
|
|
\end{itemize}
|
|
|
|
All entries in the index, except those for abbreviations, can be
|
|
generated using the commands listed above.
|
|
However, as detailed in the following section, shortcut commands are
|
|
provided for indexing all \CC\ items and some of the non-\CC\ items, and
|
|
in some cases indexing entries are generated automatically by
|
|
the reference manual formatting commands.
|
|
\index{subsubitems|)}
|
|
\index{generic macros|)}
|
|
|
|
\section{Specific Indexing Guidelines}
|
|
\label{how_to_index}
|
|
|
|
Outlined below, for each of the categories of entries listed in
|
|
Section~\ref{what_to_index}, is a description of which pages should be
|
|
indexed, what each kind of entry will look like, which cross references will
|
|
appear, the relevant indexing macros, and, where appropriate, the commands
|
|
that generate index entries automatically. This outline should be considered
|
|
to provide only the minimum requirements for each entry; in some cases there
|
|
may be additional pages or cross references called for.
|
|
|
|
\subsection{\cgal\ \CC\ names}
|
|
\label{cgal_names}
|
|
|
|
\subsubsection{Assertion flags}%
|
|
\index{assertion flags|(}
|
|
\label{assertion_flags}
|
|
|
|
\begin{description}
|
|
\item[\bf Which pages]
|
|
|
|
The index should include a listing for any page on which:
|
|
\begin{itemize}
|
|
\item the general use of assertion flags is described;
|
|
\item the specific uses of assertion flags for
|
|
a package or class are described
|
|
({\em i.e.}, the page on which the section labeled
|
|
``Assertions'' begins).
|
|
\end{itemize}
|
|
|
|
\item {\bf What will the entry look like}
|
|
|
|
There will be a main item labeled ``assertion flags'' in the default
|
|
font. Associated with
|
|
this will be the page number where the general use of these flags is
|
|
described. Subitems under this item will correspond to the name of
|
|
packages for which a description of the use of assertion flags is
|
|
provided in the manual.
|
|
|
|
For example,
|
|
|
|
\begin{indexex}
|
|
assertion flags, 0.3 \\
|
|
\> convex hull, 2.135 \\
|
|
\> polygon, 2D, 2.3
|
|
\end{indexex}
|
|
|
|
|
|
\item {\bf Cross references}\index{cross referencing!assertion flags}
|
|
|
|
\begin{itemize}
|
|
\item The names of the assertion flags mentioned in the
|
|
manual will have main entries of their own.
|
|
\item Under each package or class name for which the use of
|
|
assertion flags is mentioned in the manual, there will be
|
|
a subitem labeled ``assertion flags''.
|
|
\end{itemize}
|
|
|
|
For the example above, the cross references would be:
|
|
|
|
\begin{indexex}
|
|
\ccc{\ccFont CGAL_CH_CHECK_EXPENSIVE}, 2.135 \\
|
|
... \\
|
|
\ccc{\ccFont CGAL_POLYGON_NO_PRECONDITIONS}, 2.3 \\
|
|
... \\
|
|
convex hull, 2.135 \\
|
|
\> assertion flags, 2.135 \\
|
|
... \\
|
|
\ccc{\ccFont Polygon_2}, 2.3 \\
|
|
\> assertion flags, 2.3 \\
|
|
\end{indexex}
|
|
|
|
\item {\bf Automatic indexing commands}
|
|
|
|
None
|
|
|
|
\item {\bf Relevant indexing macros}
|
|
\begin{itemize}
|
|
\item{\verb|\ccIndexAssertionFlagsUse|}\ccIndexEntry{IndexAssertionFlagsUse}
|
|
creates a main item labeled ``assertion flags'' in the default
|
|
font. This should be used to index the page on which the
|
|
general use of assertion flags in \cgal\ is explained.
|
|
|
|
\item{\verb|\ccIndexAssertionFlagName{FLAG_NAME}|}\ccIndexEntry{IndexAssertionFlagName}
|
|
creates a main item labeled \ccc{\ccFont FLAG_NAME} in
|
|
\verb|\ccFont|.
|
|
|
|
\item{\verb|\ccIndexAssertionFlag[package name]|}\ccIndexEntry{IndexAssertionFlag}
|
|
creates a subitem labeled with the package name in the default
|
|
font under the main item ``assertion flags'' and creates a
|
|
subitem labeled ``assertion flags'' under the current
|
|
environment's package or class name. This macro must be used
|
|
inside a class environment or a {\tt ccPackage} environment.
|
|
If cross referencing has been turned off using the
|
|
\verb|\ccCrossRefOff| command (Section~\ref{how_to_stop}),
|
|
the entry under
|
|
the main item ``assertion flags'' will not be generated.
|
|
|
|
NOTE: When used in a class environment, the package
|
|
name must be supplied as the value of the optional argument
|
|
({\em e.g.}, \verb|\ccIndexAssertionFlag[polygon, 2D]|). This
|
|
argument is ignored when inside a package environment.
|
|
\end{itemize}
|
|
|
|
|
|
\end{description}
|
|
|
|
\index{assertion flags|)}
|
|
\subsubsection{Classes}
|
|
\index{classes|(}
|
|
\label{classes}
|
|
|
|
\begin{description}
|
|
\item{\bf Which pages}
|
|
|
|
The index should include a listing for any page on which:
|
|
\begin{itemize}
|
|
\item the class description begins;
|
|
\item the class description ends;
|
|
\item an explanation or use of the class is given,
|
|
if separated from the class description.
|
|
\end{itemize}
|
|
|
|
\item{\bf What will the entry look like}
|
|
|
|
The class name will be a main item in \verb|\ccFont|, followed by
|
|
the range of pages that the class description spans.
|
|
|
|
Each class's main entry will have as many of the following subitems as
|
|
are appropriate (and perhaps others):
|
|
\begin{itemize}
|
|
\item assertion flags
|
|
\item creation
|
|
\item design
|
|
\item global functions
|
|
\begin{itemize}
|
|
\item names of groups of operations ({\em e.g.},
|
|
utilities, convexity checking)
|
|
\end{itemize}
|
|
\item implementation
|
|
\item member functions
|
|
\begin{itemize}
|
|
\item names of groups of operations ({\em e.g.},
|
|
for \ccc{\ccFont Polygon_2} traversal,
|
|
predicates, random access, input, output)
|
|
\end{itemize}
|
|
\item nested classes
|
|
\item requirements
|
|
\item traits class
|
|
\begin{itemize}
|
|
\item default
|
|
\item requirements
|
|
\item ``see also'' reference to name of traits class\index{see also entries!traits class}
|
|
\end{itemize}
|
|
\item types
|
|
\end{itemize}
|
|
The entries for ``global functions'' and ``member functions'' should
|
|
each be indexed using the range of pages on which the listing of the two
|
|
corresponding groups of functions are given.
|
|
|
|
For example, the entry for \ccc{\ccFont Polygon_2} would
|
|
look something like this:
|
|
\begin{indexex}
|
|
\ccc{\ccFont{Polygon_2}}, 2.3--2.16 \\
|
|
\> assertion flags, 2.3 \\
|
|
\> creation, 2.5 \\
|
|
\> global functions, 2.9--2.10 \\
|
|
\>\> input, 2.10 \\
|
|
\>\> output, 2.10 \\
|
|
\> implementation, 2.11 \\
|
|
\> member functions, 2.5--2.9 \\
|
|
\>\> predicates, 2.7 \\
|
|
\>\> random access, 2.5 \\
|
|
\>\> traversal, 2.6 \\
|
|
\> traits class, 2.3 \\
|
|
\>\> default, 2.16 \\
|
|
\>\> requirements, 2.14 \\
|
|
\>\> {\em see also} \ccc{\ccFont Polygon_traits_2} \\
|
|
\end{indexex}
|
|
|
|
|
|
\item {\bf Cross references}\index{cross referencing!classes}
|
|
|
|
\begin{itemize}
|
|
\item The assertion flags entry will be a subitem under the
|
|
``assertion flags'' main item.
|
|
\item The names of the member functions of the class
|
|
will be main items with the class name as a subitem.
|
|
\item The names of the global functions will be main items
|
|
without subitems, referring the reader to the page on
|
|
which the function specification is given.
|
|
\item The names of the groups of functions will be main items
|
|
with the class name as a subitem.
|
|
\item The names of the traits classes will be listed as
|
|
main items, just as for other classes.
|
|
\item The names of any example classes or default classes
|
|
will be listed as main items.
|
|
\end{itemize}
|
|
For the sample entry for \ccc{\ccFont Polygon_2},
|
|
an example of each kind of applicable cross reference is shown here:
|
|
\begin{indexex}
|
|
assertion flags \\
|
|
\> \ccc{\ccFont Polygon_2}, 2.3 \\
|
|
... \\
|
|
\ccc{\ccFont bbox} \\
|
|
\> \ccc{\ccFont Polygon_2}, 2.9 \\
|
|
... \\
|
|
input \\
|
|
\> \ccc{\ccFont Polygon_2}, 2.10 \\
|
|
... \\
|
|
\ccc{\ccFont Polygon_traits_2}, 2.16 \\
|
|
... \\
|
|
\ccc{\ccFont transform}, 2.10 \\
|
|
\end{indexex}
|
|
|
|
\item {\bf Automatic indexing commands}\index{automatic indexing}{classes}
|
|
\begin{itemize}
|
|
\item \verb|\begin{ccClass}{class_name}|\Eindex{ccClass} \ldots \verb|\end{ccClass}|; \\
|
|
\verb|\begin{ccClassTemplate}{class_name}|\Eindex{ccClassTemplate} \ldots
|
|
\verb|\end{ccClassTemplate}| \\
|
|
\verb|\begin{ccRefClass}{class_name}|\Eindex{ccRefClass} \ldots
|
|
\verb|\end{ccRefClass}|
|
|
|
|
When you enter a {\tt ccClass}, {\tt ccClassTemplate}, or
|
|
{\tt ccRefClass}
|
|
environment an index entry is automatically generated
|
|
to specify the beginning page number for the
|
|
class description. Similarly, when you leave one of these
|
|
environments, an index entry indicating the end of the page
|
|
range is automatically generated.
|
|
|
|
\item \verb|\begin{ccTraitsClass}{traits_class}{class list}{package list}|\Eindex{ccTraitsClass}\index{traits class!class}\index{traits class!package} \\
|
|
\ldots \\
|
|
\verb|\end{ccTraitsClass}|; \\
|
|
\verb|\begin{ccTraitsClassTemplate}{traits_class}{class list}{package list}|\Eindex{ccTraitsClassTemplate} \\
|
|
\ldots \\
|
|
\verb|\end{ccTraitsClassTemplate}|
|
|
|
|
Note that these two environments each have three arguments.
|
|
The first argument is used to supply the name of the traits class.
|
|
The second argument is used to supply the names of the classes
|
|
for which this is a traits class. The class names should be
|
|
separated by semicolons and should not contain template parameters.
|
|
The third argument is the list of packages for which this class
|
|
is a traits class. The names in this list should also be separated
|
|
by semicolons. Either list may be empty.
|
|
|
|
When you enter one of these traits class environments, the
|
|
main index entry for the traits class is generated just as for the
|
|
other two class environments. In addition, a subsubitem labeled
|
|
``{\em see also} \ccc{traits_class}''\index{see also entries!traits class} is
|
|
created for each class and package for which this is a traits
|
|
class under the subitem labeled ``traits class'', unless cross
|
|
referencing has been turned off (Section~\ref{how_to_stop})\index{cross referencing!traits classes}.
|
|
|
|
For example, the following
|
|
commands will result in the creation of a single entry in the
|
|
index -- the main entry for \ccc{traits_class}\ccIndexEntry{NonmodifierCrossRefOff}.
|
|
\begin{verbatim}
|
|
\ccNonmodifierCrossRefOff
|
|
\begin{ccTraitsClass}{traits_class}{}{package}
|
|
\ccNonmodifierCrossRefOn
|
|
. . . <description of traits_class> . . .
|
|
\end{ccTraitsClass}
|
|
\end{verbatim}
|
|
(The same effect
|
|
could be achieved by using \verb|\ccCrossRefOff| and
|
|
\verb|\ccCrossRefOn| instead of \verb|\ccNonmodifierCrossRefOff|
|
|
and \verb|\ccNonmodifierCrossRefOn|.)
|
|
|
|
|
|
\item \verb|\ccMemberFunction|\ccIndexEntry{MemberFunction} and
|
|
\verb|\ccMethod|\ccIndexEntry{Method} --
|
|
These macros automatically generate a subitem for the
|
|
current class under the main item
|
|
labeled with the function name or operator. This is true
|
|
for all functions and operators except type conversion operators.
|
|
|
|
\item \verb|\begin{ccRefFunction}[class::]{function_name}|\Eindex{ccRefFunction} \ldots
|
|
\verb|\end{ccRefFunction}|
|
|
|
|
This environment will automatically generate a subitem for the
|
|
{\tt function\_name} under the main item for {\tt class} with the
|
|
page numbers associated with the range of pages on which the
|
|
\verb|\begin| and \verb|\end| commands appear. If
|
|
the optional argument, {\tt class}, is not provided, the function
|
|
is assumed to be a global function, and a main entry
|
|
is created for the function name with the associated range of
|
|
pages.
|
|
\end{itemize}
|
|
|
|
|
|
\item {\bf Relevant indexing macros}
|
|
|
|
The entries for the member functions are produced by the command
|
|
\begin{itemize}
|
|
\item{\verb|\ccIndexMemberFunction{function_name}|}\ccIndexEntry{IndexMemberFunction}
|
|
\end{itemize}
|
|
which creates a main item that is the function name (with no
|
|
associated page number) with a subitem that is the current class
|
|
name (with the proper page number). Both the function name and class
|
|
name are displayed in \verb|\ccFont|.
|
|
|
|
Because classes and packages may have similar subitems and subsubitems,
|
|
the macros for indexing classes have been divided into
|
|
two groups: those exclusively for classes and those that may be used
|
|
for packages or classes. These macros must be used with class or
|
|
package environments.
|
|
There are also two macros to be used for generating the subsubitems
|
|
for traits classes of a package or class. These macros do not
|
|
require you to be within any certain environment.
|
|
|
|
For any entries that are not handled by the following commands,
|
|
the generic indexing macros (Section~\ref{generic_macros}) should
|
|
be used with ``{\tt C}'' provided as the value of the optional
|
|
argument.
|
|
|
|
\noindent
|
|
{\bf Macros for Classes Only}
|
|
|
|
\begin{itemize}
|
|
\item \verb|\begin{ccIndexClass}{class_name}|\Eindex{ccIndexClass} \ldots
|
|
\verb|\end{ccIndexClass}|
|
|
|
|
This environment requires one argument,
|
|
which is the name of the class being indexed. This environment
|
|
generates an index entry labeled with the class name and with
|
|
a page range corresponding to the pages on which the
|
|
\verb|\begin| and \verb|\end| commands appear. This should be
|
|
used only when the automatic indexing done by the other class
|
|
environments is not what you want.
|
|
\end{itemize}
|
|
|
|
In order to use the following five commands, the variable
|
|
\verb|\ccIndexClassName|\ccIndexEntry{IndexClassName} must be nonempty.
|
|
This generally means the commands must be used inside one of the
|
|
environments that define this variable, namely: {\tt ccIndexClass},
|
|
{\tt ccClass}, {\tt ccRefClass},
|
|
{\tt ccClassTemplate}, {\tt ccTraitsClass},
|
|
{\tt ccTraitsClassTemplate}, or {\tt ccRefConcept}\footnote{This is for
|
|
the case when the description of a concept mimics the description of
|
|
a class.}. You may also define this variable
|
|
yourself before using one of these commands if the commands must
|
|
be used outside one of these environments.
|
|
|
|
\begin{itemize}
|
|
\item{\verb|\ccIndexClassCreation|}\ccIndexEntry{IndexClassCreation}\index{creation, of class}
|
|
creates a subitem labeled ``creation'' in the default font under
|
|
the current class's main item.
|
|
|
|
\item{\verb|\ccIndexClassDefault|}\ccIndexEntry{IndexClassDefault}
|
|
creates a subitem labeled ``default'' in the default font under
|
|
the current class's main item.
|
|
|
|
\item{\verb|\begin{ccIndexMemberFunctions}|}\Eindex{ccIndexMemberFunctions} \ldots
|
|
{\verb|\end{ccIndexMemberFunctions}|}\index{member functions}
|
|
This environment creates a ``member functions'' subitem in the
|
|
default font under
|
|
the current class's main item with a page range corresponding
|
|
to the pages on which these two commands appear.
|
|
|
|
\item{\verb|\ccIndexMemberFunctionGroup{group}|}\ccIndexEntry{IndexMemberFunctionGroup}\index{member function group}
|
|
creates a subsubitem under the current class's
|
|
``member functions'' subitem labeled with the text ``group'' in
|
|
the default font.\index{cross referencing!member function group}
|
|
This macro also creates a main item with text ``group'' in the
|
|
default font (and no associated page number) and subitem
|
|
\verb|\ccPureClassName| in \verb|\ccFont| with the appropriate
|
|
page number unless cross referencing has been turned off
|
|
(Section~\ref{how_to_stop}).
|
|
|
|
\item{\verb|\ccIndexNestedClasses|}\ccIndexEntry{IndexNestedClasses}\index{nested classes}
|
|
creates a subitem labeled ``nested classes'' in the default font
|
|
under the current class's main item.
|
|
|
|
\item{\verb|\ccIndexClassTypes|}\ccIndexEntry{IndexClassTypes}\index{types, in classes}
|
|
creates a subitem labeled ``types'' in the default font
|
|
under the current class's main item.
|
|
|
|
\end{itemize}
|
|
|
|
\noindent
|
|
{\bf Macros for Classes or Packages or Concepts}%
|
|
\index{packages|(}
|
|
|
|
The following five commands and one environment can be used to
|
|
create subitems and subsubitems under either a package
|
|
or a class
|
|
main item. They require that you be in one of the class environments,
|
|
the {\tt ccRefConcept} environment,
|
|
or a {\tt ccPackage} environment (Section~\ref{packages}).
|
|
(Since there are only two variables --
|
|
\verb|\ccIndexClassName|\ccIndexEntry{IndexClassName} and
|
|
\verb|\ccIndexPackageName|\ccIndexEntry{IndexPackageName} -- used to store
|
|
the names of the current class (or concept) and package being indexed,
|
|
it is generally not a good idea to nest package or class environments.
|
|
But if you happen to have a package
|
|
environment inside a class environment, the commands will generate
|
|
entries for the class. Otherwise, the commands generate entries for
|
|
the most deeply nested environment.)
|
|
|
|
\begin{itemize}
|
|
\item{\verb|\ccIndexAssertionFlag[package name]|}\ccIndexEntry{IndexAssertionFlag}\index{assertion flags}
|
|
creates a subitem labeled with the package name in the default
|
|
font under the main item ``assertion flags'' and creates a
|
|
subitem labeled ``assertion flags'' under the current
|
|
environment's package or class name. The former entry is not
|
|
generated if cross referencing has been turned off
|
|
(Section~\ref{how_to_stop}).\index{cross referencing!assertion flags}
|
|
|
|
NOTE: When this command is used in a class environment, the
|
|
package name must be supplied as the value of the optional
|
|
argument
|
|
({\em e.g.}, \verb|\ccIndexAssertionFlag[polygon, 2D]|).
|
|
This argument is optional because for packages it is not
|
|
required (and is ignored), but it is not optional for classes.
|
|
It must be supplied.
|
|
|
|
\item{\verb|\ccIndexDesign|}\ccIndexEntry{IndexDesign}\index{design, package or class}
|
|
creates a subitem labeled ``design'' under the current
|
|
package or class name.
|
|
|
|
\item{\verb|\begin{ccIndexGlobalFunctions}|} \ldots
|
|
{\verb|\end{ccIndexGlobalFunctions}|}%
|
|
\Eindex{ccIndexGlobalFunctions}%
|
|
\index{global functions!package or class}
|
|
create a subitem labeled ``global functions'' under the package or
|
|
class name with a page range corresponding to the pages on which
|
|
these two commands appear.
|
|
|
|
\item{\verb|\ccIndexGlobalFunctionGroup{group}|}%
|
|
\ccIndexEntry{IndexGlobalFunctionGroup}%
|
|
\index{global function group, package or class}
|
|
creates a subsubitem under the current package or class name
|
|
main item and ``global functions'' subitem labeled with the
|
|
text ``group''
|
|
in the default font. This macro also creates a main item with
|
|
text ``group'' in the default font and a subitem that is the
|
|
current package or class name, unless cross referencing has
|
|
been turned off (Section~\ref{how_to_stop}).\index{cross referencing!global function group}
|
|
|
|
\item{\verb|\ccIndexImplementation|}%
|
|
\ccIndexEntry{IndexImplementation}\index{implementation, package or class}
|
|
creates a subitem ``implementation'' displayed in the default font
|
|
under the current package or class name.
|
|
|
|
\item{\verb|\ccIndexRequirements|}\ccIndexEntry{IndexRequirements}\index{requirements!package or class}
|
|
creates a subitem labeled ``requirements'' in the default font
|
|
under the current package or class name.
|
|
\end{itemize}%
|
|
\index{packages|)}
|
|
|
|
\noindent
|
|
{\bf Macros for Traits Classes}%
|
|
\index{traits classes|(}
|
|
|
|
The main entry for a traits class should be created just as for any
|
|
other class by using the appropriate macros listed above. If the
|
|
automatic indexing done upon entering a traits class environment
|
|
is not what you want, the following two commands can be used to
|
|
generate the page range for the trait class's main entry and the
|
|
cross-referencing entries for associated classes and packages
|
|
\begin{itemize}
|
|
\item \verb|\ccIndexTraitsClassBegin{traits_class}{class list}{package list}|\ccIndexEntry{IndexTraitsClassBegin} and \\
|
|
\verb|\ccIndexTraitsClassEnd|\ccIndexEntry{IndexTraitsClassEnd}
|
|
|
|
\end{itemize}
|
|
The argument specifications are the same as for the traits class
|
|
environments (Section~\ref{auto_index}), but the traits class name
|
|
supplied as the first argument should not contain template parameters.
|
|
|
|
In addition, the following two macros should be used to create the
|
|
appropriate subitems under the relevant package or class item.
|
|
Both commands have an optional first argument that is used to indicate
|
|
whether the traits class is associated with a package or a class and
|
|
must have a value of either ``{\tt p[ackage]}'' or ``{\tt C[++]}''.
|
|
The default value is ``{\tt C}''.
|
|
|
|
\begin{itemize}
|
|
|
|
\item{\verb|\ccIndexTraitsClassDefault[p_or_C]{associated class or package}|}\ccIndexEntry{IndexTraitsClassDefault}\index{default traits class}
|
|
creates an entry labeled ``default'' displayed in the default
|
|
font under the
|
|
subitem ``traits class'' under the main item labeled with the
|
|
package or class name associated with this traits class.
|
|
|
|
|
|
\item{\verb|\ccIndexTraitsClassRequirements[p_or_C]{associated class or package}|}\ccIndexEntry{IndexTraitsClassRequirements}\index{requirements!traits class}
|
|
creates a subsubitem under the package or class name main item and
|
|
``traits class'' subitem labeled ``requirements'' in the default
|
|
font.
|
|
\end{itemize}
|
|
\index{traits classes|)}
|
|
|
|
|
|
|
|
\end{description}
|
|
|
|
\index{classes|)}
|
|
\subsubsection{Enums,
|
|
enum tags,
|
|
global structs,
|
|
global variables,
|
|
% global constants,
|
|
global functions,
|
|
typedefs}%
|
|
\index{enums|(}%
|
|
\index{enum tags|(}%
|
|
\index{structs, global|(}%
|
|
\index{variables, global|(}%
|
|
\index{functions!global|see{global functions}}
|
|
\index{global functions|(}%
|
|
\index{typedefs|(}%
|
|
\label{enums_etc}
|
|
|
|
\begin{description}
|
|
\item{\bf Which pages}
|
|
|
|
The index should include a listing for any page on which:
|
|
\begin{itemize}
|
|
\item the item is introduced and described;
|
|
\item an explanation or use of the item is given, if the
|
|
explanation is separated from the introduction.
|
|
\end{itemize}
|
|
\item{\bf What will the entry look like}
|
|
|
|
Each of these items will be indexed in \verb|\ccFont| as a main
|
|
item with no subitems, followed by the page numbers indicated above.
|
|
For example:
|
|
\begin{indexex}
|
|
\ccc{\ccFont cartesian_to_homogeneous}, 1.15 \\
|
|
\ccc{\ccFont CLOCKWISE}, 1.7 \\
|
|
\ccc{\ccFont COLLINEAR}, 1.7 \\
|
|
\ccc{\ccFont Comparison_result}, 1.8 \\
|
|
\ccc{\ccFont COPLANAR}, 1.7 \\
|
|
\ccc{\ccFont COUNTERCLOCKWISE}, 1.7
|
|
\end{indexex}
|
|
|
|
\item {\bf Cross references}
|
|
|
|
None
|
|
|
|
\item {\bf Automatic indexing commands}%
|
|
|
|
\begin{itemize}
|
|
\item \verb|\ccEnum|\ccIndexEntry{Enum}%
|
|
\index{automatic indexing!enums}
|
|
produces main entries for the enum and the enum tags.
|
|
|
|
\item \verb|\begin{ccRefEnum}[class::]{enum_name}|\Eindex{ccRefEnum}
|
|
\ldots
|
|
\verb|\end{ccRefEnum}|
|
|
This environment will automatically generate a subitem for the
|
|
{\tt enum\_name} under the main item for {\tt class} with the
|
|
page numbers associated with the range of pages on which the
|
|
``begin'' and ``end'' commands appear. If
|
|
the optional argument, {\tt class}, is not provided, the enum
|
|
is assumed to be a global enum, and a main entry
|
|
will be created for the enum with the associated range of pages.
|
|
|
|
\item \verb|\ccFunction|\ccIndexEntry{Function}
|
|
\index{automatic indexing!global functions}%
|
|
produces a main entry in the index labeled with the function
|
|
name and the appropriate page number for all functions
|
|
that are not operators. For the behavior with operators,
|
|
see Section~\ref{global_operators}.
|
|
|
|
\item \verb|\ccStruct|\ccIndexEntry{Struct}%
|
|
\index{automatic indexing!structs}
|
|
produces a main entry for the name of the struct.
|
|
|
|
\item \verb|\ccTypedef|\ccIndexEntry{Typedef}%
|
|
\index{automatic indexing!typedefs}
|
|
produces a main entry for the name of the defined type.
|
|
|
|
\item \verb|\ccVariable|\ccIndexEntry{Variable}%
|
|
\index{automatic indexing!variables}
|
|
produces a main entry for the name of the variable.
|
|
\end{itemize}
|
|
|
|
\item {\bf Relevant indexing macros}
|
|
|
|
\begin{itemize}
|
|
\item{\verb|\ccIndexEnum{Enum_name}|}\ccIndexEntry{IndexEnum}
|
|
\item{\verb|\ccIndexEnumTag{ENUM_TAG_NAME}|}\ccIndexEntry{IndexEnumTag}
|
|
\item{\verb|\ccIndexGlobalStruct{struct_name}|}\ccIndexEntry{IndexGlobalStruct}
|
|
\item{\verb|\ccIndexGlobalVariable{variable_name}|}\ccIndexEntry{IndexGlobalVariable}
|
|
% \item{\verb|\ccIndexGlobalConstant{CONSTANT_NAME}|}\ccIndexEntry{IndexGlobalConstant}
|
|
\item{\verb|\ccIndexGlobalFunction{Function_name}|}\ccIndexEntry{IndexGlobalFunction}
|
|
\item{\verb|\ccIndexTypedef{Typedef_name}|}\ccIndexEntry{IndexTypedef}
|
|
\end{itemize}
|
|
|
|
Each of these commands produces a main entry in the index with the
|
|
text supplied as the argument displayed in \verb|\ccFont|.
|
|
|
|
\end{description}%
|
|
\index{enums|)}%
|
|
\index{enum tags|)}%
|
|
\index{structs, global|)}%
|
|
\index{variables, global|)}%
|
|
\index{global functions|)}%
|
|
\index{typedefs|)}%
|
|
|
|
\subsubsection{Global operators}%
|
|
\index{operators!global|(}
|
|
\label{global_operators}
|
|
|
|
\begin{description}
|
|
\item{\bf Which pages}
|
|
|
|
The index should include a listing for any page on which:
|
|
\begin{itemize}
|
|
\item the operator is introduced;
|
|
\item an explanation or use of the operator is given, if the
|
|
explanation is separated from the introduction.
|
|
\end{itemize}
|
|
\item{\bf What will the entry look like}
|
|
|
|
Each operator will appear as a main item in \verb|\ccFont| with
|
|
no associated page number. There will be a subitem for the name
|
|
of the class of (one of the) object(s) on which this operator
|
|
operates, followed
|
|
by a page number on which the function description is given.
|
|
|
|
For example:
|
|
\begin{indexex}
|
|
\ccc{!=} \\
|
|
\> \ccc{Polygon_2}, 2.10 \\
|
|
\ccc{>>} \\
|
|
\> \ccc{Polygon_2}, 2.10
|
|
\end{indexex}
|
|
|
|
\item{\bf Cross references}
|
|
|
|
None
|
|
|
|
\item{\bf Automatic indexing commands}\index{automatic indexing!global operators}
|
|
\begin{itemize}
|
|
\item \verb|\ccFunction|\ccIndexEntry{Function}
|
|
produces, for operators, a main entry in the index labeled
|
|
with the operator and a subitem under this labeled with the
|
|
first templated type name in the parameter list. If there
|
|
are no templated parameters, a subitem will be produced for
|
|
the first type name.
|
|
\end{itemize}
|
|
|
|
\item{\bf Relevant indexing macros}
|
|
\begin{itemize}
|
|
\item{\verb|\ccIndexGlobalOperator{operator}{class_name}|}\ccIndexEntry{IndexGlobalOperator}
|
|
\end{itemize}
|
|
This macro produces a subitem labeled with the supplied class
|
|
name under a main item labeled with the operator symbol; both
|
|
items are displayed in \verb|\ccFont|. Care should be taken when
|
|
using this macro for operators that contain one of the characters
|
|
that have special meaning either for the {\tt makeindex} program
|
|
(\verb+@, !, |+) or for \LaTeX\ in general (\verb+&, %, ^, ~+).
|
|
\end{description}
|
|
\index{operators!global|)}
|
|
|
|
\subsubsection{Macros}%
|
|
\index{macros|(}
|
|
\label{macros}
|
|
|
|
\begin{description}
|
|
\item{\bf Which pages}
|
|
|
|
The index should include a listing for any page on which
|
|
\begin{itemize}
|
|
\item a macro is described;
|
|
\item an explanation of a use of the macro is
|
|
given, if the explanation is separated from the introduction
|
|
of the macro.
|
|
\end{itemize}
|
|
\item{\bf What will the entry look like}
|
|
|
|
Each macro name will be a main entry displayed in \verb|\ccFont|.
|
|
For example
|
|
\begin{indexex}
|
|
\>\ccc{for_all}, 2.45\\
|
|
\end{indexex}
|
|
|
|
\item{\bf Cross references}
|
|
|
|
None.
|
|
|
|
\item{\bf Automatic indexing commands}\index{automatic indexing!macros}
|
|
\begin{itemize}
|
|
\item \verb|\begin{ccRefMacro}[class::]{macro_name}|\Eindex{ccRefMacro} \ldots
|
|
\verb|\end{ccRefMacro}|
|
|
This environment will automatically generate a subitem for the
|
|
{\tt macro\_name} under the main item for {\tt class} with the
|
|
range of pages designated by the pages on which the
|
|
\verb|\begin| and \verb|\end| commands appear. If
|
|
the optional argument, {\tt class}, is not provided, the macro
|
|
is assumed to be a global macro, and a main entry
|
|
is created for the macro with the associated range of
|
|
pages.
|
|
\end{itemize}
|
|
|
|
\item{\bf Relevant indexing macros}
|
|
\begin{itemize}
|
|
\item \verb|\ccIndexMacro{macro_name}|\ccIndexEntry{IndexMacro}
|
|
creates a main entry with text ``macro\_name'' displayed in
|
|
\verb|\ccFont| and the associated page number.
|
|
\end{itemize}
|
|
\end{description}%
|
|
\index{macros|)}
|
|
|
|
\subsubsection{Member functions}%
|
|
\index{functions!member|see{member functions}}
|
|
\index{methods|see{member functions}}
|
|
\index{operator member functions|see{member functions}}
|
|
\index{member functions|(}
|
|
\label{member_functions}
|
|
|
|
\begin{description}
|
|
\item{\bf Which pages}
|
|
|
|
The index should include a listing for any page on which:
|
|
\begin{itemize}
|
|
\item the member function is introduced;
|
|
\item an explanation of a use of the function is
|
|
given, if the explanation is separated from the introduction
|
|
of the function.
|
|
\end{itemize}
|
|
\item{\bf What will the entry look like}
|
|
|
|
Each member function will be indexed as a main item in \verb|\ccFont|
|
|
with no associated page number. There will be a subitem for the name
|
|
of each class with a member function by that name followed by
|
|
the page number on which the member function's description is given
|
|
for that class.
|
|
|
|
For example:
|
|
\begin{indexex}
|
|
\ccc{\ccFont cartesian} \\
|
|
\> \ccc{\ccFont Point_2}, 1.14 \\
|
|
\> \ccc{\ccFont Vector_2}, 1.18 \\
|
|
\> ...
|
|
\end{indexex}
|
|
|
|
\item {\bf Cross references}
|
|
|
|
None
|
|
|
|
\item {\bf Automatic indexing commands}\index{automatic indexing!member functions}
|
|
|
|
\begin{itemize}
|
|
\item \verb|\ccMemberFunction|\ccIndexEntry{MemberFunction} and
|
|
\verb|\ccMethod|\ccIndexEntry{Method}
|
|
produce a main entry in the index labeled with the function
|
|
name and with the class name as a subitem. All functions
|
|
and operators are indexed except the type
|
|
conversion operators\index{operators!type conversion}.
|
|
|
|
\item \verb|\begin{ccRefFunction}[class::]{function_name}|%
|
|
\Eindex{ccRefFunction} \ldots
|
|
\verb|\end{ccRefFunction}|
|
|
This environment will automatically generate a subitem for the
|
|
{\tt function\_name} under the main item for {\tt class} with the
|
|
page numbers corresponding to the pages on which the
|
|
\verb|\begin| and \verb|\end| commands appear. If
|
|
the optional argument, {\tt class}, is not provided, the function
|
|
is assumed to be a global function, and a main entry
|
|
is created for the function name with the associated range of
|
|
pages.
|
|
\end{itemize}
|
|
|
|
|
|
\item {\bf Relevant indexing macros}
|
|
|
|
\begin{itemize}
|
|
\item{\verb|\ccIndexMemberFunction{function_name}|}\ccIndexEntry{IndexMemberFunction}
|
|
creates a main item that is the function name (without an
|
|
associated page number) with a subitem that is the current
|
|
class name (with the proper page number). Both the main
|
|
item and subitem are displayed in \verb|\ccFont|. This
|
|
macro must be used inside a class environment.
|
|
|
|
\end{itemize}
|
|
|
|
\end{description}
|
|
\index{member functions|)}
|
|
|
|
|
|
\subsection{Things in the \cgal\ Reference Manual without \CC\ names}
|
|
|
|
There are no automatic indexing commands for items without \CC\ names
|
|
other than the cross referencing that occurs for main item text containing
|
|
modifiers (Section~\ref{generic_macros}), for abbreviations and the indexing
|
|
done for concepts described in a {\tt ccRefConcept} environment, as described
|
|
below.
|
|
|
|
\subsubsection{Abbreviations}%
|
|
\index{abbreviations|(}
|
|
\label{abbreviations}
|
|
|
|
\begin{description}
|
|
\item {\bf Which pages}
|
|
|
|
None
|
|
|
|
\item {\bf What will the entry look like}
|
|
|
|
The abbreviation will be a main item in the default font with a
|
|
subitem that is ``see Unabbreviated Name''. For example:
|
|
\begin{indexex}
|
|
CH, {\em see} convex hull \\
|
|
\end{indexex}
|
|
In this way, the index also serves as a glossary for
|
|
important abbreviations used in the library.
|
|
|
|
\item {\bf Cross references}\index{cross referencing!abbreviations}
|
|
|
|
\begin{itemize}
|
|
\item The unabbreviated name will be listed as a main item.
|
|
\end{itemize}
|
|
|
|
\item {\bf Relevant indexing macros}
|
|
|
|
\begin{itemize}
|
|
\item{\verb|\ccIndexAbbreviation{ABBR}{unabbreviated text}|}\ccIndexEntry{IndexAbbreviation}
|
|
creates a main item that is the abbreviation in
|
|
\verb|\ccIndexAbbreviationFont|
|
|
followed by a ``{\em see} unabbreviated text'' reference
|
|
in the default font. This macro also creates
|
|
a main item for ``unabbreviated text'' in the default font
|
|
with the appropriate page number\index{cross referencing!abbreviations}, unless cross
|
|
referencing has been turned off (Section~\ref{how_to_stop}).
|
|
\end{itemize}
|
|
\end{description}%
|
|
\index{abbreviations|)}
|
|
|
|
\subsubsection{Concepts}%
|
|
\index{concepts|(}
|
|
\label{concepts}
|
|
|
|
\begin{description}
|
|
\item{\bf Which pages}
|
|
|
|
The index should include a listing for any page on which:
|
|
\begin{itemize}
|
|
\item the concept is introduced and defined;
|
|
\item the concept is employed or explained
|
|
further, if separated from the introduction.
|
|
\end{itemize}
|
|
\item{\bf What will the entry look like}
|
|
|
|
The concept will be a main item in the default font with which the
|
|
above page numbers
|
|
are listed. The page number where the concept is defined will be in
|
|
boldface. There should be subitems referring readers to specific
|
|
\cgal\ instances of the concepts or basic functionalities that
|
|
can be achieved for the concept.
|
|
|
|
There may also be subitems for variations on a concept, as in
|
|
this example:
|
|
\begin{indexex}
|
|
representation class, {\bf 1.3} \\
|
|
\> \ccc{\ccFont Cartesian}, 1.4 \\
|
|
\> choosing, 1.5 \\
|
|
\> \ccc{\ccFont Homogeneous}, 1.4 \\
|
|
\end{indexex}
|
|
|
|
However,
|
|
to make it easier to stay within the three nesting levels available,
|
|
distinctions among variations (such as
|
|
2D, 3D, and dD, or range trees, segment trees, multilayer trees,
|
|
and KD-trees) should usually be done using
|
|
modifiers\index{modifiers} instead of subitems. The modifier will be
|
|
placed after the concept name and separated from it with a comma, as in
|
|
the following example:
|
|
\begin{indexex}
|
|
point, 2D, {\bf 1.11}, 1.13 \\
|
|
\> conversion between representations, 1.15 \\
|
|
\> conversion to/from vector, 1.20\\
|
|
\> {\em see also} \ccc{\ccFont Point_2} \\
|
|
point, 3D, {\bf 1.57}, 1.59 \\
|
|
\> ... \\
|
|
\> {\em see also} \ccc{\ccFont Point_3}\\
|
|
point, dD, {\bf 1.??}, 1.?? \\
|
|
\> ... \\
|
|
\end{indexex}
|
|
|
|
In the case when a concept's description mimics that of a class,
|
|
the index entries for the concept should mimic those of a class, and
|
|
the indexing macros described in Section~\ref{classes} should be used
|
|
to produce this entry.
|
|
|
|
\item{\bf Cross references}\index{cross referencing!concepts}
|
|
|
|
\begin{itemize}
|
|
\item The basic functionalities will be cross referenced, as
|
|
described in Section~\ref{functionalities}.
|
|
\item Each \CC\ name will be listed as a main item
|
|
\item If modifiers are attached to an item, there should
|
|
be a cross reference for the term with the modifiers placed
|
|
before the concept name\index{modifiers}. An exception is
|
|
for the modifiers ``2D'', ``3D'', and ``dD''. These will
|
|
produce no cross references.
|
|
\item Any other subitems that might reasonably serve as starting
|
|
points
|
|
for a search or might be reached via a different path will
|
|
be cross referenced either as main items or subitems under
|
|
other items.
|
|
\end{itemize}
|
|
|
|
For example:
|
|
\begin{indexex}
|
|
Cartesian \\
|
|
\> representation class, 1.4 \\
|
|
\ccc{\ccFont Cartesian}, 1.4 \\
|
|
. . . \\
|
|
conversion \\
|
|
\> between number representations, 1.15 \\
|
|
\> between point and vector, 1.20 \\
|
|
. . . \\
|
|
\ccc{\ccFont Homogeneous}, 1.4 \\
|
|
homogeneous \\
|
|
\> representation class, 1.4 \\
|
|
. . . \\
|
|
\ccc{\ccFont Point_2}, 1.13 \\
|
|
. . . \\
|
|
range tree, {\em see} tree, range
|
|
\end{indexex}
|
|
|
|
\item {\bf Automatic indexing commands}\index{automatic indexing!concepts}
|
|
\begin{itemize}
|
|
\item \verb|\begin{ccRefConcept}[class::]{concept}|%
|
|
\Eindex{ccRefConcept} \ldots
|
|
\verb|\end{ccRefConcept}|
|
|
This environment will automatically generate a subitem for the
|
|
{\tt concept} under the main item for {\tt class} with the
|
|
page numbers associated with the range of pages on which the
|
|
``begin'' and ``end'' commands appear. If
|
|
the optional argument, {\tt class}, is not provided, a main entry
|
|
will be created for the concept with the associated range of
|
|
pages.
|
|
\end{itemize}
|
|
|
|
\item {\bf Relevant indexing macros}
|
|
|
|
The generic indexing macros (Section~\ref{generic_macros}) should be
|
|
used with ``{\tt c}'' supplied as the value of the optional argument.
|
|
\end{description}%
|
|
\index{concepts|)}
|
|
|
|
\subsubsection{Functionalities}%
|
|
\index{functionalities|(}
|
|
\label{functionalities}
|
|
|
|
\begin{description}
|
|
\item{\bf Which pages}
|
|
|
|
The index should include a listing for any page on which:
|
|
\begin{itemize}
|
|
\item the way to achieve this functionality is described.
|
|
\end{itemize}
|
|
\item{\bf What will the entry look like}
|
|
|
|
The main item, listed in the default font, should be the word
|
|
or phrase that captures the
|
|
essence of the thing to be achieved. If appropriate, subitems
|
|
will be used for refinements of this essence. For example:
|
|
\begin{indexex}
|
|
conversion \\
|
|
\> Cartesian to homogeneous, 1.15 \\
|
|
\> homogeneous to Cartesian, 1.15 \\
|
|
\> point to vector, 1.20 \\
|
|
\> vector to point, 1.20 \\
|
|
\end{indexex}
|
|
|
|
In an attempt to limit the number of variations that are produced
|
|
for the terms describing these functionalities, a scan through the
|
|
reference manual (release 1.0) has been made to produce these
|
|
terms\index{functionalities!terms}:
|
|
\begin{itemize}
|
|
\item comparison
|
|
\item conversion
|
|
\item composition
|
|
\item customization
|
|
\item difference
|
|
\item distance computation
|
|
\item drawing
|
|
\item generation
|
|
\item input
|
|
\item insertion
|
|
\item intersection checking
|
|
\item intersection computation
|
|
\item output
|
|
\item removal
|
|
\item searching
|
|
\item transformation
|
|
\item traversal
|
|
\item triangulation
|
|
\item union
|
|
\item verification (validity checking)
|
|
\end{itemize}
|
|
Where appropriate, these are the terms that should be used. When
|
|
no applicable term is available in this list, the word of phrase
|
|
chosen should, as with the above, be a noun ({\it i.e.}, ``comparison''
|
|
rather than ``compare'' or ``comparing'').
|
|
|
|
|
|
\item{\bf Cross references}\index{cross referencing!functionalities}
|
|
\begin{itemize}
|
|
\item Any subitems that might reasonably serve as starting points
|
|
for a search or might be reached via a different path will
|
|
be cross referenced either as main items or subitems under
|
|
other items.
|
|
\item Any subitems that are \CC\ names will also appear as main
|
|
items.
|
|
\end{itemize}
|
|
|
|
For example:
|
|
\begin{indexex}
|
|
point, 2D {\bf 1.11},
|
|
1.13 \\
|
|
\> conversion between representations, 1.15 \\
|
|
\> conversion to/from vector, 1.20\\
|
|
\end{indexex}
|
|
|
|
\item {\bf Relevant indexing macros}
|
|
|
|
The generic indexing macros (Section~\ref{generic_macros}) should
|
|
be used with ``{\tt f}'' supplied as the value of the optional argument.
|
|
|
|
\end{description}
|
|
\index{functionalities|)}
|
|
|
|
%\subsubsection{Generic data structures}%
|
|
%\index{data structures|(}
|
|
%\label{generic_ds}
|
|
%
|
|
%\begin{description}
|
|
% \item{\bf Which pages}
|
|
%
|
|
% The index should include a listing for any page on which:
|
|
%
|
|
% \begin{itemize}
|
|
% \item the data structure is described or defined.
|
|
% \end{itemize}
|
|
%
|
|
% \item{\bf What will the entry look like}
|
|
%
|
|
% The generic name or category of the data structure will appear as a
|
|
% main item in the default font with the associated page number of the
|
|
% definition (in boldface)
|
|
% or description. The subitems of these generic data structure names will
|
|
% refer readers to the specific \cgal\ instances of the data structures
|
|
% with ``see also'' entries corresponding to the class names.
|
|
% There may also be subitems for basic functionalities that can be
|
|
% achieved for the data structure.
|
|
%
|
|
% To make it easier to stay within the three nesting levels available,
|
|
% distinctions among variations on the basic data structures (such as
|
|
% 2D, 3D, and dD, or range trees,
|
|
% segment trees, multilayer trees, and KD-trees) should be done using
|
|
% modifiers instead of subitems\index{modifiers}.
|
|
% The modifier will be placed after the
|
|
% generic data structure name and separated from it with a comma, as in
|
|
% the following example:
|
|
% \begin{indexex}
|
|
% point, 2D, {\bf 1.11}, 1.13 \\
|
|
% \> conversion between representations, 1.15 \\
|
|
% \> conversion to/from vector, 1.20\\
|
|
% \> {\em see also} \ccc{\ccFont Point_2} \\
|
|
% point, 3D, {\bf 1.57}, 1.59 \\
|
|
% \> ... \\
|
|
% \> {\em see also} \ccc{\ccFont Point_3}\\
|
|
% point, dD, {\bf 1.??}, 1.?? \\
|
|
% \> ... \\
|
|
% \end{indexex}
|
|
%
|
|
%
|
|
% \item{\bf Cross references}\index{cross referencing!concepts}
|
|
%
|
|
% \begin{itemize}
|
|
% \item The basic functionalities will be cross referenced, as
|
|
% described in Section~\ref{functionalities}.
|
|
% \item Each class name will be listed as a main item
|
|
% \item If modifiers are attached to an item, there should
|
|
% be a cross reference for the term with the modifiers placed
|
|
% before the data structure name. An exception is for the
|
|
% modifiers ``2D'', ``3D'', and ``dD''. These will produce
|
|
% no cross references.
|
|
% \end{itemize}
|
|
% Examples of these cross references would be:
|
|
% \begin{indexex}
|
|
% range tree, {\em see} tree, range \\
|
|
% . . . \\
|
|
% \ccc{\ccFont Point_2}, 1.13 \\
|
|
% . . . \\
|
|
% conversion \\
|
|
% \> between number representations, 1.15 \\
|
|
% \> between point and vector, 1.20 \\
|
|
% \end{indexex}
|
|
% \item {\bf Relevant indexing macros}
|
|
%
|
|
% The generic indexing macros (Section~\ref{generic_macros}) should
|
|
% be used with ``{\tt d}'' supplied as the value of the optional argument.
|
|
%
|
|
%\end{description}
|
|
%\index{data structures|)}
|
|
|
|
\subsubsection{Hints}%
|
|
\index{hints|(}
|
|
\label{hints}
|
|
|
|
\begin{description}
|
|
\item{\bf Which pages}
|
|
|
|
The index should include a listing for any page on which:
|
|
\begin{itemize}
|
|
\item a hint is given about how to achieve something.
|
|
\end{itemize}
|
|
\item{\bf What will the entry look like}
|
|
|
|
In most cases, these hints will relate to specific packages, classes,
|
|
concepts, {\em etc.} and will therefore be subitems in the
|
|
default font under the appropriate items. For example:
|
|
\begin{indexex}
|
|
representation class, {\bf 1.3} \\
|
|
\> choosing, 1.5 \\
|
|
\end{indexex}
|
|
|
|
Any hint that is not related to some other topic should be listed
|
|
as a main item in the default font using the same guidelines as
|
|
for a concept (Section~\ref{concepts}).
|
|
|
|
\item{\bf Cross references}\index{cross referencing!concepts}
|
|
|
|
These entries will likely not require cross referencing. But, as
|
|
before, there should be cross references made for any items that
|
|
could reasonably be the starting point of a search or that might
|
|
be reached by some other path.
|
|
|
|
\item{\bf Relevant indexing macros}
|
|
|
|
There are two macros that may be used to create a hint subitem or
|
|
subsubitem under another category of entry. These are:
|
|
|
|
\begin{itemize}
|
|
\item{\verb|\ccIndexHintAsSubitem[|{\em category\/}\verb|]{item}{hint}|}\ccIndexEntry{IndexHintAsSubitem}\index{subitems!hints as}\index{hints!as subitems}
|
|
\item{\verb|\ccIndexHintAsSubsubitem[|{\em category\/}\verb|]{item}{subitem}{hint}|}\ccIndexEntry{IndexHintAsSubsubitem}\index{subsubitems!hints as}\index{hints!as subsubitems}
|
|
\end{itemize}
|
|
As with the generic indexing macros, these commands take an optional
|
|
first argument which indicates the category of the main entry. The
|
|
default value of this argument is empty indicating a main entry that
|
|
does not fall into any of the other categories. The main item text
|
|
will be displayed in the appropriate font for the category indicated
|
|
by the optional argument value (or the default font, if an argument
|
|
value is not supplied).
|
|
|
|
For hints that are themselves main items, the generic indexing
|
|
macros (Section~\ref{generic_macros}) should be used with
|
|
``{\tt h}'' supplied as the value of the optional argument.
|
|
|
|
\end{description}
|
|
\index{hints|)}
|
|
|
|
\subsubsection{Libraries}%
|
|
\index{libraries|(}
|
|
\label{libraries}
|
|
|
|
\begin{description}
|
|
\item{\bf Which pages}
|
|
|
|
The index should include a listing for any page on which:
|
|
\begin{itemize}
|
|
\item the library's relevance to \cgal\ is explained;
|
|
\item a description of how to use the library with \cgal\ is
|
|
given.
|
|
\end{itemize}
|
|
\item{\bf What will the entry look like}
|
|
|
|
The name of the library will be a main item in the default font
|
|
with the above associated page numbers listed after it.
|
|
Subitems may be warranted to describe different aspects of using the
|
|
library with \cgal\ or different parts of the library that are relevant.
|
|
For example:
|
|
\begin{indexex}
|
|
\leda, 1.1 \\
|
|
\>windows, ??.?? \\
|
|
\end{indexex}
|
|
\item{\bf Cross references}\index{cross referencing!libraries}
|
|
|
|
\begin{itemize}
|
|
\item There should be a ``see also \ccc{\ccFont Library_Name}''\index{see also entries!library}
|
|
subitem for any item that derives its use or functionality
|
|
from the library.
|
|
\end{itemize}
|
|
For example:
|
|
\begin{indexex}
|
|
\ccc{\ccFont convex_hull_rat_leda_traits_2}, 2.146 \\
|
|
\> see also \leda\
|
|
\end{indexex}
|
|
|
|
|
|
\item {\bf Relevant indexing macros}
|
|
|
|
The generic macros (Section~\ref{generic_macros}) should be used
|
|
with ``{\tt l}'' supplied as the value of the optional argument.
|
|
|
|
\end{description}%
|
|
\index{libraries|)}
|
|
|
|
|
|
\subsubsection{Packages}%
|
|
\index{packages|(}%
|
|
\label{packages}
|
|
|
|
\begin{description}
|
|
\item{\bf Which pages}
|
|
|
|
The index should include a listing for any page on which:
|
|
\begin{itemize}
|
|
\item the package description begins;
|
|
\item the package description ends;
|
|
\item an explanation or use of the package
|
|
is described, if separated from the introduction.
|
|
\end{itemize}
|
|
\item{\bf What will the entry look like}
|
|
|
|
The package name will be a main item in the default font, followed
|
|
by the above page numbers. There will be subitems for the package,
|
|
as appropriate
|
|
to describe its various features. When a package
|
|
description closely mimics a class description, its index entry
|
|
should mimic a class entry (Section~\ref{classes}). For example,
|
|
the entry for the convex hull package would look something like
|
|
this:
|
|
\begin{indexex}
|
|
convex hull, 2D, 2.135--2.148 \\
|
|
\> assertions, 2.135 \\
|
|
\> extreme points, 2.140 \\
|
|
\> convexity checking, 2.142 \\
|
|
\> lower and upper hull, 2.138 \\
|
|
\> global functions, 2.136--2.142 \\
|
|
\> traits class, 2.143 \\
|
|
\>\> default, 2.143 \\
|
|
\>\> for \leda\ geometry, 2.145 \\
|
|
\>\> requirements, 2.147 \\
|
|
\>\> {\em see also} \ccc{\ccFont convex_hull_traits_2}\\
|
|
\>\> {\em see also} \ccc{\ccFont convex_hull_constructive_traits_2}\\
|
|
\>\> {\em see also} \ccc{\ccFont convex_hull_rat_leda_traits_2}\\
|
|
\>\> {\em see also} \ccc{\ccFont convex_hull_leda_traits_2}\\
|
|
\> utilities, 2.139 \\
|
|
\end{indexex}
|
|
|
|
\item{\bf Cross references}\index{cross referencing!packages}
|
|
|
|
\begin{itemize}
|
|
\item Any subitems that might reasonably serve as starting points
|
|
for a search or might be reached via a different path will
|
|
be cross referenced either as main items or subitems under
|
|
other items.
|
|
\item Any subitems that are \CC\ names will also appear as main
|
|
items.
|
|
\item Cross referencing should mimic class cross referencing
|
|
when the package description mimics a class description.
|
|
\end{itemize}
|
|
|
|
\item{\bf Relevant indexing macros}
|
|
\begin{itemize}
|
|
\item \verb|\begin{\ccPackage}{package name}| \ldots
|
|
\verb|\end{ccPackage}|\Eindex{ccPackage}
|
|
|
|
This environment, like the class environments, generates
|
|
an index entry labeled with the package name and the range
|
|
of pages corresponding to the pages on which the
|
|
\verb|\begin| and \verb|\end| commands
|
|
appear. This environment defines a variable
|
|
\verb|\ccIndexPackageName|\ccIndexEntry{IndexPackageName} using
|
|
the supplied package name.
|
|
|
|
For package descriptions that mimic class descriptions and
|
|
thus require similar indexing, the appropriate macros listed
|
|
in Section~\ref{classes} should be used in a {\tt ccPackage}
|
|
environment.
|
|
|
|
\item For creating other entries for packages, especially for
|
|
packages that do not mimic classes, the generic macros
|
|
(Section~\ref{generic_macros}) should be used
|
|
with ``{\tt p}'' supplied as the value of the optional
|
|
argument. When inside a {\tt ccPackage} environment, the
|
|
variable \verb|\ccIndexPackageName|\ccIndexEntry{IndexPackageName}
|
|
should be used (instead of the raw text ``{\tt package name}'')
|
|
to supply the package name as an argument where necessary.
|
|
This will assure that all entries for the package will be
|
|
formatted similarly.
|
|
\end{itemize}
|
|
|
|
\end{description}
|
|
\index{packages|)}
|
|
|
|
\subsubsection{Terms}%
|
|
\index{terms|(}
|
|
\label{terms}
|
|
|
|
\begin{description}
|
|
\item{\bf Which pages}
|
|
|
|
The index should include a listing for any page on which:
|
|
\begin{itemize}
|
|
\item the term is defined;
|
|
\item the term's relevance in \cgal\ is described,
|
|
if separated from its definition.
|
|
\end{itemize}
|
|
\item{\bf What will the entry look like}
|
|
|
|
The term will be a main item in the index in the default font
|
|
and the page number on which it is defined will be in boldface.
|
|
For example,
|
|
\begin{indexex}
|
|
ring type {\bf 1.4}
|
|
\end{indexex}
|
|
\item{\bf Cross references}
|
|
|
|
None
|
|
|
|
\item {\bf Relevant indexing macros}
|
|
|
|
The generic macros (Section~\ref{generic_macros}) should be used
|
|
with ``{\tt t}'' supplied as the value of the optional argument.
|
|
|
|
\end{description}
|
|
\index{terms|)}
|
|
|
|
%\section{Example}
|
|
%\label{example}
|
|
%
|
|
%On the following pages is a sample index for Chapters 1 through 5 of Part 1
|
|
%and Chapter 8 of Part 2 of the \cgal\ Reference Manual, release 1.0. This
|
|
%corresponds to roughly 34 manual pages, which produced 3 index pages. This
|
|
%suggests that the complete index, for all 421 manual pages, might be close
|
|
%to 40 pages long.
|
|
%
|
|
%This example demonstrates all categories of entries for which guidelines are
|
|
%given here. It also demonstrates the problem that is born of
|
|
%the \ccc{\ccFont CGAL_really_long_name}s.
|
|
%The entry ``see also
|
|
%\ccc{\ccFont CGAL\-_convex\-_hull\-_constructive\-_traits\-_2}
|
|
%under the ``traits class'' subitem of the ``convex hull'' package entry
|
|
%is 35.99242pts too wide as presented. Without the ``also'' it is still
|
|
%17.04794pts too wide. With the ``also'' but without the
|
|
%``\ccc{\ccFont CGAL_}'' prefix, it is 3.20427pts too wide.
|
|
%Without either the ``also'' or the ``\ccc{\ccFont CGAL_}''
|
|
%prefix, it fits. So this entry can be made to fit on one line, but it is
|
|
%not clear that that will be true for all entries. I fear the arrival of the
|
|
%half edge data structure.
|
|
%
|
|
%The \verb|\theindex| environment provided by \LaTeX, which was used with this
|
|
%example, will hyphenate words that extend beyond the column margins (although
|
|
%it is, in good \LaTeX\ fashion, somewhat picky about how it does this; witness
|
|
%the two entries for
|
|
%\ccc{\ccFont CGAL_\-really_\-really_\-really_\-long_\-convex_\-hull_\-constructive_\-traits_\-2}
|
|
%that come before the entry for \ccc{\ccFont CGAL_\-convex_\-hull_\-constructive_\-traits_\-2},
|
|
%one of which includes hyphenation clues
|
|
%in the middle of ``constructive'' and the other of which does not), but
|
|
%it has to be told, of course, how to hyphenate the words with underscores in
|
|
%them. This can either be done manually on an as-needed basis, or a hyphenation
|
|
%dictionary for the \cgal\ identifiers could be constructed if one does not
|
|
%already exist.
|
|
%
|
|
%This sample index was generated {\em manually}, so there are probably errors
|
|
%in it. Please ignore these errors unless they hinder your attempt to get an
|
|
%idea of what an index conforming to the specifications outlined in this
|
|
%document would look like.
|
|
|
|
\small
|
|
\printindex
|
|
|
|
\input{Manual_tools/cc_manual_index_appendix}
|
|
\input{Manual_tools/cc_manual_index_appendix2}
|
|
|
|
\end{document}
|