[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-i18n-doc
Subject:    kioslave documentation
From:       Burkhard =?iso-8859-1?q?L=FCck?= <lueck () hube-lueck ! de>
Date:       2008-09-09 15:53:09
Message-ID: 200809091753.11099.lueck () hube-lueck ! de
[Download RAW message or body]

Hi,

we have some very old (2004/2005) bugs for the documentation of ioslaves:
 
The display and links in kcmshell ioslaveinfo are broken in kde3:
https://bugs.kde.org/show_bug.cgi?id=78597

This was fixed in in kde4 by terniesen with commit Revision 798315 with this 
comment in the code:
/**
* Big Hack to only select content of the help documentation
* The HTML content is cut by recognizing header and footer
*/

By changes in the html style or docbooks this could easily and unnoticeable be 
broken again.

The audiocd ioslave documention is not installed in kde4 (not properly in 
kde3):
https://bugs.kde.org/show_bug.cgi?id=106066

The reason:

A static documentation in kdebase/runtime/doc/kioslave with ioslave 
documentations not only from kdebase, but also from other kdemodules 
(kdenetwork: lan, rlan; kdepim:imap, imaps, news; kdegraphics: mrml etc).
All documentions are in one big bz2 compressed html file (index.cache.bz2).

The disadvantages (besides the 2 bugs):
It is not possible to add docs here at runtime (like audiocd from 
kdemultimedia or 3rd party ioslaves) or by installing an additional ioslave.

The documentation for some ioslaves is in kdebase, but the code is in an other 
kdemodule.

The Solution?:

1. change the ioslave documention like the kcontrol and kinfocenter docs, 
install each doc in a separate subdir in /share/doc/HTML/en/kioslave/

2. changes in kdebase/apps/kinfocenter/ioslave/kcmioslaveinfo.cpp (this is 
used when you start "kcmshell4 ioslaveinfo ": 
remove the Big Hack selectHelpBody, just put the doctext (html) into the 
widget.
change #139 help:/kioslave/%1.html -> help:/kioslave/%1/index.html?
This should work like in khelpcenter, read the index.cache.bz2 (the bzip2 
compressed html source) and display it.
The disadvantage of removing the "Big Hack" (cut off header + footer) is, that 
we need a bigger window to display the content. The advantage is, that no 
changes in the html style nor the docbooks breaks this again.

3. all ioslave docs have to be moved and renamed to 
kdemodul/doc/kioslave/nameofkioslave/index.docbook.

4. adjust all DocPath entries in name_of_ioslave.protocol

5. add a check for kioslave in the doc path in autogen.sh and adjust the 
installation dir (add_subdir='SUBDIR kioslave/$subdir';). Then all translated 
ioslave docs are installed in a separate subdir 
in /share/doc/HTML/[lang]/kioslave/.

6. move and rename the translations.

I could do no 1, 3, 4 and 5, need to bother our friendly coordinator with no 
6, but I can't do no 2, the changes in kcmioslaveinfo.cpp.

Comments? Objections?
Anyone willing to help with no 2?

Of course this has to be discussed with the modul coordinators and/or on 
k-c-d? before changing this in the repository, but first I want to change 
this locally and check, if it works as intended.

-- 
Burkhard Lück

[prev in list] [next in list] [prev in thread] [next in thread]