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

[Frederik Fouvry]

,-- On Fri, 14 Feb, Leo Savernik wrote:
| 
| Am Freitag, 14. Februar 2003 12:26 schrieb Frederik Fouvry:
| [...]
| >
| > 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.
| 
| <book> is far too big for this purpose. It'd contain chapters that had no more 
| than two paragraphs. <article> would just do, didn't it insist on the page 
| breaks.

Book is too big for many documentation packages (many are just a
few pages).  I wouldn't make too big an issue of this.  Just
think that your documentation may grow, or that it may be merged
with other documentation into a larger (real) book.  Then it's
nice to have everything on the right level. :-)

(In the beginning we discussed the book-article issue fairly
extensive, one argument being that much documentation was
(especially then) too small (iirc me being in favour of article).
It's my impression that for some packages this changes quite
drastically, and now I'm sure we're all glad to have the
documentation with the same top level format.  It means we only
have to worry about one style sheet etc., etc.)

(The fact that you cannot have a bibliography in a reference page
bothers me more in all this than the fact that "book" is too
large a unit.)

Cheers,

Frederik