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

[Bob Lockie]

Lauri Watts wrote:

>-----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 :)
>  
>
 ><?xml version="1.0" ?>
 ><!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant 
V1.0//EN" "dtd
 >/kdex.dtd" [
 >  <!ENTITY kappname "&kapp;"><!-- replace kapp here -->

Why is this not kapp instead of kappname in the template since everywere 
else references &kapp?

 >  <!ENTITY package "kde-module"><!-- kdebase, kdeadmin, etc -->
 >  <!ENTITY % addindex "IGNORE">
 > <!ENTITY % English "INCLUDE"><!-- change language only here -->

How does the language thing work since &language is referenced later yet 
"% English" is supposed to be changed?

I am trying to run "checkXML on the original template.docbook" when I 
got that error.
Should the original template.docbook should work as-is when I have 
everything set up right?

-- 
----------------------------------------
Sent from Mozilla and GNU/Linux.
Powered by an AMD processor.