[Doxygen-users] Can doxygen do this (including not only examples, but also their output )?

[Stephan P. <ste...@gm...>]

Hi everyone,

I'm new to doxygen and I'm currently trying to figure out whether it's
the right tool for the job. I believe it is, since I've done a few
tests, but before I run into a time-consuming dead end I just wanted to
ask if anybody can tell me weather certain things are indeed possible.

The "job" is the manual for a code library (from the area of
thermochemistry, if anyone cares to know :-) ), and it does NOT involve
documenting the source code of the library itself. Actually, it doesn't
even matter in which language the library is coded (it's Fortran), since
doxygen doesn't need to touch this code.

The key components of the documentation are:

- Free flowing text with tables, graphics, lists, links, etc. (no
problem for doxygen, although I did have to improvise a little already
in my tests :-) )

- short (but complete) example programs that illustrate the use of all
the functions the library provides, currently in C and Fortran, but
potentially later also in Pascal/Python/Java.

The latter is where I'm currently not 100% sure whether and how it can
be done with doxygen, since what I would like to do looks like this:

http://gtt.mch.rwth-aachen.de/gtt-web/Software/ChemApp/CAL-DOC/cal62.html#l100

(This is btw. an older version of the documentation which I started in
the late 90s, I used "Yodl" for this, plus a number of custom Perl
scripts run via Makefiles for pre- and postprocessing. But I'd like to
move away from Yodl to a more "active" tool with a larger user base...)

You can see that I splice chunks of output of the very sample programs
into the documented code. In fact, the output is generated from the
current version of the library automatically right before the
documentation is made.

Some example programs write the calculated results to output files that
I process with gnuplot into images and again insert back into the
documented code:

http://gtt.mch.rwth-aachen.de/gtt-web/Software/ChemApp/CAL-DOC/cal81.html#l122

Another important detail is that all calls to the library's few dozen
subroutines are all cross-linked. This is normally not a problem for
doxygen, but in my case I am *not* scanning the source code of the
library, and using \fn instead does not seem to the trick yet.

I did have a look at \dontinclude and related commands, but out of the
box none of them quite seem to fit my bill...

Does anybody out there use doxygen in such a way? Is that possible? One
way or the other I'm sure it is, but I'd like to get a feeling for how
easy or tricky it is, in order to judge how big a project the conversion
from Yodl to doxygen would be.

Thanks in advance for any pointers,

Stephan