[kde-doc-english] [Bug 256418] Docbook entities are probably misused
https://bugs.kde.org/show_bug.cgi?id=256418
Burkhard Lueck changed:
What|Removed |Added
Status|UNCONFIRMED |RESOLVED
Resolution||DOWNSTREAM
--- Comment #5 from Burkhard Lueck 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; -> Kate
> > Where an entity like &kate; is defined in general.entities in kdelibs
> > And &kate; used in the document is expanded via general.entities to
> > Kate
> >
> > From http://docbook.org/tdg/en/html/ch01.html#s-entities:
> >
> > You see in this example that using an entity ("&") 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.
[kde-doc-english] [Bug 256418] Docbook entities are probably misused
https://bugs.kde.org/show_bug.cgi?id=256418
--- Comment #4 from David E. Narvaez 2010-11-09
18:57:03 ---
(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; -> Kate
> Where an entity like &kate; is defined in general.entities in kdelibs
> And &kate; used in the document is expanded via general.entities to
> Kate
>
> From http://docbook.org/tdg/en/html/ch01.html#s-entities:
>
> You see in this example that using an entity ("&") 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" but taking a look at, e.g.,
http://websvn.kde.org/trunk/l10n-kde4/ca/docs/kdelibs/sonnet/index.docbook?view=markup
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.
> That is not the reason for Gentoo Bug 343523.
>
> In #343523 I see too different issues:
>
> 1) Entity 'kdf' not defined
> en_GB-4.4.5/docs/kdeutils/kinfocenter/blockdevices/index.docbook -> that is a
> broken language docbook.
>
> 2) Entity 'kpat' not defined
> We had a problem in the kde archiv with man-kpat.6.docbook switching from DTD
> 4.1 to DTD 4.2; the entity &kpat; had to be replaced with &kpatience; to make
> this docbook man page compilable. I have no idea why this was necessary,
> man-kpat.6.docbook is unchanged since < 4.0.
>
> I have no 4.4 kde source environment available any more, so I can't dig into
> that issue further. My guess is that this is a Gentoo issue related to mixing
> DTD 4.1/4.2
I was actually treating both things separately but your insight on the kpat
issue is great and I'll be investigating down that line.
Thanks again.
--
Configure bugmail: https://bugs.kde.org/userprefs.cgi?tab=email
--- You are receiving this mail because: ---
You are the assignee for the bug.
[kde-doc-english] [Bug 256418] Docbook entities are probably misused
https://bugs.kde.org/show_bug.cgi?id=256418 --- Comment #3 from Burkhard Lueck 2010-11-09 18:17:10 --- (In reply to comment #0) > Created an attachment (id=53266) --> (http://bugs.kde.org/attachment.cgi?id=53266) [details] > A list of files in kde-l10n sources declaring entities in a suspicious way > > Version: unspecified (using Devel) > OS:unspecified > > I stumbled upon this analyzing bug reports like > > https://bugs.gentoo.org/show_bug.cgi?id=343523 > > where docbook complains about entities not declared. According to > > http://www.w3schools.com/dtd/dtd_entities.asp > > you declare an entity using syntax like > > > That is an exception, only 7 of 156 entity definitions in docbooks use this form > and then use the entity as &kappname; on the rest of the document. It looks > like a widespread practice on the translation documents of kde-l10n to use a > syntax similar to > > > That is the major use case, 149 of 156 entity definitions in docbooks use this form > 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; -> Kate Where an entity like &kate; is defined in general.entities in kdelibs And &kate; used in the document is expanded via general.entities to Kate
[kde-doc-english] [Bug 256418] Docbook entities are probably misused
https://bugs.kde.org/show_bug.cgi?id=256418 Freek de Kruijf changed: What|Removed |Added CC||f.de.kruijf at gmail.com --- Comment #2 from Freek de Kruijf 2010-11-09 13:53:34 --- In my view this certainly is OK. It simply means that you do can use &kappname; where you want to use the entity for the current application. The advantage is that if the name of the application changes, and this happens, you do not need to change the messages. Like the change we had with ktts to jovie, but there have been more. Another advantage is that a message like "&kappname; handbook", which can be used in all docbooks, only needs to be translated once. However it is not used very often by the document writers. So this not a bug, but a feature and it may need some promotion. -- Configure bugmail: https://bugs.kde.org/userprefs.cgi?tab=email --- You are receiving this mail because: --- You are the assignee for the bug.
[kde-doc-english] [Bug 256418] Docbook entities are probably misused
https://bugs.kde.org/show_bug.cgi?id=256418 Albert Astals Cid changed: What|Removed |Added Component|general |general AssignedTo|tsdgeos at terra.es|kde-doc-english at kde.org Product|i18n|docs Summary|Docbook entities in |Docbook entities are |translations are probably |probably misused |misused | --- Comment #1 from Albert Astals Cid 2010-11-09 09:42:16 --- No idea if that is the correct syntax or not, but that's not a fault of the translation but from the original docbooks so moving to the docs team. -- Configure bugmail: https://bugs.kde.org/userprefs.cgi?tab=email --- You are receiving this mail because: --- You are the assignee for the bug.
