[kde-doc-english] docbook/xsl/xpath problems with glossary in khelpcenter

[Burkhard Lück]

Hi doc people,

I mailed about some problems a week ago in kde-docbook, but forgot to cc this 
list and got no reaction on kde-docbook so far. 
So I'm sending it here as well.

Yuri Chornoivan updated the glossary documentation, proofreading that I 
noticed some problems with the current implementation of the glossary stuff.

1) The Glossary is installed at 
`kde-4config --path html`/share/doc/HTML/en/khelpcenter/glossary with 
index.cache.bz2, index.docbook and kdeprintingglossary.docbook
These docbooks are not intended to be displayed, you see the whole doc only 
changing the encoding via View -> Set Encoding.

2) At runtime a cache file is used, This is generated with "meinproc4 --output 
m_cacheFile --stylesheet khelpcenter/glossary.xslt m_sourceFile". 
The result you find in `kde4-config --path cache`/help/glossary.xml.
To be precise on a system compiled from sources you'll have only an empty files 
in the help folder and no glossary entries in khelpcenter.
Reason for that is on systems compiled from sources m_cacheFile= 
KStandardDirs::locateLocal( "cache", "help/glossary.xml" );,  
"kde4-config --path cache" returns a path with a hidden folder (with a leading 
dot) like /home/kde44/.kde44/cache-hostname/ here.
On systems installed via distribution the cache path is e.g. 
/var/tmp/kdecache-user/ -> no hidden folder in this path.

Executing meinproc4 --output m_cacheFile --stylesheet path/to/glossary.xslt 
m_sourceFile failes silently with this error:
"XPath error : Invalid expression
/home/kde44/.kde44/cache-hostname/
                  ^
runtime error
Evaluating user parameter outputFile failed"

This bugs happens not only with the glossary, but for all cache help files on a 
system compiled from sources.

Where is the bug ? meinproc4? libxml? XPath?

3) If you look at a successfully generated cache file glossary.xml, you see 
that processing with the stylesheet glossary.xslt all docbook markup (links, 
para, listitems etc) is stripped off in the <glossdef></glossdef> block of the 
source index.docbook; and in case of several paras only the first para is in, 
all others are removed.

4) As far as I understand glossary.cpp, at runtime the glossary navigation 
tree is build from this cache file glossary.xml. 
If you click on an item in the navigation tree, the glossary entry to show is 
generated at runtime using an id to get the glossentry text and adding html 
header/footer (with wrong number of args -> reason for bug #182004, a one 
liner will fix it).

This glossary stuff is broken since ages, e.g. the glossary entry i18n has a 
(not working) link since 9 years, this apparently never worked since the 
glossary was introduced in khelpcenter, very strange...

So I see two main problems here:
* empty chache file on system compiled from sources - no glossary 
* glossentries without working links and paras, lists etc are not really 
usefull

Any help to solve these issues is really appreciated.

-- 
Burkhard Lück