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