[kde-doc-english]docbook.template from CVS

[Lauri Watts]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Friday 10 January 2003 08:50, Bob Lockie wrote:

> # checkXML template.docbook
> template.docbook:47: error: Entity 'kapp' not defined
> <title>The &kapp; Handbook</title>
>
> Any suggestions as to why?

Ok, you're in business :)  Bear with me while I give you a rundown on these 
entities, you really do need to know about them to write KDE style DocBook 
(well, .any DocBook really, they're a very efficient tool to help you write 
faster and more accurately)

&kapp; is an entity.  You're probably familiar with these from HTML, where 
there are things like &nbsp; for a non breaking space.  Basically, you write 
in your source file &kapp; and it's replaced at processing time with some 
other text.

KDE uses entities *extensively*, because they save a lot of typing, and 
because they make it easy to enforce a certain consistency across all the 
documents. If everyone uses the entities, we can be sure that names are spelt 
right, and trademarks are acknowledged.  

You can (and we do) have &kcontrol; in the source, replaced during processing 
with "<application>KDE Control Center</application>".  We even have whole 
sections that are entities, for example, if you put &help.menu.documentation; 
in the appropriate place, the entire marked up listing for the standard KDE 
Help menu is inserted.

Ok, that's the background, and why we use them, you're probably more 
interested in how to fix the problem :)

The template gives you this:
  <!ENTITY kappname "&kapp;"><!-- replace kapp here, do *not* replace 
kappname-->
  <!ENTITY package "kde-module"><!-- kdebase, kdeadmin, etc -->

These are entity definitions: you could now put &package; in the body of your 
document, and it would be replaced with kde-module.  Obviously that would 
make no sense, so replace kde-module with the correct module, if there is 
one, or don't use the &package; entity if there isn't.

Now, we have entities defined for all the KDE applications, so &kapp; here is 
just a placeholder, and would normally be replaced by the entity for the 
app's name like this:

<!ENTITY kappname "&kcontrol;">

But we hit a problem here, of course, because you don't already have an entity 
for your application.  So, we make a new one!

Let's pretend you're writing about an application called KToaster, and 
KToaster is going to be in the kdeutils module.  We'd make the entities look 
like this:

...
<!ENTITY ktoaster "<application>KToaster</application>">
<!ENTITY kappname "&ktoaster;">
<!ENTITY package "kdeutils">
...

Just to be really clear, entities can include other entities, and they can 
include markup, or both, and they can be nested into the point where you can 
no longer keep track of them.  Nesting is useful, that's why we use it this 
way, but don't go overboard :)  

The end result:

In your text, whenever you want to refer to the *name* of the application, you 
would type &ktoaster;.  The other two will take care of themselves, and are 
used for boiler plate text, for example if you want to use the standard 
installation instructions in the appendix.

Three things to note: 
This is very convenient when the author of the application is struck by a 
blast of creativity and renames the application you're writing about to 
"KToasTer" - you only have one place to change it.  When an application is in 
KDE CVS, we have one canonical list of these to change all the names for all 
the documents.  

You can generally assume that any KDE application that's part of the actual 
KDE distribution will have an entity for it's name, so you should use 
&konqueror; etc, to refer to them.

Finally, the one time you don't want to use the entity, is when you need to 
write about executing the actual binary name.  Then it's 
<command>ktoaster</command>. 

And that's probably more than you ever wanted to know about entities, and why 
you have this error :)

Regards,
- -- 
Lauri Watts, in verbose mode
KDE Documentation: http://i18n.kde.org/doc/
KDE on FreeBSD: http://freebsd.kde.org/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.1 (FreeBSD)

iD8DBQE+Hp86/gUyA7PWnacRAtuwAJ9gI5UycQYPnZdzWpkFfUpyPCOhtgCfaGpj
FyeoBDuOUN2ZDm2djJSW8Jc=
=EQ/f
-----END PGP SIGNATURE-----