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

[Bob Lockie]

Bob Lockie wrote:

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


I used a 4.2 based template and it fixed some of my problems.

I still want to know the following and maybe someone can see why I get a 
tag mismatch error ("help" e-mail).

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