[kde-doc-english] kioslave documentation

[Burkhard Lück]

Am Dienstag 09 September 2008 17:53:09 schrieb Burkhard Lück:
> 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.

I am working on this task and noticed, that there are some kioslave docs like 
http/https, pop3/pop3s, imap/imaps, webdav/webdavs with the only diff in 
content "encrypted via ssl"; or like bzip/bzp2, which are identical 
except "2".

What's the reason for that?

Any objections to join the docs for these pairs of ioslaves?

-- 
Burkhard Lück