API docs; functional or pretty?

[Frans Englich]

On Thursday 22 June 2006 19:08, Thomas Zander wrote:
> On Thursday 22 June 2006 20:40, Frans Englich wrote:
> > > What can we do with the problem Adriaan put forth that as long as the
> > > docs don't look and behave like the kde - site (which IMO makes them
> > > unusable) we can't have them on developer.kde.org?
> >
> > I vaguely recall having bounced DKO with Adriaan in private mail. I
> > have this idea of fully integrating all documentation concerning KDE,
> > API documentation, possibly user manuals, guidelines(HIG, HOWTOs, etc),
> > into the strongest and common denominator: Docbook.
>
> Docbook is a storage format and so your answer has little to do with my
> above question ;)

It is true that Docbook is storage, but sometimes one must look at that area 
too because it affect others, such as displaying.

> > By having everything in Docbook, we can link across everything(say,
> > from the HIG to a particular enum in a class), index across everything,
> > and export to whatever format you like, etc, etc. Of course,
> > considering I'm an XML geek, I'm having trouble breathing while
> > describing that.
>
> Read the (xml) tags files doxygen creates[1], it allows you to do all that
> while avoiding a conversion to docbook only to convert from docbook to a
> readable format later on again.

I don't see how.

Remember that only the API documentation is in doxygen, not any HOWTOs or 
guidelines. You can treat them separated, but that will prevent cross-linking 
and it will still be inconsistent. I think this demonstrates how an issue of 
storage format/backend, affects the end user result.

The tag files are neither not that interesting. Writing sensible stylesheets 
for that is a huge task, while Docbook XSL has some of the most well-written 
and most sophisticated stylesheets that can be found.

Of course, if ones only interest is to change the style of the current Doxygen 
output, bringing in Docbook makes little sense. But if one wants to look at 
the general inconsistency problem at DKO, I think looking in that direction 
is sensible.


Cheers,

		Frans