[kde-guidelines] Fwd: Re: The Path to Docbook Support

[Frans Englich]

I mailed Dimitri(author of Doxygen) about converting C++Doxygen to Docbook. 
Below is his response.

----------  Forwarded Message  ----------

Subject: Re: The Path to Docbook Support
Date: Tuesday 02 November 2004 07:09
From: Dimitri van Heesch <dimitri at stack.nl>
To: Frans Englich <frans.englich at telia.com>

Hello Frans,

On Tue, Nov 02, 2004 at 01:03:21AM +0000, Frans Englich wrote:
> Hello Dimitri,
>
> I am investigating the possibilities for generating Docbook output via
> Doxygen from C++ code, for a major revitalization of KDE's documentation,
> which a group of devoted developers has intention to do. This major
> documentation project, whose active developer period will stretch over a
> long time, has in plans to convert existing developer documentation to
> Docbook, write new Human Interface Guidelines as well as for other topics
> such as graphics, and it was hence quickly realized that smooth integration
> with the API reference was of interest for the purpose of navigation,
> styling, referencing and so forth: we need Docbook output.
>
> From looking at the TODO/Wishlist:
> http://www.stack.nl/~dimitri/doxygen//todo.html
>
> it appears as Docbook output is yet not implemented. However, perhaps that
> will happen in the future, or that we(the guidelines developers) can
> implement it in Doxygen if that's not already under work(no promises or
> time scales).
>
>
> I have a couple of questions regarding this. Feel free to be as informative
> as necessary, in terms of comments, links to developer docs, and so forth,
> which those who are to implement Docbook support could need. If it is ok, I
> will forward your reply to our guidelines list, such that others can take
> part and look into it.
>
> * What is the current status/plans of Docbook output? Is anyone working on
> it? Is there a time frame on when it will be implemented?

So far no one is working on this and there is no planning yet as to when this
will start.

> * While knowing virtually nothing about Doxygen, except writing markup tags
> in C++ code, it appears to me that the simplest way to implement Docbook
> output would be to transform the XML output with XSLT into Docbook(or any
> other format for that matter). Hence; how good is the XML support? If, say,
> KDE's C++ reference took its path through the XML output, would then the
> condition of the XML output feature be the bottle neck, in terms of markup
> support, stability, and so forth? Is there anything which XML output
> currently doesn't support? If so, what are the time frames of when it will
> be
> corrected/extended?

I think the XML output is quite good and stable as it is. I believe there
is not much missing with respect to features (although occasionally some
 minor omissions are found). The output does reflect the way things are
 stored in doxygen internally, so this may not be ideal in all cases, but if
 you do not want to generate a completely different type of documentation it
 is
probably fine.

> * I know nothing about Doxygen's XML output format, but what are your
> estimations on how difficult/feasible it would be to write XSLTs converting
> XML output to Docbook, assuming one is "reasonable" comfortable with XSLT?
> Would there be capabilities one would have to let go, and if so, which
> ones? If not transforming XML to Docbook is the proper way, how should it
> be done then?

Going from XML to Docbook is a good approach (though I do not know XSLT that
well so I never designed the XML output to be easy to use for XSLT, any
improvement suggestions in this respect are welcomed though).

Have a look at boost's documentation system:
http://www.boost.org/doc/html/boostbook.html
Apparently they use tools to convert doxygen's XML into Docbook already!

Hope this helps,

Regards,
  Dimitri

-------------------------------------------------------

I checked out BoostBook and AFAICT Dimitri is right -- it does 
doxygen->docbook conversion. So, all it requires is some (major) integration 
work, perhaps a day or two of work :)

I'll have a look at it when I start working on developer.kde.org.


Cheers,

		Frans