CXX2HTML

NAME

cxx2html - C++ to HTML Converter

SYNOPSIS

cxx2html is an extractor which pulls HTML-like comments from C++ source code and generates HTML pages describing the classes as output. One HTML page is generated for each header file.

cxx2html operates in two passes first it scans the header files looking for important sections, e.g. classes, and then it generates the HTML pages for each header. The input to cxx2html is a series of flags (each preceeded by a -) followed by one or more C++ header files to process.

This extractor attempts to preserve the relative hierarchy of the header files in placement the generated HTML file. So if cxx2html were given the following files:

        /usr/home/fred/One.h
        /usr/home/fred/Group/Two.h

it would generate:

        One.html
        Group/Two.html

to preserve the hierarchy of the header files (this behavior can be turned off, see -flat ).

cxx2html uses the information collected during the initial scan of the C++ header files to create the links between classes. The information can either be temporary and be used only during the single execution (the default), or it can be persistent (see -db ).

The output of cxx2html has been tuned for use with Mosaic, but it may work with other browsers.

SWITCHES

cxx2html is invoked as:

        cxx2html FLAGS FILES

where FLAGS is zero or more switches separated by white space, and FILES is one or more C++ header files to be converted to HTML pages. Each switch is preceeded by a "-"; the switches include:

--: indicates that no more switches follow. The remaining parameters are considered filenames. Note that this is not usually required; it is only required when dealing with oddly named files.
-aips: this flag is used to turn off the AIPS++ specific tags (see AIPS++ TAGS ).
-clear: indicates that the database (see -db ) should be cleared and regenerated.
-copy file: this is intended to allow inclusion of copyright information at the end of generated files. file should be a fully qualified path which is marked up with HTML. If this file exists and is readable, it will be included at the end of each of the generated pages. "-copyright" is a synonym.
-create: indicates that cxx2html should attempt to create any directories which it needs. This switch should be used with caution.
-db name: specifies that name should be the name for a DBM style database to store information about the contents of the header files.
-dir directory: indicates that the output files should be placed in directory. "-directory" is a synonym.
-ext extension: This can be used to specify an alternate extension for the output files. By default, all the output files are produced with an html extension. This flag could be used like:
-flat: indicates that the directory hierarchy of the input header files should not be preserved, and the HTML files should just be dumped into the current directory or a specified directory (see -dir ).
-rel: indicates that relative paths should be used within the generated HTML files to access non-generated files, e.g. the input header files. By default, absolute paths are used to access the files which are not generated by cxx2html. Relative paths are always used to access files generated by cxx2html. "-relative" is a synonym.
-root directory: indicates that directory should be considered a root of the header files. To preserve the directory hierarchy of the input header files, the roots of the header files must be known. Once the roots are available, the directory hierarchy is preserved based on these roots. If no roots, are supplied then the minimal hierarchy (the maximum root) is calculated based on the header files supplied as parameters. Multiple -root flags can be used to specify more than one possible root.
-scan: indicates that cxx2html should not generate any HTML files, but only scan the files and generate the dictionary of information. A database must be specified for this flag to be used (see -db ).
-v: print out the version information.

COMMENT LANGUAGE

The following assumptions are made about the C++ header files which are being documented:

         (1)  Documentation immediately precedes the language element
         (2)  All of the header files being documented have unique names
         (3)  All of the classes being documented have unique names
         (4)  All comments are written using C++ style comments

So, a class might look like:

        // This is the <b>good</b> documentation for foo
        class foo {
            foo(); // ctor (THIS WILL BE ATTACHED TO "~foo()"!)
            ~foo();
        };

These rules apply to function documentation as well. Thus, adding a comment to the end of a function declaration means that it will be associated with the next language element (as with the destructor above).

HTML

In general, the class comments are marked up with HTML. This markup is transported verbatim to the output HTML pages. Empty comment lines are interpreted as paragraph breaks.

There are a number of extensions which may be useful. These were added to identify sections which were important for code documentation or to simplify the task of generating documentation for source code.

LINKTO

Because the extractor knows about all of the classes and where they are located in the generated HTML pages, there is a extractor expanded tag which indicates that a link to a particular class (which the cxx2html should have seen) should be created. This tag is:

        <linkto class=TableKeywords>good class!</linkto>

When cxx2html finds a tag of this form, it substitutes an HTML anchor which has a hypertext link to the particular section of the HTML page which discusses the referenced class (here TableKeywords). In this case, the generated link might look like:

        <a href="Tables/TableKeywords.html#TableKeywords">good class!</a>

The reason this additional tag was useful is because the relative location the HTML page which documents a class could easily change.

Sometimes it is also necessary to reference URLs within the HTML file which discusses a given class. This can be done as follows:

        <linkto class="CLASSNAME#ANCHOR">

This will create a link to ANCHOR within the HTML file created for the class CLASSNAME. The whole anchor must be specified. Another common case is creating a link to one of the anchors created by cxx2html itself. This is handled as follows:

        <linkto class="CLASSNAME:ANCHOR">

In this case, a link will be created to the specified anchor which was created by cxx2html. This link will point to an anchor within the generated class documentation which looks like:

        <a name="CLASSNAME:ANCHOR">

So, if we wanted to reference the generated description anchor for TableKeywords, we would insert a tag which looks like:

        <linkto class="TableKeywords:description">here</linkto>

Links can also be created for function groups (see GLOBAL FUNCTION GROUPS ) as well as classes. This is done as follows:

        <linkto group="MaskArrMath.h#math">here</linkto>

The header file (here MaskArrMath.h) must be specified as well as the function group name (here math). This is necessary because the function group names are only assumed to be unique within the header file.

The generated anchors for function groups can be accessed in a way similar to classes:

        <linkto group="MaskArrMath.h#math:description">here</linkto>

This would access the description for the math function group. A similar method works for accessing general anchors in the generated HTML file for math:

        <linkto group="MaskArrMath.h#math#my_anchor">here</linkto>

This will create a link to the anchor named my_anchor in the generated HTML file for math. Another method which is easier, however, is to use the file attribute:

        <linkto file="MaskArrMath.h#my_anchor">

This will create a link to the anchor my_anchor in the HTML file generated from the header file MaskArrMath.h. The anchor must be fully specified. This file attribute could also be used to access class anchors, but the use of the class attribute is much more general.

One final attribute which <linkto> can have is module. This attribute allows the documentation writer to create links to the module HTML files as well as user defined anchors within the module documentation. For example:

        <linkto module=Tables>
        <linkto module="Tables#my_anchor">

The first version would just create a link to the HTML file which documents the Tables module. The second would create a link to the user specified anchor (my_anchor) within that HTML file. This is analogous to syntax for the class attribute. Note that there are no anchors automatically generated by cxx2html for module HTML files.

Note that in each of these cases only one of the attributes can be used at a time, either group or class or file or module. Also, quotes are required for the attribute values in most of these cases.

LINKFROM

This tag is used to indicate that several classes or modules are related to the current class, module, or global function group. This tag is used as follows:

        // <linkfrom anchor=math classes="MaskedArray ROMaskedArray">
        //     Related <here>mathematical functions</here> for MaskedArrays
        // </linkfrom>

This indicates that links should be created from the MaskedArray and ROMaskedArray classes to the anchor math in the HTML file generated for the current header file. The text contained between the opening and closing linkfrom tags is used as the label of the link from the listed classes to the indicated anchor (here math). If this text contains an opening (<here>) and closing (</here>) tags, these tags will be replaced with the HTML anchors which create the requested link.

To create links in a set of modules, the modules attribute is use instead of (or in addition to) the classes attribute:

        // <linkfrom anchor=column_ops modules="Tables">
        //     Related <here>column operations</here> for Tables
        // </linkfrom>

This tag is the inverse of the <linkto> tag (see LINKTO ). The <linkto> tag specifies links from the current file to other files, and <linkfrom> specifies links from other files to the current file.

SRCBLOCK

This is a special tag for including code block in the documentation. Having a unique tag for this ensures that all of the code examples look the same. Also, the following replacements are made:

        (1)   < replaced by &lt;
        (2)   > replaced by &gt;
        (3)   " replaced by &quot;
        (4)   & replaced by &amp;

In addition, cxx2html will attempt to add the proper amount of white space in front of the code block to set it off if the author hasn't already done this, i.e. if there is a line in the code snippet which begins with less than two space characters, then the whole code block will be moved over a uniform amount. This tag is used as follows:

        //<srcblock>
        // x() = sqrt(3);
        //</srcblock>
        double &x();

In this case, since the code line has only one leading space character extra indentation will be added. In the following, however:

        //<srcblock>
        //   y() = exp(3);
        //</srcblock>
        double &y();

no extra indentation will be added because all of the lines (the single line) has more than one leading space.

If tabs are used for indentation in a code example, cxx2html will not attempt to provide extra indentation.

SRC

This does the same substitutions, e.g. '>' for '>', as <srcblock> (see SRCBLOCK ), but this tag does not separate the text as a block. In other words, <src> can be use in-line to indicate very short code snippets. If a code example extends over multiple lines, <srcblock> should be used instead.

SUMMARY

Another tag which is treated specially is the summary tag. This tag gives a brief one-line summary of the class. It is specified like:

        <summary> A really good class </summary>

This summary line is extracted and used whenever the class is used in a list. This allows the person reading the class documentation to more easily select classes of interest.

MODULES

Often it is useful to break a large set of header files up into "modules". cxx2html supports a concept of modules. cxx2html makes the following assumptions about "modules":

        (1)  Modules are composed of the header files within a particular
             directory.
        (2)  There is a header file with the same basename as the directory,
             so there would be "Tables.h" which would document the module
             composed of "Tables/*.h".
        (3)  The documentation for the module is specified in MODULENAME.h,
             e.g. Tables.h, and is enclosed in:
                           <module> ... </module>

If these conditions hold, then the module documentation in MODULENAME.h between the <module> tags is extracted, and put into MODULENAME.html and links to all of the classes in the module are also added to this HTML file.

ELEMENT GROUPS

Often it is useful to apply the same comment to several functions. For this, there is a cxx2html "group" directive. This is specified like:

        // Common comment
        // <group>
        func1();
        func2();
        // </group>

This is used within a class, and it specifies that the common documentation should be applied to each of the elements in the group. These group commands can be nested. The <group> tag has one attribute name. The name attribute can be used to associate a HTML anchor with the group:

        // Common comment
        // <group name=transcendental>
        sin(double x);
        cos(double x);
        // </group>

This indicates that these two functions should be grouped together and that the group should have the anchor transcendental (in addition to the normal anchors created for the individual functions by cxx2html).

A group tag without a name attribute can only be used in comments within a group which has a name attribute, e.g. a global function group (see GLOBAL FUNCTION GROUPS ), or in comments within an extracted C++ language element, e.g. a class.

GLOBAL FUNCTION GROUPS

Often large groups of global functions are related in some way. These groups of global functions can be treated much like a class and documented with cxx2html.

Here is an example of how global functions can be documented:

        // <summary> Element by element mathematical operations. </summary>
        //
        // These functions perform element by element mathematical 
        // operations on masked arrays.
        //
        // <group name=assignment>
        template<class T>
        const MaskedArray<T> & operator+= (const MaskedArray<T> &left,
                                           const Array<T> &other);
        template<class T>
        const MaskedArray<T> & operator-= (const MaskedArray<T> &left,
                                           const Array<T> &other);
        // </group>

This indicates that these two global functions are to be treated as a group, and extracted by cxx2html. The syntax for introducing a global function group is the same as element grouping within a class:

        // <group name=NAME>

The NAME is used to generate a anchor within the final HTML page for this global function group. This NAME must be unique within the file, i.e. no other classes or function groups can have the same name. Global function groups must have the name attribute specified, and while there can be nested group tags, only the outer most group is treated as a function group.

As with classes, the <summary> has a special meaning for function groups. It is used in the menu at the top of a file which contains several function groups or classes.

HTML-3.0 LIKE EXTENSIONS

The HTML 3.0 <note> tag is supported in a primitive form:

        <note role=tip> this is a tip for the user </note>
        <note role=caution> this cautions the user </note>
        <note role=warning> this warns the user of danger </note>

Each of these generates an accented block of text with an appropriate graphic for the importance of the note. Later when HTML 3.0 is widely available this support will be removed, and the underlying HTML 3.0 browsers will be relied upon.

AIPS++ TAGS

The following tags are specific to the documentation standards which we have developed for the AIPS++ project. In general, these tags just get expanded to be section headers (<h3>).

If the aips flag (see -aips ) is specified, these tags will not be processed.

Here are the tags:

etymology: This explains why the particular name for the class was selected. Sometimes this will aid in understanding the class. This is used as follows:
motivation: This describes the author's motivation for writing the class. It should detail what conditions necessitated the development of a new class. Like <synopsis> any tags or text can be included between the opening and closing <motivation> tags.
prerequisite: This tag identifies the prerequisite classes which should be understood before attempting to learn about the new class. This is used like:
reviewed: This tag is used to indicate the review status of the class. It has four attributes:
synopsis: This is used to provide a medium to long description of the class. Any important text can be included between the opening, <synopsis> and the closing, </synopsis>, tags. This text can include any special purpose tags discussed above or regular HTML tags.
templating: This is used to identify requirements for the type arguments to a templated class or function. It essentially identifies the requirements imposed upon classes by the template. Its form is:
thrown: This provides a list of the exceptions which are thrown by a particular function. This tag is used as follows:
todo: This provides a list of improvements, bug fixes, extensions, etc. which should be added to this class in the future. This is used like:
use: This tag indicates the intended use for the class. It currently has only one attribute, visibility. This attribute has two values, and is used as follows:

LIBRARY DIRECTORY

/usr/local/ulib/cxx2html