\documentstyle[12pt]{article} %\pagestyle{empty} \textwidth 15.4cm \textheight 24 cm \topmargin -14mm \evensidemargin 3mm \oddsidemargin 3mm \input{cgal_manual.sty} \parindent0em \setlength{\parskip}{1ex minus 0.9ex} \sloppy \title {cgal\_manual.sty\\ The CGAL Kernel User Manual \LaTeX\ style\\ \vspace{5mm} \CCrevision} \author{Lutz Kettner} \date{\CCdate} \begin{document} \maketitle % ---------------------------------------------------------------------- \section{Introduction} The {\tt cgal\_manual}-style was developed with a tight look at the LEDA manual style. It has two facilities. First, it provides a couple of macros for structuring the manual as the LEDA manual does. These are {\tt \string\definition}, {\tt \string\creation}, {\tt \string\operations}, {\tt \string\implementation}, {\tt \string\example}, and {\tt \string\precond}. There are demonstrated in the next section. The second facility of this style deals with the special handling of \CC\ language features. The style will be used in conjunction with a tool that extracts a class declaration with all its method and function declarations and plugs it in a \CC\ header file. Therefore, pure \CC\ code will stay in several arguments and has to be reformatted neatly for the manual. Again, the LEDA manual was the ideal we want to meet. In our case, \TeX\ will do the complete reformatting as it is written as macros in the style. Another section below explains all features. Demo classes with and without template parameters are defined. The benefit of using \TeX\ is that no other tool has to be invoked before the final specification is printer ready. Thus, no inconsistent versions can appear as it is the case e.g.\ for index making procedures for \TeX. If the programming turns out to be too slow, I am not a \TeX\ wizard, maybe someone can do it better or it can be even switched to an external tool. % ---------------------------------------------------------------------- \section{Structuring Macros} \definition Here comes the general introductory explanation for a class etc. \precond Specific conditions can be stated as preconditions in any place. \creation Constructors are defined and explained here. \operations The complete list of methods and functions (including operators) are defined here. \implementation Specific notes about implementation issues that belong to the user can be given here. These might be space requirements and runtime statements. \example How to solve a small but interesting problem with this class. % ---------------------------------------------------------------------- \begin{class}{Demo_Class} \CCsection{A simple class as an example} The class with its name is declared by \verb"\begin{class}{Demo_Class}". The macro \verb"\CCsection{"\ldots\verb"}" produces the section title from above and appends the class name. Note that the special character ``\_'' has not to be quoted as it is usual within \LaTeX. In any case, the complete original \CC\ source text is written without quoting. The formatting macros handle for example the special characters \_, {\tt <}, {\tt >}, and {\tt \&} as they appear in \CC\ names and the characters \#, \%, \CChat, and \CCtilde\ as they appear with operators. See the following example: \CCstyle{ #define %^~ Return_Type > fct_foo( const X &a);} To achieve this behaviour with \TeX\, the \verb"\catcode" values of some characters has to be changed. So within the \CC\ code things like comments with ``\%'' sign wont work. The \TeX\ comment in the other parameter works as usual. A sad sideeffect is that these changed catcodes wont apply if these macros are invoced within other macros. In that case, the argument text was just once parsed from \TeX\ and the catcodes are all fixed. \definition The class \classname\ does nothing. The formatted name of the class can be accessed using the macro \verb"\classname". The unformatted name as it was originally written can be accessed using the \verb"\pureclassname" macro. \creationvariable{p} \creation The constructors create a variable \var\ of the class. The \verb"\creationvariable{"\ldots\verb"}" macro sets the name for the future use. It can be accessed with the \verb"\var" or \verb"\purevar" macro. The constructors are written using the \verb"\constructor{"\ldots\verb"}{"\ldots\verb"}" macro. The first parameter contains the \CC\ declaration, the second parameter the comments. The declaration is written in the normal \CC\ fashion, as shown at the end of the comment. The style formats them as if they are used to declare a variable for this class. For convinience, \verb"const"\ldots\verb"&" parameter declarations are eliminated in the formatting. It makes no difference in the usage of a parameter. If the type of a constructor, method, or function parameter equals the current class, it is also omitted. In the case that nothing is left, the \CCemptyParameter\ symbol is used. See the copy constructor for an example. This all together is the way, we achieve very natural looking descriptions. \constructor{Demo_Class();}{introduces a variable \var\ initialized to the default. \CC\ code: \protect\verb"Demo\_Class();"} \constructor{Demo_Class(const Demo_Class &);}{copy constructor. \CC\ code: \verb"Demo\_Class(const Demo\_Class \&);" } \constructor{Demo_Class(RT hx, RT hy, RT hw);}{arbitrary constructor. \CC\ code: \verb"Demo\_Class(RT hx, RT hy, RT hw);"} The font and style in which the declarations are formatted can be changed by overwriting the \verb"\CCfont" and \verb"\CCendfont" macros. There default settings are \verb"\def\CCfont{\it}\def\CCendfont{\/}". They are used within a group, so font changing commands are local. The following line is formatted using the definitions \verb"\def\CCfont{\tt}\def\CCendfont{}". \begingroup \def\CCfont{\tt}\def\CCendfont{} \constructor{Demo_Class(int a, X &x);}{arbitrary constructor.} \endgroup Also changable are the special characters the formatting has to deal with. They are named \verb"\CCunderscore", \verb"\CCopenangle", \verb"\CCcloseangle", \verb"\CCampersand", \verb"\CChat", and \verb"\CCtilde". The sign for the empty parameter is named \verb"\CCemptyParameter". \operations \threecolumns{2.8cm}{2.8cm} The layout of this section can be customized to the width of the return types and the declarations. The \verb"\threecolumns{"\ldots\verb"}{"\ldots\verb"}" macro sets the width of the two leading columns of the total three columns. The other dimensions will be computed. Note that declarations after the closing parantheses like {\tt const} for the implicit class parameter of a method will not be printed (this might change in the future). The return value is handled like a parameter type. That means that {\tt const\ldots\&} declarations are removed, but if the type equals to the class, it is {\em not} removed. \method{FT x() const;}{Cartesian x-coordinate. \CC\ code: {\tt FT x() const;}} \method{const FT& y();}{Cartesian y-coordinate. \CC\ code: {\tt const FT\& y();}} \method{Demo_Class transform( const CGAL_HAff_transformation &t) const; }{ Longish declarations forces the comment to start in the next line.} \method{Demo_Class longish_function_name( const CGAL_HAff_transformation &t, const Dummy_Type &q, Long_Type_Name_For_Fun Variable_Also_Long) const; }{ Even more longish declarations forces the parameters printed one per line.} Reference or pointer parameters can occur on both sides of the separating space between the type and the function or method name. The formatting normalizes them to the the left side. This formatting is not done within the parameters (, but maybe in the future). An example: \function{Demo_Class& foo( int& a, int* b);}{} \function{Demo_Class* foo( int& a, int* b);}{} \function{Demo_Class &foo( int &a, int *b);}{} \function{Demo_Class *foo( int &a, int *b);}{} Operator declarations are formatted as like the operators are used. All operators that are allowed to be overloaded in \CC\ are handled. They are listed in the last section for completeness and to check the layout. Type casting through an operator is currently not supported. It will give an error message. If the error will be ignored, the macro formats the operator as a method or function, as it was declared. Sometimes, there is a choice between implementing an operator as a method or as a function. Both declarations will produce the same formatting, as demonstrated with the next two declarations. \function{Demo_Class operator+(Demo_Class p, Demo_Class q);}{Declaration via function.} \method{Demo_Class operator-(Demo_Class q);}{Declaration via method.} There is some laziness allowed in placing spaces around the operator characters. See the following examples: \method{A operator+(Demo_Class q);}{\CC\ code: {\tt A operator+(Demo\_Class q);}} \method{A operator +(Demo_Class q);}{\CC\ code: {\tt A operator +(Demo\_Class q);}} \method{A operator+ (Demo_Class q);}{\CC\ code: {\tt A operator+ (Demo\_Class q);}} \method{A operator + (Demo_Class q);}{\CC\ code: {\tt A operator + (Demo\_Class q);}} The keyword {\tt operator} is reserved, but it can appear as a substring in another name. See the following examples that this style can handle such cases: \method{A foo_operator(Demo_Class q);}{} \method{A noperator(Demo_Class q);}{} \method{A operatoro(Demo_Class q);}{} \method{A operator_(Demo_Class q);}{} \method{A operator0(Demo_Class q);}{} For future extensions, the macro that separates the return type from the function or method name recognizes the scope operator (, but currently not in the usage as the global scope). An example: \function{Demo_Class Class_X :: foo(Demo_Class p, Demo_Class q);}{Declaration with scope.} Other features should be incorporated. These are: Preprocessor constants and macros, normal C variable declarations and constants, global functions and their associated file, enums, typedefs, structs similar to classes (more ?). \end{class} % ---------------------------------------------------------------------- \begin{class}{Demo_Class} \section{The list of all operators} \function{Ptr_Class operator->(Demo_Class p);}{} \function{Demo_Class operator[](Demo_Class p, int i);}{} \function{Demo_Class operator()(Demo_Class p);}{} \function{Demo_Class operator()(Demo_Class p, int i);}{} \function{Demo_Class operator()(Demo_Class p, int i, int j);}{} \function{Demo_Class operator()(Demo_Class p, int i, int j, int k);}{} \function{Demo_Class operator()(Demo_Class p, const A& a, B& b, C c, const D& d, Demo_Class e);}{all number and types of parameters are possible.} \function{Demo_Class operator++(Demo_Class p);}{} \function{Demo_Class operator++(Demo_Class p, int);}{The postfix incr.\ operator has a hidden {\tt int} parameter that the formatting does not show.} \function{Demo_Class operator--(Demo_Class p);}{} \function{Demo_Class operator--(Demo_Class p, int);}{} \function{Demo_Class operator~(Demo_Class p);}{} \function{Demo_Class operator!(Demo_Class p);}{} \function{Demo_Class operator-(Demo_Class p);}{} \function{Demo_Class operator+(Demo_Class p);}{} \function{Demo_Class operator&(Demo_Class p);}{} \function{Demo_Class operator*(Demo_Class p);}{} \method{void* operator new( size_t);}{Hidden parameters are not shown. \CC\ code: {\tt $\backslash$method\{void* operator new( size\_t);\}}.} \method{void operator delete(void*, size_t);}{Hidden parameters are not shown. \CC\ code: {\tt $\backslash$method\{void operator delete(void*, size\_t);\}}} \method{void operator delete[](void*, size_t);}{Hidden parameters are not shown again. \CC\ code: {\tt $\backslash$method\{void operator delete[](void*, size\_t);\}}} \function{Member_Ptr operator->*(Demo_Class p);}{} \function{Demo_Class operator*(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator/(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator%(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator+(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator-(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator<<(Demo_Class p, int i);}{} \function{Demo_Class operator>>(Demo_Class p, int i);}{} \function{Demo_Class operator<(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator<=(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator>(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator>=(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator==(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator!=(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator&(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator^(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator|(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator&&(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator||(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator=(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator*=(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator/=(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator%=(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator+=(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator-=(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator<<=(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator>>=(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator&=(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator|=(Demo_Class p, Demo_Class q);}{} \function{Demo_Class operator^=(Demo_Class p, Demo_Class q);}{} \end{class} \end{document}