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

[Leo Savernik]

Am Freitag, 14. Februar 2003 12:17 schrieb Lauri Watts:
[...]
>
> That's because man-template is not intended for use generating HTML, it's
> intended to be used with a quite different xslt stylesheet to generate
> *roff man pages :)
>
> If you want to write a user manual, use the user manual template in
> template.docbook.  You can include refentries in such a document, the
> template indeed does so as an example.  This is *not* going to be usable
> within kinfocenter however, and that's because it's not what kinfocenter is
> intended to display.

The problem with the <book> template is that it forces the use of chapters 
(which break pages each). My manual is just a bordercase that's too 
complicated for info center and too short to justify spanning multiple 
chapters.
>
> If you want to write a one page short overview suitable for use in
> kinfocenter, base it on an article, use no nested hierarchy.
>
> There's absolutely no reason you can't do both, it is absolutely not a
> problem if your application has two documents, because there are two
> intended uses and two intended audiences.  Kinfocenter for those who just
> want a quick overview of what a kioslave might offer, in the context of a
> long list of the slaves they have installed, and KHelpCenter for those who
> want an in depth user manual.

I finally did that. I now have two documents. A very primitive introduction in 
kdebase/doc/kioslave/data.docbook and a man-page like thorough description in 
kdebase/doc/dataprotocol/ (not committed yet). The data.docbook links to the 
dataprotocol implementation.
>
[...]
> Writing for a particular rendering in HTML is doomed to failure, because
> DocBook is semantic markup, not presentational the way .  Write for
> content, mark things up with what they *are* not based on how they render
> in HTML, and using the appropriate templates.    We could change tomorrow
> where the pagebreaks are in a document for example, and it wouldn't have
> the slightest effect on your actual content.  Once you get past the idea
> that the presentation is out of your hands,

I agree fully with you on the presentation vs. content issue. I'm only trying 
to find the type of document that fits my needs best, and so far it seems 
I've been unlucky :-(
>
[...]
>
> With our KDE stylestheets, it's going to be chunked into one page per major
> section no matter what you do, when using refentries and a bibliography.

<article> html conversion seems fishy though. The first page is called 
index.html, the second dataprotocol-1.html, the third .html (only 
extension!). I don't think it's a mistake of mine as the docbook validates 
and contains what I want it to contain (and nothing more).

I'd like to announce the following proposal for the rendering of <article>s:
Have articles span exactly one page and no more than one page. You already 
mentioned that articles are not used except for each infocenter kioslave 
description and each of those articles is not meant to ever span more than 
one page. Therefore I consider the impact of such a change negligably small 
to non-existant.
>
> I'll have a look at the work you've committed over the weekend.  The reason
> help:/dataprotocol isn't working, is probably that you need to install a
> .desktop file with a DocPath entry for that to happen.

I'm looking forward to hearing your opinion. The funny thing is I placed a 
.desktop file and the help document is found and displayed correctly, but in 
konqueror, not in khelpcenter. It's picking the right doc but the wrong app.
>
> Regards,