Bug 42448

Summary: docbook authors guide template
Product: [Websites] docs.kde.org Reporter: Olaf Zanger <olaf.zanger>
Component: generalAssignee: Documentation Editorial Team <kde-doc-english>
Status: CLOSED FIXED    
Severity: normal    
Priority: NOR    
Version: unspecified   
Target Milestone: ---   
Platform: openSUSE   
OS: Linux   
Latest Commit: Version Fixed In:
Sentry Crash Report:

Description Olaf Zanger 2002-05-10 20:06:15 UTC
(*** This bug was imported into bugs.kde.org ***)

Package:           docs
Version:           KDE 3.0.0 
Severity:          normal
Installed from:    SuSE RPMs
Compiler:          Not Specified
OS:                Linux
OS/Compiler notes: Not Specified

the template.docbook file and the "The KDE DocBook Authors guide" both have wrong entity header content.

wrong:
<!ENTITY kappname "&kapp;">
<!ENTITY kappname "&kapp;" -- this only *seems* redundant -->
...

right:
<!ENTITY kapp "kappname">
<!ENTITY kde "KDE">
...

the "meinproc" script should be mentioned in the  "The KDE DocBook Authors guide". i had to know the irc channel to solve a 3 hour search.

thanks

(Submitted via bugs.kde.org)
Comment 1 Lauri Watts 2002-07-13 15:18:43 UTC
meinproc is mentioned now on the website.

The template is correct and doesn't need any changing.=20
&KDE; is globally defined and should not be defined in any document and t=
he=20
&kappname; entity should include the entity that refers to the real=20
application name: e.g. <!ENTITY kappname "&konqueror;">

--=20
KDE Documentation: http://i18n.kde.org/doc/
KDE on FreeBSD: http://freebsd.kde.org/
Comment 2 Frederik Fouvry 2002-10-11 17:04:00 UTC
Exactly: whereas the double mention of kappname is wrong (only the first
one will be used), the "corrections" are a lot worse:

1. The general entity &kapp; isn't meant to be defined: it should
   be replaced by the name of the documented application.
   (If it were possible to raise an error in this entity, then I
   would do it.)

2. The general entity &kde; is defined already and must not be
   defined in the preamble again (and certainly not in this
   way!).  Funny how many people seem to want to defined an
   entity for KDE, and always in a way that is much more
   cumbersome than what they get out of it.  _We_ on the other
   hand have done it right ... ;-)