RE: DOCBOOK-APPS: "Abbreviated" DocBook (notice about doxygen)

[David Cramer <david_cramer@broadjump.com>]

> -----Original Message-----
> From: Prikryl,Petr [mailto:PRIKRYLP@skil.cz]
> Sent: Friday, January 11, 2002 2:14 AM

> The below mentioned links are not dead!  All of them work 
> for me. The last public release of doxygen (1.2.13.1) was 
> released in January 5, 2002 (so quite fresh, isn't it?).

Yes, I tried a little later and the links were working for me. Must have
been a brief outage somewhere. That's why I mentioned that it's a mature
tool with a solid user base, so folks would know to keep trying in case
the links were cold when got my post. 

> Being one of the contributors to the development (not directly
> working on XML part), I can tell
> you that it generates XML as one of its output.  It is currently
> really experimental part of doxygen and others work hard
> on that.  As far as I know, the XML output will probably become
> a kind of intermediate (internal) form of the generated results.
> It is primarily tailored to capture details generated by doxygen.
> Then, the set of generators then will produce final output
> formats.

Right--that's what I was getting at. The original post asked about
getting code into docbook refentries without doing so much markup by
hand. Doxygen potentially does this one better--pull the information,
including comments, directly out of the source code into doxygen's xml
format. Once it's in xml, you can write xsl stylesheets to transform it
into docbook to incorporate it into existing documentation that's in
docbook and/or use existing stylesheets to go to a particular output.
Likewise you could select, sort, combine, and generally munge the data
in various ways with xsl. 

As I mentioned, I haven't played with doxygen's xml output, but it
shouldn't be too hard. I'm assuming, for example, that since doxygen
does automatic hyperlinking of classnames and such when it finds them in
the code comments for html output (as you mention), that it puts
semantically meaningful tags around those classnames in the xml output
and including the raw material for a link. I'd be pretty surprised if it
didn't. Your xsl simply transforms this markup into <classname> and
<link> tags. 

If anybody has already written doxygen2docbook xsls, I hope they're
sharing them with the rest of the world :)
 
> There definitely are people among doxygen users who would
> like to see DocBook XML as one of the final output form.
> This is not the case, yet.  It would be nice to attract some
> of the DocBook experts to doxygen development to accelerate
> the DocBook XML generator development.
> 
> These days, doxygen produces the following final outputs:
> HTML, LaTeX sources, RTF, man, and the mentioned XML
> with the generated texts in one of the 25 human languages.

Doxygen's other output formats are so good already that it you may not
feel the need to use the xml output to go to docbook. You may instead
prefer to write overview pages in docbook, spin that to html to be
picked up by doxygen. 
 
> I personally appreciate that the doxygen comments inside
> my C++ sources are really brief and intuitive in syntax.
> They fit to programmer's need -- no need to learn details
> of documentation systems.  Still, doxygen produces nice,
> highly configurable output with automatically generated
> hyperlinks (if applicable), and with automatically generated
> images (clickable in HTML) that capture dependencies
> and relations inside your developed system.

I can't imagine doing api documentation any other way. 

Thanks for the information!

David

> Hope this helps,
> 
>  Petr
> ---
> Petr Prikryl, Skil, spol. s r.o., (prikrylp@skil.cz)
> 
> 
> > -----Original Message-----
> > From:	David Cramer [SMTP:david_cramer@broadjump.com]
> > Sent:	Thursday, January 10, 2002 6:28 AM
> > To:	Kevin Atkinson; docbook-apps@lists.oasis-open.org
> > Subject:	RE: DOCBOOK-APPS: "Abbreviated" DocBook
> > 
> > I haven't played with the feature so I don't know for certain if it
> > would work for you, but the automatic documentation tool 
> Doxygen has xml
> > as one of it's output types. You could write an xslt  to 
> convert that
> > output to whatever you need. 
> > 
> > This is (or perhaps was) the link
> > <http://www.stack.nl/~dimitri/doxygen/>. It's cold right now. 
> > http://freshmeat.net/projects/doxygen/ lists 
http://www.doxygen.org/ as
> the homepage, but that's dead too now. Perhaps they're moving or
> something--it's a mature tool with a strong community supporting it.