Author: Greg Rowe <greg-tcldox@therowes.net>

No longer maintained
--------------------

I am no longer maintaining tcl-dox.  It started as a fun experiment
but I've lost interest.  Tcl-dox is highly error prone and difficult
to maintain because it is based on regular expressions.  I may work on
a new version of tcl-dox that uses libtcl and the Tcl_ParseCommand
function to do far more robust and reliable translations.  ...But time
is scarce and I can't promise that I'll ever get around to that.

0.8.3 is the my final release.


Introduction
------------

Tcl-dox is a filter that translates Tcl code into C++-like code so
that Doxygen [0] can generate documentation for it.  I would like to
thank my employer, Impact Technologies [1] for allowing me to
distribute this under the GPL.  I would also like to thank those
people that have taken the time to write to me seeking help,
providing feedback, and contributing code.

The filter is pretty basic at this point and I fully expect that it
will not cover all of the TCL syntax.  ...But you've got the source
and I'm open to applying your patches or making additions/fixes based
on your feedback.  If you have some TCL syntax that the filter doesn't
handle please send me the TCL source and I will improve the filter so
that it can handle the syntax.

TCL isn't parsed like most languages are which is why this filter
exists rather than creating a full fledged scanner and parser for
Doxygen.  It would be nice to add proper support to Doxygen for tcl
but I do not know of a good way to do so.


Building Tcl-Dox
----------------

To build tcl-dox you need flex or another comparable scanner
generator.  Flex is readily available on almost all UNIX-like systems.
Flex is distributed with cygwin.  A Makefile is provided that should
work on most systems.

$ cd src
$ make 

If all went well you should have `tcl-dox` (or tcl-dox.exe) in the src
directory.  Now you should install it in your $PATH.  The following is
just an example.

$ cp tcl-dox /usr/local/bin

If you get errors that look like the ones below install m4.

$ make
flex  -t tcl-dox.l > tcl-dox.c
flex: fatal internal error, exec failed
make: *** [tcl-dox.c] Error 1
rm tcl-dox.c


Using Tcl-Dox with Doxygen
--------------------------

To use the filter with Doxygen set FILTER_PATTERNS in your Doxyfile to
be *.tcl=tcl-dox.  With this setting Doxygen will run `tcl-dox` when
it encounters input files with a .tcl extension.  Doxygen runs filters
in the following manner:

        tcl-dox $inputFileName

I recommend installing tcl-dox in your $PATH.  You may be able to
specify the full path to the binary in FILTER_PATTERNS if you do not
wish to put tcl-dox in the $PATH.

If you turn on CALL_GRAPH and turn off FILTER_SOURCES then Doxygen
will not generate call graphs.  To fix this Doxygen would have to do a
two-pass scanning mechanism and that is not currently planned.  

Included with the source code is an example Doxyfile.  The file adds
*.tcl FILE_PATTERNS as well as setting FILTER_PATTERNS as described
above.  I highly recommend installing dot and turning on CALL_GRAPHS.


Documenting Your Code
---------------------

The easiest way to see how to markup TCL code is with an example.
There are a couple of simple examples in the 'examples' directory.
Also see the Doxygen website [0] for a full manual on using Doxygen.



Contacting me
-------------

If you find bugs or would like to contact me for whatever reason
please feel free to do so.  

Greg Rowe <greg-tcldox@therowes.net>


Footnotes
---------
[0] http://www.doxygen.org
[1] http://www.impact-tek.com
