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

[Frederik Fouvry]

| 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>.
| 
| 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.

May be due to the incomplete implementation of the style sheets.
Dunno.  The article should have other info anyway (that may well
be the cause of the empty page: the style sheets expect that, and
generate an empty page if you don't give anything).  It's only
enforced in KDE through book because that's the standard document
element.

If my previous assumptions are true, you get a bad result because
<article> is used as a hack.  ;-) The solutions seems to be to
make a book out of it, with a <reference> (or <chapter>) element,
followed by a <bibliography>.  In the refentry, you can refer to
the bibliography.  Or still: mark up the bibliography with other
means (a list).  It's not as nice, but if there's no other way to
do it (and the solution proposed above does not satisfy), then
you can get dispensation from me on this issue.

I don't see another way with the current DTD.  You may also want
to raise the issue with the DocBook people: that one sometimes
wants a bibliography in refentries.  They'll certainly think
about it.

| 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.

Page breaks are a matter of style sheets, not of markup.
The Duck Book says about refentries:

Formatted as a displayed block. It is not uncommon for RefEntrys
to introduce a forced page break in print media.

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

Frederik