[kde-doc-english] docs.kde.org issues

[T.C. Hollingsworth]

Hi!

On Sat, Jan 14, 2012 at 3:53 AM, Burkhard Lück <lueck at hube-lueck.de> wrote:
> Am Samstag, 14. Januar 2012, 09:26:14 schrieb T.C. Hollingsworth:
>> Hi Burkhard!
>>
>> On Tue, Jan 10, 2012 at 3:21 AM, Burkhard Lück <lueck at hube-lueck.de> wrote:
>> > Hi,
>> >
>> > some issues with docs.kde.org:
>> >
>> > 1) Broken links to common folder with e.g. number png's
>> > Local Installation
>> > en/common with untranslated license html files, css + png files etc
>> > en/app/common symlink to en/common
>> > lang/common -> with translated license html files
>> > lang/app/common -> symlink to lang/common
>> > d.k.o has an additional module folder
>> > module/en/common (content like local installation)
>> > module/en/app -> no common subdir
>> > module/lang/common dir with translated license html files
>> > module/lang/app/ -> no common subdir
>> > Possible solution:
>> > add common folder (symlink to en/common) to each lang/module/app folder
>> > www/areas/docs/generator creates already symlinks to en screenshots for
>> > lang folders without localized screenshots.
>> >
>> > 2) dead license links (https://bugs.kde.org/show_bug.cgi?id=109143)
>> > Solution of issue 1) would solve that, you get the english licenses, but
>> > not the translated
>> >
> What about this issue?

Sounds good to me.  I can look at coming up with a patch for this too
if you'd like.

>> > 2) In KHelpcenter the english documentation will be displayed in case
>> > there is no translated documentation
>> > To get the same behaviour we need to add a symlink (to en/app) to each
>> > empty lang/app folder
>> >
> And about this issue?

If there is no translated documentation for say Kate in Spanish on the
stable branch, then the "stable/es/kde-baseapps/kate" directory
wouldn't exist, correct?  Or would it just be empty?

Assuming either of these, it shouldn't be too difficult to walk the
directory structure and create symlinks for stuff that exists in en
but not in the individual languages.

>> > 3) Links to other docbooks launch Konqueror with lokal Dokumentation
>> > Html files have e.g. href="help:appname"
>> > Possible solution:
>> > replace 'href="help:appname"' via sed with proposal from
>> > https://bugs.kde.org/show_bug.cgi?id=279900:
>> > 'href="http://docs.kde.org/?language=<language>&application=<appname>"
>>
>> I have attached a patch to trunk/www/areas/docs that does this, with
>> two additions.  The first is adding the branch parameter (which
>> already exists in the PHP code), so links go to the same branch that
>> the doc being viewed is on.
>>
>> The second, more major addition, adds a "path=" paramater to the PHP
>> code so e.g. help:/kate/part.html goes to
>> d.k.o/?language=en&branch=stable&application=kate&path=part.html goes
>> to d.k.o/stable/kde-baseapps/kate/part.html.  Otherwise visitors would
>> always be dropped on the table of contents.
>>
>> The sed expression has been extensively tested, but I can't really
>> test the rest.
>>
> Thanks a lot for the patch.
>
> I have a setup on my computer like on d.k.o for doc generation, which I used
> to fix the generator script.
> I just try to setup a webserver on my machine (see
> http://community.kde.org/KDE.org/Staging_Setup).
> That allows me to test your patch (and fixes for the other topics) locally on a
> staging host.

Thanks for the pointer to that, I'll definitely get a test setup going.

> But that will have to wait a few days, I am still busy to get calligra docs
> ready for 2.4.0.
>
>> > 4) Use app names + kcm names like in systemsettings, not installation/git
>> > dir names
>> > (https://bugs.kde.org/show_bug.cgi?id=227923 about using "kcontrol" on
>> > d.k.o) While this is for apps like Kate or the module names in the
>> > navigation panel only a minor issue, it is important for the
>> > kcontrol/systemsettings modules. For historical reasons some of these
>> > kcm docs have realy crazy names, which makes it nearly impossible for
>> > Joe User to find what he is looking for. E. g. kwintabbox -> "Task
>> > Switcher" or kcmsmserver-> "Session Management"  or kded->"Service
>> > Manager". I'd like to display the names you see in Systemsettings here.
>> > Afaik this should be doable via an php array?
>>
>> IMHO it would also be nice if we could rearrange the navigation to be
>> more like the categories in the K menu.  "Joe User" probably doesn't
>> know whether their favorite app is in extragear or not.
>>
> That is a great idea and makes really sense.
>
>> So the array would look like:
>> $apps = array(
>>     "Multimedia" => array(
>>         "Dragon Player" => "kdemultimedia/dragonplayer",
>>         "K3B" => "extragear-multimedia/k3b",
>>         "System Settings" => array(
>>             "CDDB Retrieval" => "kdemultimedia/kcontrol/cddbretrieval"
>>         )
>>         "KIOSlaves" => array(
>>             "Audio CD" => "kdemultimedia/kioslave/audiocd"
>>     )
>> )
>>
>> I'd be happy to come up with a patch for either this, or just the
>> names if that's too much, if interested.
>>
> I am definitely interested, but using names seems to be much simpler?
> If so I'd prefer to fixed the issues raised in this thread first and use a name
> array.

I was mainly worried about duplication of effort between the name
array and the full navigation tree array.  If that's not a problem we
can definitely do the names first.

> Rearranging the navigation would be the next step then. And a really big
> improvement for our users.
>
> My php skills are really limited, so one question for the ignore_array in
> index.php:
> ignore_array has entries like kdepim/kioslave, but these are nevertheless
> visible on d.k.o.
>
> This code snippet from index.php should exclude them, but apparently does not
> work for entries like "kdepim/kioslave" as I expect it:
>
>        /* Ignore the oddities defined above */
>                foreach ( $ignore_array as $ignore_string ) {
>                        $test_string = $selected_package . "/" . $application;
>                        if ( $test_string == $ignore_string ) {
>                                $breaktest = true;
>                                break;
>                        } else {
>                                $breaktest = false;
>                        }
>                }
>
> Any ideas to fix that?

I can't see anything wrong with that just looking at it.  (IMHO it
should have $breaktest = false; before the foreach loop instead of
setting it on every iteration of the loop, but that's a stylistic
matter; it should work regardless.)

I'll look at this when I have a test instance set up and can debug it properly.

-T.C.