[kde-guidelines] CVS

[Frans Englich]

On Friday 29 October 2004 02:09, Frans Englich wrote:
<SNIP>
> > I can pretty simply turn a <classname>KSomething</classname> into a link
> > directly to the API documentation.

No, we're thinking in the wrong direction.

Isn't it lame that links only show up in one format, that the API has its own 
navigation/style, that it doesn't work in print, and that it's thrown in its 
own corner? Wouldn't it be nice if we had the API reference under the 
framework; navigation, styles, references, and so forth?

Currently, api.kde.org uses plain-old html Doxygen output, but we could change 
that -- especially if we're going to turn up side down on 
developer.kde.org/guidelines anyway. I know Doxygen have XML output, and 
writing XSLTs for converting to Docbook wouldn't be that much of work, I 
think.

The end result would be that _all_ developer documentation would be nicely 
integrated, have a consistent look, work in print, use the same navigation, 
references/links would be perfect -- and all of it would be available in all 
output formats we tell it to produce.

How hard is it, C++Doxygen->Docbook, then? I'm investigating..

(The principle is similar to the PC market; once one enters, it's on the high 
speed, cheap, multifold market. When we convert to Docbook that means we're 
open to all the Docbook 3rd party projects out there(and it amazes me how 
large of a de-facto standard Docbook is). Much functionality in the API 
reference will come for free.)

>
> Nice, can you post the template? I had a look, and I couldn't find out how
> to do it without knowing what library the class was part in, in order to
> generate a proper URL(functions was even worse for me, they needed the
> class & library).

But nevertheless, I would like to know, it could be useful. (is there an "I am 
lucky" search interface?)

>
> Also, could we use <section> instead of <sectX>? Would save work when
> reorganizing, and easy to do when we're from scratch(sectX's will probably
> be obsoleted in newer versions, also).

?


Cheers,

		Frans