[kde-doc-english] Changes needed for Re: http://docs.kde.org/development/*/kde-workspace/ broken

[Luigi Toscano]

Luigi Toscano ha scritto:
> On Monday 24 of March 2014 20:16:41 Burkhard Lück wrote:
>> did anyone of you notice that the kde-workspace development documentation on
>> docs.kde.org is broken (apparently entities from kdelibs not found)?
>>
>> Reason could be kdelibsfrom master with kde-workspace master=frameworks +
>> updated dtd 4.5.
>>
>> I expect that to happen for kde-runtime soon as well.
>>
>> What to do for now?
>>
>> Skip kde-workspace?
> 
> Yes, please: it will require some changes to the script (including the 
> availability of meinproc5), and other fixes to kdoctools that I'm 
> investigating. It started from your mention of common/ directory not being 
> installed, and I found that we need to fix some other stuff (for example, the 
> usage of <lang>/docs/common directory in SVN). I will post later some other 
> details.

Few notes (CC kde-doc-english too) about those issues.

Starting point: Burkhard point out that the common/ directory of kdoctools is
not installed, it's needed for shared files of documentations. But then I
realized few problems.

=> problem COMMONNAME: installation of common/ is going to conflict with
kdelibs4 common/ for distributions which do not specify a different prefix,
like Fedora: /usr/share/doc/HTML/<lang>/common (Debian uses:
/usr/share/doc/kde/HTML/<lang>/common/).
Goal COMMONNAME: use a different name for common/ (called <common> below),
like kdoctools5-common/ and reenable the installation of the directory.


=> problem SYMLINKS: symbolic links are created in each documentation
directory to ../common. This has been (forever) broken on Windows
(big old TODO in the handbook-creation macro).
Goal SYMLINKS: remove the symbolic links for each directory.
Steps: ensure that every link like <common>/foo in the final documentation are
properly changed into help:/ links, so that the help kioslave can find them
from the proper directory <lang>/<common> directory. This is already works for
the License Notice in the header of each package. Needs some tuning for the
link to the GPL/FDL license in the "Credits and License" section of
documentation.

It should be quite easy with a custom ulink handler in a custom XSL rule for
kde-chunk.xsl (which already defines a kde.common variable); I have a working
prototype; but there is the problem for the &kicon; entity defined into
<lang>/user.entities (do we need it?)

=> problem COMMONLANG: $HTML_INSTALL_DIR/en/common is handled by kdoctools;
<lang>/common are installed by kde-i18n-<lang>,
but the metapackage is going away (every framework should install its language
files). Also, other language-specific files are already in kdoctools.

Many of the files for each language have an (empty) localized css and the
translated version of the 3 common license. Only few language have a
(unofficial) translated version.

Goals COMMONLANG:
 - install additional <common> from kdoctools, forget about
trunk/l10n-kde4/<lang>/docs/common
 - add a default <license>-translated.html in en/<common> as fallback and
almost-empty "localized" css
 - Let interested translators recreate the translated (unofficial) version of
the license

This is more or less the dump (sorry, maybe not totally clear) of the issues
I'm trying to solve on kdoctools right now.

Ciao
-- 
Luigi