doxygen-develop

[Doxygen-develop] Comment diagrams

[Stathis S. <im...@sa...>]

Hello everyone, (sorry if you receive this twice)

I have developed a small Java utility that can generate PNG diagrams
from ascii-art:

http://ditaa.sourceforge.net

What I would like to know is, what you think is the best way to try and
integrate this into doxygen, so that any ascii-diagrams included in the
comments would be rendered and the appropriate <img> tag would be
inserted into the resulting HTML documentation.

I thought of using preprocessing, but wouldn't that require my
preprocessor to be able to parse comments in the same way that doxygen
does? (and what's worse, in all the languages doxygen parses!)

And another thing: do you think that's a worthwhile project (the
intergration with doxygen)

Thanks,

Stathis

[Doxygen-develop] Comment diagrams

[Stathis S. <im...@sa...>]

Hello,

I'm really glad that you liked ditaa, and that you tought it would be
useful. :-)

Before diving too deep into the (120k lines!) code to add the \ditaa and
\endditaa tags, I would like to ask for some pointers so that I don't
get lost.

It seems that I would need to add ditta and edditta to to cmdmapper.cpp
and cmdmapper.h.

Then I would need to modify config.l I'm not familiar with flex, so this
will be tricky...

I would propose to add the following entries in the configuration:

HAVE_DITAA: whether ditaa processing occurs (like HAVE_DOT)
DITAA_JAR: filename (with full path) of the ditaa jar file

Another thing is how you would pass command line parameters to ditaa
itself. How about the line after the \ditaa tag being reserved for that?
Example:

\ditaa no-shadows round-corners
+--+
|  |
+--+
\endditaa

or something of the kind.

Then I would probably have to add something to docparser.cpp so that
ditaa starts if the \ditaa tag is found in a comment. Also the
appropriate changes in htmlgen.cpp for the <img> tags to be inserted (I
suppose ditta would not be possible for other formats, it doesn't make
postscript yet!),

Am I making any sense at all? :-) Any tips/help would be very welcome.

Thanks

Stathis


-- 
________

Efstathios Sideris
Biomolecular Structure and Modelling Unit
Department of Biochemistry and Molecular Biology
University College London
Darwin Building, Gower Street
London WC1E 6BT, UK

Re: [Doxygen-develop] Comment diagrams

[Dimitri v. H. <di...@st...>]

Hi Stathis,

On Fri, Nov 19, 2004 at 06:53:18PM +0000, Stathis Sideris wrote:
> Hello,
> 
> I'm really glad that you liked ditaa, and that you tought it would be
> useful. :-)
> 
> Before diving too deep into the (120k lines!) code to add the \ditaa and
> \endditaa tags, I would like to ask for some pointers so that I don't
> get lost.
> 
> It seems that I would need to add ditta and edditta to to cmdmapper.cpp
> and cmdmapper.h.

Yes.

> Then I would need to modify config.l I'm not familiar with flex, so this
> will be tricky...

If you look for "dot" in scanner.l and replace it by ("dot"|"ditta")
and cases where "dot" is part of a or'ed construction already just append
a |"ditta" it should be fine. The part in scanner.l is just to skip 
\\ditta (i.e. the escaped version of the command), and not to 
interpret the section in between. I'll review if before including it.

> I would propose to add the following entries in the configuration:
> 
> HAVE_DITAA: whether ditaa processing occurs (like HAVE_DOT)
> DITAA_JAR: filename (with full path) of the ditaa jar file

Ok, just enter a section for these in config.l (one of type bool and the
other of type string). Then you can use Config_getBool("HAVE_DITAA") and
Config_getString("DITAA_JAR") in the rest of code.

> Another thing is how you would pass command line parameters to ditaa
> itself. How about the line after the \ditaa tag being reserved for that?
> Example:
> 
> \ditaa no-shadows round-corners
> +--+
> |  |
> +--+
> \endditaa
> 
> or something of the kind.
> 
> Then I would probably have to add something to docparser.cpp so that
> ditaa starts if the \ditaa tag is found in a comment. Also the
> appropriate changes in htmlgen.cpp for the <img> tags to be inserted (I
> suppose ditta would not be possible for other formats, it doesn't make
> postscript yet!),

Indeed. There are several commands with parameters already, so just look
at handleCommand in docparser.cpp.

> Am I making any sense at all? :-) Any tips/help would be very welcome.

Perfect sense. I think you covered all places where changes are needed.

Regards,
  Dimitri

Re: [Doxygen-develop] Comment diagrams

[Dimitri v. H. <do...@gm...>]

On 17 Nov 2004 18:19:13 +0000, Stathis Sideris <im...@sa...> wrote:
> Hello everyone, (sorry if you receive this twice)
> 
> I have developed a small Java utility that can generate PNG diagrams
> from ascii-art:
> 
> http://ditaa.sourceforge.net

Nice!

> What I would like to know is, what you think is the best way to try and
> integrate this into doxygen, so that any ascii-diagrams included in the
> comments would be rendered and the appropriate <img> tag would be
> inserted into the resulting HTML documentation.
> 
> I thought of using preprocessing, but wouldn't that require my
> preprocessor to be able to parse comments in the same way that doxygen
> does? (and what's worse, in all the languages doxygen parses!)

I would suggest to add a pair of commands (\ditaa .. \endditaa) 
to doxygen that work in a similar way as the \dot ... \enddot commands
(which can now be used to include graph descriptions and let dot
convert them into images).

> And another thing: do you think that's a worthwhile project (the
> intergration with doxygen)

Yes, I believe so.

Regards,
  Dimitri

Re: [Doxygen-develop] Comment diagrams

[Stefan K. <ko...@im...>]

Hi Stathis,

this is really cool. I've forwarded it to the gtk-doc mailinglist as well.
To me it looks like a good way to integrate simple diagraphs into source-code
docs. Such diagraphs that desribe concepts is something that imho is often
missing. The big advantage of your approach over e.g. dor is that your diagraphs
are readable in the source as well ;-)

Ciao
  Stefan

Stathis Sideris wrote:
> Hello everyone, (sorry if you receive this twice)
> 
> I have developed a small Java utility that can generate PNG diagrams
> from ascii-art:
> 
> http://ditaa.sourceforge.net
> 
> What I would like to know is, what you think is the best way to try and
> integrate this into doxygen, so that any ascii-diagrams included in the
> comments would be rendered and the appropriate <img> tag would be
> inserted into the resulting HTML documentation.
> 
> I thought of using preprocessing, but wouldn't that require my
> preprocessor to be able to parse comments in the same way that doxygen
> does? (and what's worse, in all the languages doxygen parses!)
> 
> And another thing: do you think that's a worthwhile project (the
> intergration with doxygen)
> 
> Thanks,
> 
> Stathis
> 
> 
> 
> -------------------------------------------------------
> This SF.Net email is sponsored by: InterSystems CACHE
> FREE OODBMS DOWNLOAD - A multidimensional database that combines
> robust object and relational technologies, making it a perfect match
> for Java, C++,COM, XML, ODBC and JDBC. www.intersystems.com/match8
> _______________________________________________
> Doxygen-develop mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-develop
> 

-- 
      \|/            Stefan Kost
     <@ @>           private            business
+-oOO-(_)-OOo------------------------------------------------------ - - -  -   -
|       __  Address  Simildenstr. 5     HTWK Leipzig, Fb IMN, Postfach 301166
|      ///           04277 Leipzig      04251 Leipzig
| __  ///            Germany            Germany
| \\\///    Phone    +49341 2253538     +49341 30766101
|  \__/     EMail    st_kost_at_gmx.net kost_at_imn.htwk-leipzig.de
|           WWW      www.sonicpulse.de  www.imn.htwk-leipzig.de/~kost/about.html
===-=-=--=---=---------------------------------- - - -  -    -