[kde-guidelines] CVS
Frans Englich
frans.englich at telia.com
Wed Nov 3 00:57:25 CET 2004
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
More information about the kde-guidelines
mailing list