[kde-doc-english]hitting the limits of kioslave documentation

[Lauri Watts]

On Wednesday 12 February 2003 23.38, Leo Savernik wrote:
> Hello,
>
> I'm documenting the data kioslave. As the document is intended as a
> reference manual for data url usage with detailed syntax explanation and
> examples, I need to structure it.

If you want to write a full blown manual, then do so, using the normal 
template (a <book>, not an <article> for example.)  Then provide a .desktop 
file with a DocPath entry so that KHelpcenter can find it.  Now write a short 
overview with brief examples, in line with the rest of the kioslave docs for 
displaying in kinfocenter, and provide a link to the help:/yourkioslave/ doc 
for more information, where readers can see the entire manual.  

See kdelibs/kdoctools/template.docbook for the standard template.  If this is 
for a KDE CVS module, it should go in <module>/doc/<appname>/index.docbook. 

I am going to guess just changing to a book, and your existing work will be 
fine (the two are very similar, article had some small advantage in the 
particular case of kinfocenter that I can't actually remember right now - 
it's the only place we use the article DTD however.)   Probably your current 
introduction and a couple of brief examples will be enough in kinfocenter 
itself. 

> I wanted to use man page-like sections by using a <refentry>, but this
> element and all its children are not displayed (in the KDE Info Center).

Fullblown documentation including refentries are absolutely outside the scope 
of kinfocenter.  It's not a help viewer - but KHelpCenter is.  I can fully 
imagine that in future even the limited rendering available in KInfoCenter 
may be removed.

> Then I tried <section>, but only the first section is ever rendered, using
> <sect1> instead exhibits the same symptoms. Lauri Watts told me in
> kde-devel that this was a kioslave documentation restriction.

The <section> tag is not used anywhere in KDE, and may have unpredictable 
results upon rendering (or, it might be perfectly fine, it's just an unknown 
case.)  If you want a nested hierarchy, it's better to use <sect(n)> 
elements, but this is a stylistic issue where KDE style is to use the 
numbered version.

> After that I resorted to using <simplesect> instead of <section>. It works
> -- its only disadvantage is that is must not be nested this forcing me to
> flatten the hierarchy (the original nesting was only two levels deep, so
> the <simplesect> workaround is acceptable for me).

Simplesect is (see above what I wrote for <section>) 

> There's still one issue left. I'd like to insert a bibliography entry for
> the associated rfc, but that doesn't work either. Is there anything like a
> "lightweight" bibliography entry that will also display under kioslave
> docs?

No.  Definitely do that in a complete manual.

For your .desktop file, you can hide the entry from appearing in the KDE menu, 
but we need it for KHelpCenter. You should add a line for the doc: 
DocPath=yourkioslave/index.html 
You probably will want to assign it an icon, as normal, and you can use this:
X-KDE-ParentApp=kinfocenter to have it appear under the kinfocenter top level 
menu in KHelpCenter, rather than under the applications tree.  The Desktop 
file probably needs to have an unique name, not the same as the .protocol 
file that you use for the same kioslave (so <yourkioslave>doc.desktop, for 
example.)

Hopefully that clears things up, however you raise a couple of points that we 
should definitely keep in touch on, if you don't mind, in particular I'd like 
to see a draft of your doc once the bibliography is done, so we can take a 
look at the HTML rendering, in case our stylesheets need a little work.

Regards,
-- 
Lauri Watts
KDE Documentation: http://i18n.kde.org/doc/
KDE on FreeBSD: http://freebsd.kde.org/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: signature
Url : http://mail.kde.org/pipermail/kde-doc-english/attachments/20030213/d3265985/attachment.sig