[kde-doc-english] kioslave documentation
Burkhard Lück
lueck at hube-lueck.de
Tue Sep 9 17:53:09 CEST 2008
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
More information about the kde-doc-english
mailing list