[kde-doc-english] [Bug 256418] Docbook entities are probably misused

[Burkhard Lueck]

https://bugs.kde.org/show_bug.cgi?id=256418


Burkhard Lueck <lueck at hube-lueck.de> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|UNCONFIRMED                 |RESOLVED
         Resolution|                            |DOWNSTREAM




--- Comment #5 from Burkhard Lueck <lueck hube-lueck de>  2010-11-09 21:52:36 ---
(In reply to comment #4)
> (In reply to comment #3)
> > > and then use &kate; on the rest of the documents. 
> > 
> > No, that is wrong, we then use &kappname; in the document. 
> > This entitiy &kappname; is expanded in this way:
> > &kappname; -> &kate; -> <application>Kate</application>
> > Where an entity like &kate; is defined in general.entities in kdelibs
> > And &kate; used in the document is expanded via general.entities to
> > <application>Kate</application>
> > 
> > From http://docbook.org/tdg/en/html/ch01.html#s-entities:
> > <!ENTITY ora "O'Reilly &amp; Associates">
> > You see in this example that using an entity ("&amp;") in an entity 
> > definition is valid docbook syntax.
> 
> Thanks for the interest and for the explanation. I didn't know of the existence
> of the general.entities file, but as long as the &kate; entity (in this
> example) is defined somewhere I agree it's fine to expand kappname to another
> entity. I'm not sure if "we then use"  means "we should use" or "in fact, we
> use" 

if "we then use" means *not* "we should use" (reason see the link in my reply
to comment #2), but "in fact, we use". Either direktly as &kappname; in the
docbook text or via the docbook tool chain e.g. in the entity
&help.menu.documentation;. That's now the third or fourth level of entitiy
redirection ;-)

> but taking a look at, e.g., 
> 
> http://websvn.kde.org/trunk/l10n-kde4/ca/docs/kdelibs/sonnet/index.docbook?view=markup
> 
The header of language docbooks is just a copy from the english docbook, so you
have to look into kdelibs/doc/sonnet/index.docbook

> you can easily check &kappname; does not appear in the document (which wouldn't
> really break anything, since the sonnet entity was already declared) but then
> it may all be just a matter of style or convenience and we could close this
> report.
> 
Finaly you got me ;-) Guilty!
With rev 1077440 I updated the sonnet docs and and changed it to an article,
where the entity &kappname; is not used any more. I left the entity in the
header. But defining an entity but not use it does not matter and will never
break docbook xml.

Thanks to Yuri's hint I know now that this is a Gentoo bug:

The entity &kpat; is defined in
http://websvn.kde.org/tags/KDE/4.4.0/kdelibs/kdoctools/customization/obsolete/general.entities?view=log.
This file with the entity was removed before 4.5.0 was released.

Obviously you try to build a language from kde 4.4.5 with kdelibs >= 4.5.0. 
Check if you have a file
$KDEDIR/share/apps/ksgmltools2/customization/obsolete/general.entities, I am
sure you will not find it.

Closing as downstream.

Thanks for the report.

-- 
Configure bugmail: https://bugs.kde.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the assignee for the bug.