[kde-doc-english] kde-docbook conventions

[Anne-Marie Mahfouf]

On lundi 08 décembre 2008 12:37:28 tic wrote:
> I just started breeding over the kmail handbook and got stuck almost
> immediately when I compared the template docbook with my index.docbook.
>
> 1) The kmail handbook is split into multiple files by chapter at the
> moment. From the comments in the template I gather that the entire
> documentation should be in one single file. I reckon I should merge those
> files together in the end?
you can have several .docbook files for clarity.
In your index.docbook simply add
  <!ENTITY foo SYSTEM "foo.docbook">
in the header
and then 
&foo; into the doc body
where this foo.docbook will be a chapter for ex

When you call &foo; the whole foo.docbook will be included magically by the 
script.

> 2) I got this list of ENTITY declarations which also doesn't seem to be
> encouraged in the policies. What is the suggested method to clean all that
> up?
>
> <-- snip
>
>   <!ENTITY kappname "&kmail;">
>   <!ENTITY package "kdepim">
>   <!ENTITY kmail-intro SYSTEM "intro.docbook">
>   <!ENTITY kmail-getting-started SYSTEM "getting-started.docbook">
>   <!ENTITY kmail-using-kmail SYSTEM "using-kmail.docbook">
>   <!ENTITY kmail-configure SYSTEM "configure.docbook">
>   <!ENTITY kmail-menus SYSTEM "menus.docbook">
>   <!ENTITY kmail-faq SYSTEM "faq.docbook">
>   <!ENTITY kmail-importing SYSTEM "importing.docbook">
>   <!ENTITY kmail-credits-and-licenses SYSTEM
> "credits-and-licenses.docbook"> <!ENTITY % addindex "IGNORE">
>   <!ENTITY % English "INCLUDE" > <!-- change language only here -->
>   <!ENTITY html "<acronym>HTML</acronym>">
>   <!ENTITY gpg "<application>GPG</application>">
>   <!ENTITY gpgsm "<application>GpgSM</application>">
>   <!ENTITY mdn "<acronym>MDN</acronym>">
>   <!ENTITY acl "<acronym>ACL</acronym>">
>   <!ENTITY imap "<acronym>IMAP</acronym>">
>   <!ENTITY nntp "<acronym>NNTP</acronym>">
>   <!ENTITY openpgp "<acronym>OpenPGP</acronym>">
>   <!ENTITY smime "<acronym>S/MIME</acronym>">
>   <!ENTITY kolab "<acronym>Kolab</acronym>">
>
> <-- snap
the first are the .docbook as I tried to explain above, this is encouraged as 
when the doc is big, it adds clarity.
Acronyms are only OK in a doc if they are not translatable.

It's prefered that they are in kdelibs and used globally in all apps. 
> Thanks for the help
> Manfred
Thanks for getting into this!

Anne-Marie
aka annma :)
> --
> tictric at jabber.ccc.de
> _______________________________________________
> kde-doc-english mailing list
> kde-doc-english at kde.org
> https://mail.kde.org/mailman/listinfo/kde-doc-english

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.kde.org/pipermail/kde-doc-english/attachments/20081208/c073e3a5/attachment.htm