<!-- Published by Quadralay WebWorks HTML Lite 1.5.1 -->
<!-- And munged by Dave's special Python script -->
<html>
<head>
<title>Documentation System</title>
</head>

<body bgcolor="#ffffff">
<a name="n0"></a><h1>5 Documentation System</h1><p><ul>
<li> <a href="#n1">Introduction</a>
<li> <a href="#n2">How it works</a>
<li> <a href="#n3">Choosing a documentation format</a>
<li> <a href="#n4">Function usage and argument names</a>
<li> <a href="#n5">Titles, sections, and subsections</a>
<li> <a href="#n6">Formatting</a>
<li> <a href="#n7">Adding Additional Text</a>
<li> <a href="#n8">Disabling all documentation</a>
<li> <a href="#n9">An Example</a>
<li> <a href="#n10">ASCII Documentation</a>
<li> <a href="#n11">HTML Documentation</a>
<li> <a href="#n12">LaTeX Documentation</a>
<li> <a href="#n13">C++ Support</a>
<li> <a href="#n14">The Final Word?</a>
</ul>

<a name="n1"></a><h2> Introduction</h2>
While SWIG makes it easy to build interfaces, it is often difficult to keep track of all of the different functions, variables, constants, and other objects that have been wrapped. This especially becomes a problem when your interface starts to grow in size from a handful to several hundred functions. To address these concerns, SWIG can automatically generate documentation in a number of formats including ASCII, HTML, and LaTeX. The goal is that you could look at the documentation file to see what functions were wrapped and how they are used in the target scripting language.<p>
<p>
Usage documentation is generated for each declaration found in an interface file. This documentation is generated by the target language module so the Tcl module will follow Tcl syntax, the Perl module will use Perl syntax, and so on. In addition, C/C++ comments can be used to add descriptive text to each function. Comments can be processed in a number of different styles to suit personal preferences or to match the style used in a particular input file.<p>
<p>
Automatic documentation generation for C/C++ programs is a fairly formidable problem and SWIG was never intended to be a substitute for a full-blown documentation generator. However, I feel that is does a reasonable job of  documenting scripting language interfaces. It seems to do just fine for many of SWIG's primary applications--rapid prototyping, debugging, and development.<p>
<a name="n2"></a><h2> How it works</h2>
For each declaration in an interface file, SWIG creates a "Documentation Entry." This entry contains three components; (1) a usage string, (2) a C information string, and (3) descriptive text. For example, suppose you have this declaration in an interface file :<p>
<p>
<blockquote><pre>int fact(int n);
/* This function computes a factorial */

</pre></blockquote>
The documentation entry produced by the SWIG ASCII module will look like this for Tcl:<p>
<p>
<blockquote><pre>fact n
	[ returns int ]
	This function computes a factorial

</pre></blockquote>
The first line shows how to call the function, the second line shows some additional information about the function (related to its C implementation), while the third line contains the comment text. The first two lines are automatically generated by SWIG and may be different for each language module. For example, the Perl5 module would generate the following output :<p>
<p>
<blockquote><pre>fact($n)
	[ returns int ]
	This function computes a factorial

</pre></blockquote>
<p>
Of course, this is only a simple example, more sophisticated things are possible.<p>
<a name="n3"></a><h2> Choosing a documentation format</h2>
The type of documentation is selected using the following command line options :<p>
<blockquote><pre>
-dascii			Produce ASCII documentation
-dhtml			Produce HTML documentation
-dlatex			Produce LaTeX documentation
-dnone			Produce no documentation

</pre></blockquote>
The various documentation modules are implemented in a manner similar to language modules so the exact choice may change in the future. With a little C++ hacking, it is also possible for you to add your own modules to SWIG. For example, with a bit of work you could turn all of the documentation into an online help command in your scripting language. <p>
<a name="n4"></a><h2> Function usage and argument names</h2>
The function usage string is produced to match the declaration given in the SWIG interface file. The names of arguments can be specified by using argument names. For example, the declarations<p>
<p>
<blockquote><pre>void insert_item(List *, char *);
char *lookup_item(char *name);
</pre></blockquote>
<p>
will produce the following documentation (for Python) :<p>
<p>
<blockquote><pre>insert_item(List *, char *)
	[ returns void ]

lookup_item(name)
	[ returns char * ]

</pre></blockquote>
When argument names are omitted, SWIG will use the C datatypes of the arguments in the documentation.   If an argument name is specified, SWIG will use that in the documentation instead.  Of course, it is up to each language module to create an appropriate usage string so your results may vary depending on how things have been implemented in each module.<p>
<a name="n5"></a><h2> Titles, sections, and subsections</h2>
The SWIG documentation system is hierarchical in nature and is organized into a collection of sections, subsections, subsubsections, and so on. The following SWIG directives can be used to organize an interface file :<p>
<p>
<ul>
<li><tt>%title "Title Text"</tt>. Set the documentation title (may only be used once)
<li><tt>%section "Section title"</tt>. Start a new section.
<li><tt>%subsection "Subsection title"</tt>. Create a new subsection.
<li><tt>%subsubsection "Subsubsection title"</tt>. Create a new subsubsection.
</ul>
<p>
The <tt>%title</tt> directive should be placed prior to the first declaration in an interface file and may only be used once (subsequent occurrences will simply be ignored). The section directives may be placed anywhere. However, <tt>%subsection</tt> can only be used after a <tt>%section</tt> directive and <tt>%subsubsection</tt> can only be used after a <tt>%subsection</tt> directive.<p>
<p>
With the organization directives, a SWIG interface file looks something like this :<p>
<p>
<blockquote><pre>%title "Example Interface File"
%module example
%{
#include "my_header.h"
%}

%section "Mathematical Functions"

... declarations ...

%section "Graphics"
%subsection "2D Plotting"
... Declarations ...
%subsection "3D Plotting"
%subsubsection "Viewing transformations"
... Declarations ...
%subsubsection "Lighting"
... Declarations ...
%subsubsection "Primitives"
... Declarations ...

%section "File I/O"

... Declarations ...
</pre></blockquote>
<a name="n6"></a><h2> Formatting</h2>
Documentation text can be sorted, chopped, sliced, and diced in a variety of ways. Formatting information is specified using a comma separated list of parameters after the <tt>%title</tt>, <tt>%section</tt>, <tt>%subsection</tt>, or <tt>%subsubsection</tt> directives. For example :<p>
<p>
<blockquote><pre>%title "My Documentation", sort, before, pre

</pre></blockquote>
This tells SWIG to sort all of the documentation, use comments that are before each declaration, and assume that text is preformatted. These formatting directives are applied to all children in the documentation tree--in this case, everything in an interface file.<p>
<p>
If formatting information is specified for a section like this<p>
<p>
<blockquote><pre>%subsection "3D Graphics", nosort, after
</pre></blockquote>
<p>
then the effect will only apply to that particular section (and all of its subsections). In this case, the formatting of the subsection would override any previous formatting, but these changes would only apply to this subsection. The next subsection could use its own formatting or that of its parent.<p>
<p>
Style parameters can also be specified using the <tt>%style</tt> and <tt>%localstyle</tt> parameters. The <tt>%style</tt> directive applies a new format to the current section and all of its parents. The <tt>%localstyle</tt> directive applies a new format to the current section. For example :<p>
<p>
<blockquote><pre>%style sort,before, skip=1      # Apply these formats everywhere
%localstyle sort                # Apply this format to the current section

</pre></blockquote>
Use of these directives usually isn't required since it's easy enough to simply specify the information after each section.<p>
<a name="n15"></a><h3> Default Formatting</h3>
By default, SWIG will reformat comment text, produce documentation in the order encountered in an interface file (nosort), and annotate descriptions with a C information string.   This behavior most closely matches that used in SWIG 1.0, although it is not an exact match due to differences in the old documentation system.<p>
<p>
When used in the default mode, comment text may contain documentation specific formatting markup. For example, you could embed LaTeX or HTML markup in comments to have precise control over the look of the final document.<p>
<a name="n16"></a><h3> Comment Formatting variables</h3>
The default formatting can be changed by changing one or more of the following formatting variables :<p>
<blockquote><pre>
after                 Use comments after a declaration (default)
before                Use comments before a declaration
chop_top=nlines       Comment chopping (preformatted)
chop_bottom=nlines    Comment chopping (preformatted)
chop_left=nchar       Comment chopping (preformatted)
chop_right=nchar      Comment chopping (preformatted)
format                Allow SWIG to reformat text (the default)
ignore                Ignore comments
info                  Print C information text (default)
keep                  Keep comments (opposite of ignore)
noinfo                Don't print C information text
nosort                Don't sort documentation (default)
pre                   Assume text is preformatted
skip=nlines           Number of blank lines between comment and declaration
sort                  Sort documentation
tabify                Leave tabs intact
untabify              Convert tabs to spaces (default)
</pre></blockquote>
<p>
More variables may be available depending on particular documentation modules. The use of these variables is described in the next few sections.<p>
<a name="n17"></a><h3> Sorting </h3>
Documentation can be sorted using the `<tt>sort</tt>' parameter. For example :<p>
<p>
<blockquote><pre>%title "My interface",sort
</pre></blockquote>
<p>
When used, all documentation entries, including sections will be alphabetically sorted. Sorting can be disabled in particular sections and subsection by specifying the `<tt>nosort</tt>' parameter in a section declaration. By default, SWIG does not sort documentation. As a general rule, it really only comes in handy if you have a really messy interface file.<p>
<p>
For backwards compatibility with earlier versions of SWIG, the following directives can be used to specify sorting. <p>
<p>
<blockquote><pre>%alpha 		Sort documentation alphabetically (obsolete)
%raw		Keep documentation in order (obsolete)

</pre></blockquote>
These directives only apply globally and should near the beginning of file. Future support of these directives is not guaranteed and generally discouraged.<p>
<a name="n18"></a><h3> Comment placement and formatting</h3>
Comments may be placed before or after a declaration. This is specified using the `<tt>before</tt>' and `<tt>after</tt>' parameters.    The space between a comment and a declaration can be set by changing the `<tt>skip</tt>' parameter.  By default, <tt>skip=1</tt>, indicating that a comment and declaration must be on adjacent lines.    Use of the <tt>skip</tt> parameter makes it possible for the documentation generator to ignore comments that are too far away and possibly unrelated to a declaration.<p>
<p>
By default, SWIG reformats the text found in a comment.   However, in many cases, your file may have preformatted comments or comment blocks.   To handle such comments correctly, you can use preformatted mode.  This is specified using the `pre' parameter as follows :<p>
<p>
<blockquote><pre>%section "Preformatted Section",pre
%section "Reformatted Section", format

</pre></blockquote>
All declarations in this section will now be assumed to have preformatted comments.   When using the preformat mode, a variety of other parameters are available as shown in the following diagram :<p>
<center><img src="ch5.1.png"></center>

.<p>
<p>
The chopping parameters can be used to strip out the text of block comments.  For example, using <tt>chop_left=3</tt>, <tt>chop_top=1</tt>, <tt>chop_bottom=1</tt> on the above comment produces the following output :<p>
<blockquote><pre>
Plot2D_line x1 y1 x2 y2 color
	[ returns void ]
	void Plot2D_line(int x1, int y1, int x2, int y2, Pixel color)  

	Draws a line between the points (x1,y1) and (x2,y2) using the 
	the given color.   The line is cropped to fit in the current  
	bounding box.                                      

	Uses the Bresenham line drawing algorithm.
</pre></blockquote>
<p>
The chopping parameters only apply if a comment is sufficiently large (i.e.. if the number of lines exceed <tt>chop_top</tt>+<tt>chop_bottom</tt>).   Thus, in our example, a one line comment will be unaltered even though chopping has been set.   By default, SWIG sets chop_left=3 and all others to zero.   This setting removes the  `<tt>/* </tt>` or `<tt>// </tt>` preceeding a comment.<p>
<a name="n19"></a><h3> Tabs and other annoyances</h3>
When using the preformatted mode, SWIG will automatically convert tabs to white space.  This is done assuming that tabs are placed every 8 characters.   The tabification mode can be selected using the `tabify' and `untabify' parameters :<p>
<p>
<blockquote><pre>%section "Untabified Section",untabify
%section "Leave those tabs alone", tabify

</pre></blockquote>
Tabs are simply ignored when comments are reformatted (well, actually, they're just copied into the output, but the target documentation method will ignore them).<p>
<a name="n20"></a><h3> Ignoring comments</h3>
To ignore the comments in a particular section, you can use the `ignore' parameter.  For example :<p>
<blockquote><pre>
%section "No Comments", ignore
%section "Keep Comments", keep

</pre></blockquote>
The `<tt>keep</tt>' parameter is used to disable the effect of an ignore parameter (if set by a section's parent).<p>
<a name="n21"></a><h3> C Information</h3>
Normally, each declaration in a file will have a C information tag attached to it.  This is usually enclosed in [ ] and contains the return type of a function along with other information.   This text can disabled using the `noinfo' parameters and reenabled using the `info' parameter.<p>
<p>
<blockquote><pre>%section "No C Information", noinfo
%section "Print C Information", info

</pre></blockquote>
<a name="n7"></a><h2> Adding Additional Text</h2>
Additional documentation text can be added using the <tt>%text</tt> directive as shown :<p>
<p>
<blockquote><pre><tt>%text %{
</tt>
This is some additional documentation text.

%}

</pre></blockquote>
The <tt>%text</tt> directive is primarily used to add text that is not associated with any particular declaration.   For example, you may want to provide a general description of a module before defining all of the functions.   Any text can be placed inside the <tt>%{,%}</tt> block except for a `<tt>%}</tt>' that ends the block. For the purposes of sorting, text segments will always appear immediately after the previous declaration.<p>
<a name="n8"></a><h2> Disabling all documentation</h2>
All documentation can be suppressed for a portion of an interface file by using the <tt>%disabledoc</tt> and <tt>%enabledoc </tt>directives.   These would be used as follows:<p>
<p>
<blockquote><pre>%disabledoc
... A a bunch of declarations with no documentation ...
%enabledoc
... Now declarations are documented again ...

</pre></blockquote>
These directives can be safely nested.  Thus, the occurrence of these directives inside a <tt>%disabledoc </tt>section has no effect (only the outer-most occurrence is important).<p>
<p>
The primary use of these directives is for disabling the documentation on commonly used modules that you might use repeatedly (but don't want any documentation for).  For example :<p>
<blockquote><pre>
%disabledoc
%include wish.i
%include array.i
%include timer.i
%enabledoc

</pre></blockquote>
<p>
<a name="n9"></a><h2> An Example</h2>
To illustrate the documentation system in action, here is some code from the SWIG library file `array.i'.<p>
<p>
<blockquote><pre>//
// array.i
// This SWIG library file provides access to C arrays.

%module carray

%section "SWIG C Array Module",info,after,pre,nosort,skip=1,chop_left=3,
chop_right=0,chop_top=0,chop_bottom=0

%text %{
%include array.i

This module provides scripting language access to various kinds of C/C++
arrays. For each datatype, a collection of four functions are created :

   &lt;type&gt;_array(size)              : Create a new array of given size
   &lt;type&gt;_get(array, index)        : Get an element from the array
   &lt;type&gt;_set(array, index, value) : Set an element in the array
   &lt;type&gt;_destroy(array)           : Destroy an array

The functions in this library are only low-level accessor functions
designed to directly access C arrays.  Like C, no bounds checking is
performed so use at your own peril.
%}

// -----------------------------------------------------------------------
// Integer array support
// -----------------------------------------------------------------------

%subsection "Integer Arrays"
/* The following functions provide access to integer arrays (mapped
   onto the C 'int' datatype. */

%{
	... Supporting C code ...
%}
int *int_array(int nitems);
/* Creates a new array of integers. nitems specifies the number of elements.
   The array is created using malloc() in C and new() in C++. */

void int_destroy(int *array);
/* Destroys the given array. */

int int_get(int *array, int index);
/* Returns the value of array[index]. */

int int_set(int *array, int index, int value);
/* Sets array[index] = value.  Returns value. */

// -----------------------------------------------------------------------
// Floating point
// -----------------------------------------------------------------------

%subsection "Floating Point Arrays"
/* The following functions provide access to arrays of floats and doubles. */

%{
	.. Supporting C code ...
%}
double *double_array(int nitems);
/* Creates a new array of doubles. nitems specifies the number of elements.
   The array is created using malloc() in C and new() in C++. */

void double_destroy(double *array);
/* Destroys the given array. */

double double_get(double *array, int index);
/* Returns the value of array[index]. */

double double_set(double *array, int index, double value);
/* Sets array[index] = value.  Returns value. */

float *float_array(int nitems);
/* Creates a new array of floats. nitems specifies the number of elements.
   The array is created using malloc() in C and new() in C++. */

void float_destroy(float *array);
/* Destroys the given array. */

float float_get(float *array, int index);
/* Returns the value of array[index]. */

float float_set(float *array, int index, float value);
/* Sets array[index] = value.  Returns value. */

// -----------------------------------------------------------------------
// Character strings
// -----------------------------------------------------------------------

%subsection "String Arrays"

%text %{
The following functions provide support for the 'char **' datatype.   This
is primarily used to handle argument lists and other similar structures that
need to be passed to a C/C++ function.
%}

#if defined(SWIGTCL)
%text %{
To convert from a Tcl list into a 'char **', the following code can be used :

     # $list is a list
     set args [string_array expr {[llength $list] + 1}]
     set i 0
     foreach a $list {
        string_set $args $i $a
        incr i 1
     }
     string_set $i ""
     # $args is now a char ** type
%}
#elif defined(SWIGPERL)

%text %{
To convert from a Perl list into a 'char **', code similar to the following
can be used :

    # @list is a list
    my $l = scalar(@list);
    my $args = string_array($l+1);
    my $i = 0;
    foreach $arg (@list) {
        string_set($args,$i,$arg);
        $i++;
    }   
    string_set($args,$i,"");

(of course, there is always more than one way to do it)
%}
#elif defined(SWIGPYTHON)

%text %{
To convert from a Python list to a 'char **', code similar to the following
can be used :

    # 'list' is a list
    args = string_array(len(list)+1)
    for i in range(0,len(list)):
	string_set(args,i,list[i])
    string_set(args,len(list),"")
%}

#endif

%{
	... Supporting C code ...
%}
char **string_array(int nitems);
/* Creates a new array of strings. nitems specifies the number of elements.
   The array is created using malloc() in C and new() in C++. Each element
   of the array is set to NULL upon initialization. */

void string_destroy(char *array);
/* Destroys the given array. Each element of the array is assumed to be
   a NULL-terminated string allocated with malloc() or new().  All of
   these strings will be destroyed as well. (It is probably only safe to
   use this function on an array created by string_array) */

char *string_get(char **array, int index);
/* Returns the value of array[index]. Returns a string of zero length
   if the corresponding element is NULL. */

char *string_set(char **array, int index, char *value);
/* Sets array[index] = value.  value is assumed to be a NULL-terminated
   string.  A string of zero length is mapped into a NULL value.  When
   setting the value, the value will be copied into a new string allocated
   with malloc() or new().  Any previous value in the array will be
   destroyed. */
</pre></blockquote>
<p>
In this file, all of the declarations are placed into a new section.  We specify formatting information for our section.  Since this is a general purpose library file, we have no idea what formatting our parent might be using so an explicit declaration makes sure we get it right. Each comment contains preformatted text describing each function.   Finally, in the case of the string functions, we are using a combination of conditional compilation and documentation system directives to produce language-specific documentation.   In this case, the documentation contains a usage example in the target scripting language.<p>
<p>
When processed through the ASCII module, this file will produce documentation similar to the following :<p>
<p>
<blockquote><pre>7.  SWIG C Array Module
=======================

%include array.i

This module provides scripting language access to various kinds of C/C++
arrays. For each datatype, a collection of four functions are created :

   &lt;type&gt;_array(size)              : Create a new array of given size
   &lt;type&gt;_get(array, index)        : Get an element from the array
   &lt;type&gt;_set(array, index, value) : Set an element in the array
   &lt;type&gt;_destroy(array)           : Destroy an array

The functions in this library are only low-level accessor functions
designed to directly access C arrays.  Like C, no bounds checking is
performed so use at your own peril.

7.1.  Integer Arrays
--------------------
The following functions provide access to integer arrays (mapped
onto the C 'int' datatype.   


int_array(nitems)
        [ returns int * ]
        Creates a new array of integers. nitems specifies the number of elements.
        The array is created using malloc() in C and new() in C++.   
        
int_destroy(array)
        [ returns void  ]
        Destroys the given array.   
        
int_get(array,index)
        [ returns int  ]
        Returns the value of array[index].   
        
int_set(array,index,value)
        [ returns int  ]
        Sets array[index] = value.  Returns value.   
        
7.2.  Floating Point Arrays
---------------------------
The following functions provide access to arrays of floats and doubles.   


double_array(nitems)
        [ returns double * ]
        Creates a new array of doubles. nitems specifies the number of elements.
        The array is created using malloc() in C and new() in C++.   
        
double_destroy(array)
        [ returns void  ]
        Destroys the given array.   
        
double_get(array,index)
        [ returns double  ]
        Returns the value of array[index].   
        
double_set(array,index,value)
        [ returns double  ]
        Sets array[index] = value.  Returns value.   
        
float_array(nitems)
        [ returns float * ]
        Creates a new array of floats. nitems specifies the number of elements.
        The array is created using malloc() in C and new() in C++.   
        
float_destroy(array)
        [ returns void  ]
        Destroys the given array.   
        
float_get(array,index)
        [ returns float  ]
        Returns the value of array[index].   
        
float_set(array,index,value)
        [ returns float  ]
        Sets array[index] = value.  Returns value.   
        
7.3.  String Arrays
-------------------

The following functions provide support for the 'char **' datatype.   This
is primarily used to handle argument lists and other similar structures that
need to be passed to a C/C++ function.

To convert from a Python list to a 'char **', code similar to the following
can be used :

    # 'list' is a list
    args = string_array(len(list)+1)
    for i in range(0,len(list)):
	string_set(args,i,list[i])
    string_set(args,len(list),"")

string_array(nitems)
        [ returns char ** ]
        Creates a new array of strings. nitems specifies the number of elements.
        The array is created using malloc() in C and new() in C++. Each element
        of the array is set to NULL upon initialization.   
        
string_destroy(array)
        [ returns void  ]
        Destroys the given array. Each element of the array is assumed to be
        a NULL-terminated string allocated with malloc() or new().  All of
        these strings will be destroyed as well. (It is probably only safe to
        use this function on an array created by string_array)   
        
string_get(array,index)
        [ returns char * ]
        Returns the value of array[index]. Returns a string of zero length
        if the corresponding element is NULL.   
        
string_set(array,index,value)
        [ returns char * ]
        Sets array[index] = value.  value is assumed to be a NULL-terminated
        string.  A string of zero length is mapped into a NULL value.  When
        setting the value, the value will be copied into a new string allocated
        with malloc() or new().  Any previous value in the array will be
        destroyed.   
        
</pre></blockquote>
<a name="n10"></a><h2> ASCII Documentation</h2>
The ASCII module produces documentation in plaintext as shown in the previous example.  Two formatting options are available (default values shown) :<p>
<p>
<blockquote><pre>ascii_indent = 8
ascii_columns = 70

</pre></blockquote>
`<tt>ascii_indent</tt>' specifies the number of characters to indent each function description.   `<tt>ascii_columns</tt>' specifies the width of the output when reformatting text.<p>
<p>
When reformatting text, all extraneous white-space is stripped and text is filled to fit in the specified number of columns.   The output text will be left-justified.    A single newline is ignored, but multiple newlines can be used to start a new paragraph.   The character sequence `\\' can be used to force a newline.<p>
<p>
Preformatted text is printed into the resulting output unmodified although it may be indented when used as part of a function description.<p>
<a name="n11"></a><h2> HTML Documentation</h2>
The HTML module produces documentation in HTML format (who would have guessed?).  However, a number of style parameters are available  (shown with default values)<p>
<blockquote><pre>
html_title = "&lt;H1&gt;:&lt;/H1&gt;"
html_contents = "&lt;H1&gt;:&lt;/H1&gt;"
html_section = "&lt;HR&gt;&lt;H2&gt;:&lt;/H2&gt;"
html_subsection = "&lt;H3&gt;:&lt;/H3&gt;"
html_subsubsection = "&lt;H4&gt;:&lt;/H4&gt;"
html_usage = "&lt;B&gt;&lt;TT&gt;:&lt;/TT&gt;&lt;/B&gt;"
html_descrip = "&lt;BLOCKQUOTE&gt;:&lt;/BLOCKQUOTE&gt;"
html_text = "&lt;P&gt;"
html_cinfo = ""
html_preformat = "&lt;PRE&gt;:&lt;/PRE&gt;"
html_body = "&lt;BODY bg_color=\"#ffffff\"&gt;:&lt;/BODY&gt;"
</pre></blockquote>
<p>
Any of these parameters can be changed, by simply specifying them after a <tt>%title</tt> or <tt>%section</tt> directive.  However, the effects are applied globally so it probably makes sense to use the <tt>%style</tt> directive instead.  For example :<p>
<p>
<blockquote><pre>%style html_contents="&lt;HR&gt;&lt;H1&gt;:&lt;/H1&gt;"
... Rest of declarations ...

</pre></blockquote>
Each tag uses a ":" to separate the start and end tags.   Any text will be inserted in place of the ":".  Since strings are specified in SWIG using quotes, any quotes that need to be inserted into a tag should be escaped using the "\" character.<p>
<p>
Sample HTML output is shown below :<p>
<p><a href="ch5.2.png">Sample Screenshot 1 </a><p>
<p>
<p>
Since our example used preformatted text, the output is very similar to the ASCII module.  However, if you use the default mode, it is possible to insert HTML markup directly into your C comments for a more personalized document.<p>
<p>
For navigation within the document, SWIG also produces a table of contents with links to each section within the document.  With a large interface, the contents may look something like this :<p>
<p><a href="ch5.3.png">Sample Screenshot 2 </a><p>
<p>
<p>
<a name="n12"></a><h2> LaTeX Documentation</h2>
The LaTeX module operates in a manner similar to the HTML module.  The following style parameters are available (some knowledge of LaTeX is assumed).<p>
<blockquote><pre>
latex_parindent = "0.0in"
latex_textwidth = "6.5in"
latex_documentstyle = "[11pt]{article}"
latex_oddsidemargin = "0.0in"
latex_pagestyle = "\\pagestyle{headings}"
latex_title = "{\\Large \\bf :} \\\\\n"
latex_preformat = "{\\small \\begin{verbatim}:\\end{verbatim}}"
latex_usage = "{\\tt \\bf : }"
latex_descrip = "{\\\\\n \\makebox[0.5in]{} \begin{minipage}[t]{6in} : \n 
\\end{minipage} \\\\";
latex_text = ":\\\\"
latex_cinfo = "{\\tt : }"
latex_section = "\\section{:}"
latex_subsection = "\\subsection{:}"
latex_subsubsection = "\\subsubsection{:}"

</pre></blockquote>
The style parameters, well, look downright ugly.   Keep in mind that the strings used by SWIG have escape codes in them so it's necessary to represent the `\' character as `\\'.   Thus, within SWIG your code will look something like this :<p>
<p>
<blockquote><pre>%style latex_section="\\newpage \n \\section{:}"
</pre></blockquote>
<p>
The default values should be sufficient for creating a readable LaTeX document in any case you don't want to worry changing the default style parameters.<p>
<a name="n13"></a><h2> C++ Support</h2>
C++ classes are encapsulated in a new subsection of the current section.  This subsection contains descriptions of all of the member functions and variables.  Since language modules are responsible for creating the documentation, the use of shadow classes will result in documentation describing the resulting shadow classes, not the lower level interface to the code.<p>
<p>
While it's not entirely clear that this is the best way to document C++ code, it is a start (and it's better than no documentation).<p>
<a name="n14"></a><h2> The Final Word?</h2>
Early versions of SWIG used a fairly primitive documentation system, that could best be described as "barely usable."  The system described here represents an almost total rewrite of the documentation system.  While it is, by no means, a perfect solution, I think it is a step in the right direction.     The SWIG library is now entirely self-documenting and is a good source of documentation examples.   As always suggestions and improvements are welcome.<p>
<p>
<p>

<p><hr>

<address>SWIG 1.1 - Last Modified : Mon Aug  4 10:46:55 1997</address>
</body>
</html>