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

[Lauri Watts]

On Thursday 13 February 2003 19.20, Leo Savernik wrote:

> I copied the man-template.docbook and preliminarily changed some data in it
> to see if it worked -- and it indeed worked, it was exactly the format I
> want this document to have. However, <refentry> doesn't allow
> <bibliography>, so I wanted to be smart and wrapped the whole doc in an
> <article> element and inserted the bibliography after </refentry>.

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.  

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.

> Well, I was outsmarted. The resulting document still works, but it doesn't
> fit into one single page anymore. It's three pages instead whose first page
> is blank (dunno why), the second contains the <refentry> and the third the
> <bibliography> element.

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, 

> Is there any possibility to suppress the page breaks in an <article>? If
> not, I'll throw the bibliography away and stick to a document using
> <refentry> as root.

Just use the proper template - the user manual, template.docbook, if it's a 
user manual you are writing.

> The attachment contains the offending docbook. It mostly consists of the
> default blurb and the bibliography entry.

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.

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.

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/20030214/a3e033ba/attachment.sig