[kde-doc-english] kioslave documentation

[Burkhard Lück]

Am Donnerstag 02 Oktober 2008 21:25:22 schrieb 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?

ping?

-- 
Burkhard Lück