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

[Jason M. <ko...@gm...>]

BTW, I've discovered something about how Doxygen does linking to 
typedefs. If you use a typedef in a parameter, Doxygen links to the 
actual type being referenced by the typedef. While this is probably very 
useful in the finished format, it isn't useful for an intermediate 
format. XML tools can easily determine what the final type being 
referenced is, but going backwards is impossible. Also, the XML format 
outputs references as replacement for the string that was being 
referenced, so if you use a typedef as an argument, it is basically 
impossible to find out what the actual typedef used is.

It would be good if Doxygen could preserve this information internally, 
at the level of DocVisitor. This would allow the individual 
DocVisitor-derived classes to decide among themselves how best to 
represent a link to a typedef, rather than forcing everyone to link to 
the final type.

Ted Drain wrote:
> 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 <ko...@gm... 
>> <mailto: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.
>>