Re: [Doxygen-develop] Interest in new XML format for Doxygen export

[Ted D. <ted...@jp...>]

Dimitri,
I think the changes can be summarized like this:

Doxygen outputs an XML schema that is mostly an XML representation of 
the HTML documentation.  This means that for a given element (say a 
function), the "data" (arguments, short description, long 
description, etc) for that element is stored in several locations and 
sometimes the same data is stored in multiple locations.

I hope I'm not putting words in Jason's mouth but the here my take on 
his changes:  The goal of the change is to make an XML schema that is 
a representation of the data that doxygen has parsed and created, not 
a representation of the HTML.  This would make it much easier to 
write XML style sheets and applications to process this documentation 
into different formats (like heavily customized HTML).

We really need something like this because we're combining 
documentation from user's guides, C++, and Python into a single 
documentation repository that needs to have a common style for how 
the various constructs are shown.  I think that a big part of the 
benefit of this representation is that it makes all of the good 
things that doxygen does more accessable.  It's difficult to dig 
through the doxygen C++ data structures in order to make custom 
documents (and it's hard to keep patches up to date, etc).  By having 
doxygen do the parsing, grouping, cross-linking, etc and then 
outputting that in XML, we can write stand-alone XML processing 
engines that do our customization work without having to understand 
or change the doxygen internals.

Ted

At 11:37 AM 12/16/2007, Dimitri van Heesch wrote:
>Hi Jason,
>
>I'm interested in what you have been working on, so please tell us 
>more about it.
>
>Building doxygen should not be a significant problem:
>Doxygen does build with Studio 2005 (even with the free (as in beer) 
>express version),
>or with cygwin (or mingw), so it should not be a problem to get that 
>working on your system.
>If you have a patch against 1.5.1 that may already be useful.
>
>Regards,
>   Dimitri
>
>On Dec 15, 2007 5:27 AM, Jason McKesson 
><<mailto:ko...@gm...>ko...@gm...> wrote:
>I actually have this about 90% working (only a few of Doxygen 
>features are not exported), and have had it around for some time. 
>But there is a significant problem. Namely, that my changes are 
>built against Doxygen 1.5.1, and the latest releases of Doxygen do 
>not support Visual Studio 2003, which I use. If it uses a meta-build 
>system like CMake or Premake that could export build files for 
>virtually any development environment, then I could upgrade Doxygen 
>and submit it as a patch.
>
>
>Ted Drain wrote:
>>
>>Jason,
>>
>>I would love to see something like this included.  We use doxygen to
>>
>>create a reference manual for C++ software that's used by people
>>
>>through a Python interface.  It's a ton of work to munge the output
>>
>>documentation to something is Python-like that people can
>>
>>understand.  If we had a good XML format, this type of work could all
>>
>>be done through XSLT or XML processing.
>>
>>
>>Ted
>>
>>
>>Jason McKesson <mailto:korval2@gm...><korval2@gm...>:
>>
>>
>>>
>>>I am currently working on exporting a new XML format from Doxygen. I was
>>>
>>>wondering if there would be some interest in integrating this into the main
>>>
>>>line when it is finished.
>>>
>>>
>>>If you want more details about how this format differs from the current
>>>
>>>Doxygen XML format, please let me know.
>>>
>>>
>>
>>Ted Drain     Jet Propulsion 
>>Laboratory   <mailto:ted...@jp...>ted...@jp...
>>