SDB:Selbsthilfe zur Hilfe

Aus openSUSE

Version: 10.3

Inhaltsverzeichnis

1 Anliegen
2 Die Axt im Haus …

Anliegen

ein brauchbares KDE-Hilfezentrum

Ausgangssituation

Unmittelbar nach seinem Erscheinen im Herbst 2007 habe ich auf meinem Rechner openSuSE 10.3 (32 Bit) mit KDE 3.5.7 als Desktop für die Sprache Deutsch installiert. Ich hoffte, dadurch vor allem auch zu einem brauchbaren KDE-Hilfezentrum zu kommen, das ich bei dem nur wenige Monate vorher installierten openSuSE 10.2 vermisst hatte.

Die Installation erfolgte von der Heft-DVD einer bekannten 14tägig erscheinenden Zeitschrift für Computertechnik (die DVD, die einer Zeitschrift für leichtes und bequemes Linux beilag, konnte von meinem Laufwerk nicht immer sicher erkannt werden). Der DVD-Inhalt sollte der originalen Downloadversion von Novell entsprechen.

Steine des Anstoßes

Nach getaner Installationsarbeit die Enttäuschung: das KDE-Hilfezentrum, so wie es in openSuSE integriert ist, ist weitgehend zweckfrei.

Im linken Teil seines Fensters sind in der Baumstruktur der Karteikarte "Inhalt" bei weitem nicht alle Programme auffindbar, obwohl sie installiert sind und ihre Dokumentationen auf der Festplatte existieren.

Eine besondere Kuriosität erfährt man, wenn man in dieser Baumstruktur unter "Anwendungs-Handbücher" und "KDE-Anwendungs-Handbücher" auf "KDE-Hilfezentrum" klickt (vielleicht weil man zu erfahren hofft, wie dem eben genannten Missstand abzuhelfen ist). Im rechten Teil des Fensters erscheint dann nämlich statt einer Dokumentation die Mitteilung Für /susehelpcenter/index.html ist keine Dokumentation verfügbar..

Auf der Karteikarte "Such-Optionen" wird als Bereich, wo nach einem Begriff gesucht werden kann, zunächst nur "Man-Pages" angeboten. Folgt man dem Hinweis, erstmal einen für die Suche nötigen Index zu erstellen, werden nur 'qt3' und (nach einem update im Jan.2008) die Teile der "openSUSE-Dokumentation" zur Indizierung angeboten.

(Bei dieser Gelegenheit: vielleicht sollte man sich mal festlegen, ob es nun richtig "openSuSE" oder "openSUSE" heißen soll.)

Eine Suche in den Programmhandbüchern und in den Info-Seiten scheint also gar nicht möglich zu sein.

Hat man die möglichen Indizes erstellt und sucht in einem dann zugänglichen Bereich nach einem Schlagwort, so erhält man (außer im Bereich Man-Pages) maximal zehn Treffer angezeigt, egal was man in der Karteikarte "Such-Optionen" unter "Max. Treffer:" ausgewählt hat.

Die Hoffnung stirbt zuletzt

In der openSUSE-Dokumentation (Teil IV. Hilfe und Fehlerbehebung, Kapitel 12. Hilfe und Dokumentation, 12.1. Im Lieferumfang enthaltene Hilfe-Ressourcen) ist zu lesen:

"Es gibt mehrere Stellen, an denen Sie Online-Dokumentation finden können, die in Ihrem Produkt inbegriffen ist:
…
Desktop-Hilfezentren
Die Hilfezentren sowohl des KDE-Desktops (KDE-Hilfezentrum) als auch des GNOME-Desktops (Yelp) bieten zentralen Zugriff auf die wichtigsten Dokumentationsressourcen auf Ihrem System in durchsuchbarer Form.
…"

Auch in dem (später dann doch lesbaren) Benutzerhandbuch "Das KHelpCenter" (Kapitel 2. Benutzerhandbuch zum KDE-Hilfe-System) findet man die Aussage:

"Das KDE-Hilfe-System wurde dafür entwickelt, sowohl die allgemeinen Unix-Hilfe-Systeme (man und info) als auch die KDE-Dokumentationen (XML) einfach zugänglich zu machen. …"

Irgendwie, sei es durch Nutzung etwas verborgener Einstellmöglichkeiten oder Behebung eventueller Fehler, sollte es doch möglich sein, ein brauchbares Hilfesystem zu erhalten. Als einer, der sich noch nicht allzu lange mit Linux beschäftigt, fände ich das schon sehr nützlich.

Anscheinend arbeiten mit openSuSE aber hauptsächlich Experten, die keine Hilfen mehr benötigen. Trotz heftigen Googlens habe ich nämlich diesbezüglich kaum Anfragen in Foren gefunden und wenn, blieben sie meist unbeantwortet. Auch andere sachdienliche Hinweise waren höchst selten.

Bleibt also die Wahl, entweder zu resignieren und ohne eine brauchbare Hilfe auszukommen oder selbst Hand anzulegen. Ich habe mich für letzteres entschieden und möchte meine Erkenntnisse im Folgenden darstellen. Möglicherweise kann der eine oder andere damit etwas anfangen. Es wird zwar etwas lang aber es gibt ja auch viel zu tun.

Vielleicht lesen das auch mal einige Experten und äußern sich kritisch dazu. Am liebsten wäre mir allerdings, wenn in näherer Zukunft ein update erscheint, das alles in Ordnung bringt.

Die Axt im Haus …

Um mir das Hilfezentrum gefügig zu machen, muss ich eine ganze Reihe von Dateien ändern und neue Verzeichnisse anlegen. Wie ich das tue und wie es wahrscheinlich am einfachsten nachzuvollziehen ist, will ich hier einmal (statt im Folgenden immer wieder) darstellen. Fortgeschrittene und Experten, die sowieso lieber die Kommandozeile benutzen, mögen mir die Ausführlichkeit verzeihen. Für sie ist die Darstellung auch nicht gedacht, sondern für die, die (wie ich vor einiger Zeit) mit dem Einstieg in Linux Neuland betreten.

Ausgangspunkt ist immer der Konqueror im Systemverwaltungsmodus (,weil die meisten der geplanten Aktionen root-Rechte erfordern). Er wird geöffnet durch Klick auf "Hauptmenüsymbol/Anwendungen/System/Dateiverwaltung/Konqueror(Dateiverwaltungsmodus)" und Eingabe des root-Passwortes.

Um eine Datei /abc/…/def/xyz zu ändern, klickt man sich durch den Pfad, bis man beim Unterverzeichnis def/ angelangt ist. Jetzt sollte man im angezeigten Inhalt die Datei xyz finden. Ein Rechts-Klick auf den Namen oder das Symbol öffnet das Kontextmenü und dort ein Klick auf "Öffnen mit/KWrite" den Texteditor 'KWrite' (der auch gleich die root-Rechte vom Konqueror "erbt"). Wer mit einem anderen Editor lieber arbeitet oder besser umgehen kann, kann natürlich auch den wählen.

Will man in einer der im Folgenden zu ändernden Dateien eine Zeile "auskommentieren", so setzt man an den Zeilenanfang ein Doppelkreuz (#) ein.

Sind die notwendigen Änderungen vollbracht, klickt man auf "Speichern" (das Diskettensymbol in der Werkzeugleiste oder im Menü "Datei/Speichern"). 'KWrite' legt dabei standardmäßig eine Sicherheitskopie des alten Standes (erscheint als xyz~) und die geänderte Datei xyz an.

Nach der ersten Änderung enthält xyz~ den ursprünglichen Stand von xyz, nach jeder weiteren den jeweils vorhergehenden Stand. Will man sichergehen, auch den ursprünglichen Stand zu behalten, sollte man nach der ersten Änderung xyz~ in z.B. xyz.alt umbenennen (Klick im Kontextmenü auf "Umbenennen" und Ergänzung des Dateinamens).

Muss man im Verzeichnis /abc/…/def/ ein neues Unterverzeichnis z.B. namens klm/ erstellen, klickt man sich wieder bis def/ durch, öffnet mit Rechts-Klick auf eine freie Stelle im Inhalt das Kontextmenü und klickt "Neu erstellen/Ordner…" an. Im darauf erscheinenden Dialogfenster wird der Verzeichnisname 'klm' (natürlich ohne die Apostrophe) eingetragen und dann auf "OK" geklickt.

Zu beachten ist, dass immer nur ein Unterverzeichnis nach dem anderen erstellt werden kann. Es ist also nicht möglich, in dem Dialogfenster als Verzeichnisnamen z.B. 'klm/nop' einzutragen, wenn man ein Verzeichnis /abc/…/def/klm/nop/ erzeugen möchte.

Muss man eine Datei oder gleich mehrere von einem in ein anderes Verzeichnis kopieren, selektiert man sie zunächst, d.h. klickt sie bei gedrückter Strg-(Ctrl-)Taste an. Nach Rechts-Klick auf die Selektion klickt man in dem Kontextmenü auf "Kopieren", wechselt dann in das Verzeichnis, wohin die Datei(en) kopiert werden soll(en), und macht einen Rechts-Klick auf eine freie Stelle dort. In dem Kontextmenü wählt man dann "Datei einfügen".

Soll eine Datei oder gleich mehrere ohne inhaltliche Änderungen in einem anderen Verzeichnis auftauchen, genügt es meist, so genannte (dynamische) Links zu setzen. Dazu wechselt man im Konqueror in das Zielverzeichnis (also das, wo die Links hin sollen) und öffnet dann ein zweites Konqueror-Fenster (das muss nicht im Systemverwaltungsmodus sein, Klick auf das Häuschensymbol der Kontrollleiste reicht). Im zweiten Konqueror wechselt man in das Quellverzeichnis, selektiert dort die entsprechenden Dateien, zieht die Selektion (bei gedrückt gehaltener linker Maustaste) in den Inhaltsbereich des ersten Konquerors und lässt sie dort über einer freien Stelle fallen (Maustaste loslassen). In dem darauf erscheinenden popup-Menü klickt man auf "Hiermit verknüpfen" und es erscheinen die Links (zu erkennen an dem kleinen Pfeil links unten am Datei-icon) im neuen Verzeichnis.

An dem popup-Menü erkennt man, dass auf diese Weise auch das Kopieren möglich wäre, würde man "An diese Stelle kopieren" anklicken. Den Punkt "An diese Stelle verschieben" sollte man aber nicht wählen, weil dann die Datei aus dem Quellverzeichnis verschwinden würde. Auf die gleiche Weise lassen sich auch Links zu ganzen Verzeichnissen erstellen.

Grundsteinlegung

Die meisten der zu ändernden Dateien stehen in den Verzeichnissen /opt/kde3/… und /usr/share/….

Nun ist es aber so, dass diese Verzeichnisse der Paketverwaltung gehören und man möglichst die Finger davon lassen sollte, will man möglichen Problemen bei einem Distributions- oder KDE-update von vornherein aus dem Weg gehen. Diese Weisheit habe ich einem Artikel Handgemacht in der Zeitschrift LinuxUser 6/2004 unter der Überschrift Ärger nach der Installation entnommen, wo auch gleich ein Vorschlag für eine "saubere Lösung" mittels Nutzung der Umgebungsvariable KDEDIRS gemacht wird.

Der Inhalt von KDEDIRS wird zwar von den KDE-Programmen, zu denen ja auch KHelpCenter gehört, berücksichtigt, diese Variable ist aber standardmäßig nicht gesetzt. Ich will es auch dabei belassen, denn sie wird, wenn nötig, üblicherweise in der Datei .bashrc im home-Verzeichnis gesetzt, gilt damit also nur für einen Nutzer.

Es gibt nämlich noch eine andere Möglichkeit, den KDE-Programmen mitzuteilen, wo sie ihre Daten finden können, die m.E. auch mehr der Philosophie von openSuSE (und KDE?) entspricht:

In der Konfigurationsdatei /etc/kde3rc, einer einfachen Textdatei, findet sich standardmäßig in der Gruppe [Directories] der Eintrag prefixes=/etc/opt/kde3/. Hier kann man, wie die Pluralform des Schlüssels schon vermuten lässt, auch weitere Verzeichnisse angeben.

Ich habe diesen Eintrag durch Angabe des Verzeichnisses /usr/local/ ergänzt, weil ich dort dann meine geänderten Dateien unterbringen will. Da üblicherweise dort auch die selbst kompilierten Programme landen, hat das außerdem den Vorteil, dass sie, wenn es sich um KDE-Programme handelt, gleich in die richtige KDE-Umgebung eingebunden sind (siehe oben genannten Artikel). Der neue Eintrag lautet also jetzt

prefixes=/etc/opt/kde3/,/usr/local/

Anschließend sollte man gleich unter /usr/local/share/ ein Unterverzeichnis applications/ einrichten. Die Existenz dieses Verzeichnisses veranlasst den Startvorgang von KDE, das Verzeichnis /usr/local/share/ auch in bestimmte Umgebungsvariablen aufzunehmen (siehe /etc/profile.d/xdg-environment.sh).

Danach (und nach einem Neustart) ändert sich zunächst noch gar nichts, aber der Grundstein ist gelegt. Wer etwas mehr über seine Hintergründe erfahren möchte, dem sei die Lektüre des KDE Benutzerhandbuch (das müsste schon im Hilfezentrum unter "Anwendungs-Handbücher/KDE Einführung" erreichbar sein), speziell der Kapitel 25 KDE Interna und 26 KDE Anpassen, Das KDE-Menü empfohlen.

Das also ist des Pudels Kern

Sehr aufschlussreich ist die Datei README.metadata, die dem Quelltextpaket von 'kdebase' beiliegt (auch zu erhalten unter [1]). Ihr kann man entnehmen, dass KHelpCenter so genannte "meta data files" nutzt, die jeweils eine Dokumentation beschreiben. Standardmäßig liegen sie bei openSuSE im Verzeichnis /usr/share/susehelp/meta/. Dort und in weiteren Unterverzeichnissen findet man eine Menge *.desktop-Dateien und in jedem Unterverzeichnis eine Datei .directory. Wir wollen sie im Folgenden einfach auch 'meta-Dateien' nennen.

Beides sind einfache Textdateien, die man sich mit einem Texteditor oder, wenn man mit dem Konqueror als Dateimanager arbeitet, mit dessen (Menüpunkt im Kontextmenü) "Vorschau in Erweiterte Editorkomponente" ansehen kann.

Tut man das auch, erkennt man schnell das Beschreibungsprinzip nach dem Muster "‹Schlüssel›=‹Wert›" (welche Schlüssel es gibt und was sie bedeuten, steht auch in der README.metadata). So hat z.B. die Datei …/Manuals/Productivity/enscript.desktop folgenden Inhalt:

[Desktop Entry]
Name=enscript
Comment=ASCII to PostScript(tm) converter 
Comment[de]=Konverter für ASCII nach PostScript(tm) 
Comment[es]=Conversor ASCII a PostScript(tm) 
Comment[fr]=Convertisseur de fichiers ASCII vers PostScript(tm) 
Comment[hu]=ASCII-ből PostScriot(tm)-be konvertáló program
DocPath=/usr/share/doc/packages/enscript/FAQ.html

Sie gibt unter dem Schlüssel Name einen Titel, unter Comment eine Kurzbeschreibung (sogar in mehreren Sprachen) und unter DocPath den vollständigen Namen der Datei, die die Dokumentation enthält, an.

Öffnet man das KDE-Hilfezentrum und klickt in der Karteikarte "Inhalt" auf "Anwendungs-Handbücher", wird die Baumstruktur erweitert und man findet unter dem Ast "Referenz-Dokumentation" auch den Titel "Enscript". Im rechten Fensterteil wird eine entsprechende Listendarstellung angezeigt, in der sich ebenfalls dieser Titel ergänzt durch die Kurzbeschreibung findet. Lässt man dort den Mauszeiger über dem Titel ruhen, erscheint auch in der Statuszeile am unteren Fensterrand der vollständige Dateiname. (Dass der Titel hier aber groß geschrieben ist, obwohl er in der enscript.desktop-Datei klein geschrieben steht, liegt wahrscheinlich daran, dass kein Schlüssel Name[de] existiert und deshalb eine automatische Übersetzung versucht wird (Stichwort KBabel).)

Die auf der Karteikarte "Inhalt" angezeigte Baumstruktur wird durch die Struktur der Unterverzeichnisse des Verzeichnisses …/meta/ geliefert, deren jedes eine Datei .directory enthält. Diese kann zwar die gleichen Schlüssel-Wert-Zeilen enthalten wie die *.desktop-Dateien, ist aber grob betrachtet hauptsächlich (aber nicht ausschließlich, siehe z.B. DocPath=/….html) dazu da, den "Ästen" in der Baumstruktur eine Bezeichnung und ggf. eine Kurzbeschreibung zu geben (Manuals - Anwendungs-Handbücher, Productivity - Referenz-Dokumentation).

So ich denke, das Prinzip ist klar, weitere Einzelheiten zu gegebener Zeit.

Sag mir, wo die Hilfen sind

Stöbert man in dem …/meta-Verzeichnis, stellt man fest, dass es viele *.desktop-Dateien gibt. deren Namen auch mit Namen von Programmen korrespondieren, die man ganz bestimmt auf seinem Rechner installiert hat, nur sind die entsprechenden Titel nicht im Hilfezentrum zu finden.

Nun, das liegt daran, dass die meisten jeweils unter dem Schlüssel DocPath angegebenen Dateinamen falsch sind. Manchmal erkennt man, wenn im Pfadnamen auch Versionsnummern auftauchen, dass auf einen völlig veralteten Stand Bezug genommen wird. Die benannten Dateien existieren also meist nicht und werden deshalb im Hilfezentrum (sinnvollerweise) nicht aufgelistet.

Die 'meta-Dateien' stammen (vorsichtig gesagt) fast alle aus dem Paket 'susehelp-2007.08.22-14' (alle habe ich nicht überprüft), das also beim Packen schon veraltet war.

Meistens findet man die Dokumentation eines installierten Programms im Verzeichnis /usr/share/doc/packages/‹Programmname›/ als *.html-, *.pdf-, *.ps-, *.xml- oder auch nur als Text-(README-)Datei. Findet man dort nichts passendes, sollte man sich in den man- und/oder info-Seiten umsehen.

Setzt man (probeweise!) den Namen einer existierenden Dokumentation (am besten im html-Format) richtig bei dem Schlüssel DocPath der entsprechenden *.desktop-Datei (Sicherheitskopie anlegen!) ein, so findet man nach Öffnen des Hilfezentrums in der Karteikarte "Inhalt" plötzlich auch den Titel dieses Programms und kann sich seine Dokumentation anzeigen lassen (Danach schnell alles wieder rückgängig machen, wegen des unter Grundsteinlegung gesagten. Hartgesottene Nutzer wollen vielleicht trotzdem mit der Reparatur in diesem Verzeichnis fortfahren.).

Ich habe jedenfalls unter /usr/local/share/ ein Verzeichnis susehelp/meta/ angelegt und zunächst den gesamten Inhalt von /usr/share/susehelp/meta/ dorthin kopiert. Da kann ich nun nach Herzenslust Veränderungen an den Dateien vornehmen (und habe immer noch die Originaldateien).

Damit KHelpCenter auch weiß, dass es nun diese neuen 'meta-Dateien' verwenden soll, muss man die Konfigurationsdatei khelpcenterrc, die sich im Verzeichnis /etc/opt/kde3/share/config/ (vergleiche prefixes=/etc/opt/kde3/… unter Grundsteinlegung) befindet, ändern.

Ich habe das nicht direkt getan, sondern zunächst ein Verzeichnis /usr/local/share/config/ angelegt, dorthin die Datei khelpcenterrc kopiert und in der Kopie folgende Änderung gemacht:

In der Gruppe [General] befindet sich der Eintrag MetaInfoDirs=/usr/share/susehelp/meta. Dieser muss so geändert werden, dass dort steht:

MetaInfoDirs=/usr/local/share/susehelp/meta

KHelpCenter findet beim Start zwar beide rc-Dateien, entscheidet sich aber aufgrund der höheren Priorität des Verzeichnisses /etc/opt/kde3/share/config/ noch für die ursprüngliche. Ich weiß nicht, ob und wenn ja wie man die Priorität beeinflussen kann, deshalb habe ich die ursprüngliche rc-Datei umbenannt (z.B. in khelpcenterrc~ oder khelpcenterrc.alt).

Nun kann man die Auswirkungen seiner Änderungen in den 'meta-Dateien' im danach neu geöffneten Hilfezentrum-Fenster begutachten. Hier einige Besonderheiten bezüglich der möglichen Werte des Schlüssels DocPath:

DocPath=

Ist der Wert leer oder fehlt die Zeile beginnend mit DocPath=, wird im Hilfezentrum dennoch der nach Name= bzw. Name[de]= stehende Titel angezeigt. Klickt man ihn an, so erscheint im rechten Fensterteil in dem Kopfbild dieser Titel und darunter ggf. der hinter Comment= bzw. Comment[de]= angegebene Text und weiter nichts.

DocPath=/….html

Bezeichnet der Wert eine html-Datei, wird beim Anklicken des entsprechenden Titels deren Inhalt direkt im rechten Fensterteil des Hilfezentrums angezeigt.

Wenn man nun heftig am Ändern ist und trägt als DocPath eine existierende html-Datei ein, sollte man gleich, wenn noch nicht vorhanden, folgende Zeilen dazu setzen:

X-DOC-SearchMethod=htdig
X-DOC-DocumentType=text/html

Die erste Zeile schadet nicht, nützt aber auch nichts. Die zweite ist eine Voraussetzung dafür, dass in diesem Dokument auch nach einem Wort gesucht, genauer gesagt, dass dafür ein Index erstellt werden kann. Dazu aber später mehr.

Ich hatte das Paket 'opensuse-manual_de' installiert und habe daher ein Verzeichnis /usr/share/susehelp/meta/opensuse-manual_de/ und durch meine Kopieraktion natürlich auch /usr/local/share/susehelp/meta/opensuse-manual_de/. In Hinblick auf Indizierbarkeit habe in letzterem folgende Änderungen durchgeführt:

In der Datei .directory habe ich die merkwürdige Zeile ; DocPath=; Icon=document2 (sie ist wegen des am Zeilenanfang stehenden Semikolons ";" ein Kommentar und deshalb wirkungslos) ersetzt durch die Zeile

DocPath=/usr/share/doc/manual/opensuse-manual_de/manual/index.html

Das bewirkt, dass im Hilfezentrum durch Klick auf den Titel "openSUSE-Dokumentation (de)" die ganze aus mehreren Teilen bestehende Dokumentation angezeigt wird. Wegen des schon vorhandenen Eintrags X-DOC-DocumentType=text/html ist sie nun auch als Ganzes indizierbar, wovon man sich nach Klick auf die Schaltfläche "Suchindex erstellen…" in der Karteikarte "Such-Optionen" des Hilfezentrums überzeugen kann.

Die einzelnen Teile der Dokumentation sind repräsentiert durch die Unterverzeichnisse book_…/, deren jedes wieder eine Datei .directory enthält. Dort finden sich gültige DocPath-Werte, aber auch die Einträge X-DOC-DocumentType=text/html und X-DOC-SearchMethod=Htdig. D.h. die einzelnen Teile lassen sich im Hilfezentrum gesondert anzeigen aber auch indizieren.

Letzteres ist nach der obigen Änderung aber nicht mehr nötig und außerdem Verschwendung von Plattenspeicher (Indexdateien können recht groß werden). Ich habe deshalb in den .directory-Dateien der Unterverzeichnisse book_…/ jeweils die Einträge X-DOC-DocumentType=text/html und X-DOC-SearchMethod=Htdig auskommentiert.

DocPath=/…[.txt], DocPath=/….ps bzw. DocPath=/….pdf

Bezeichnet der Wert eine Textdatei, eine *.ps-Datei, bzw. eine *.pdf-Datei, so wird beim Anklicken des entsprechenden Titels im Hilfezentrum zusätzlich das zuständige Anzeigeprogramm (standardmäßig KWrite, KGhostView bzw. KPDF) gestartet und der Inhalt dort angezeigt.

DocPath=http://…

Beginnt der Wert mit http://, so wird beim Anklicken des entsprechenden Titels im Hilfezentrum zusätzlich ein (vom Nutzer als Standardbrowser festgelegter) Browser (standardmäßig der 'Konqueror' als Browser) gestartet und der Inhalt dort angezeigt. Das hat durchaus auch für lokale Dateien Bedeutung. Z.B. findet sich in cups.desktop die Angabe DocPath=/usr/share/doc/packages/cups/index.html. Diese Datei existiert zwar, wird aber im Hilfezentrum nur als eine (etwas verstümmelte) "home page" angezeigt, die etliche (angeblich) weiterführende Links enthält. Tatsächlich weisen diese Links hier aber ins Leere. Trägt man stattdessen folgendes ein

DocPath=http://localhost:631/help/

und klickt dann im Hilfezentrum den Titel "CUPS Dokumentation" an, öffnet sich zusätzlich der Browser mit einer ordentlichen Seite, deren Links auch wirklich weiterführen.

DocPath=help:/…

Hat der Wert die Form help:/‹name›/index.html, setzt das, um gültig zu sein, voraus, dass es im Verzeichnis /opt/kde3/ (dem KDE-Installationsverzeichnis) oder /usr/local/ (dank der Erweiterung von prefixes, siehe Grundsteinlegung) ein Unterverzeichnis share/doc/HTML/de/‹name›/ gibt (statt ‹name› kann auch ‹name1›/‹name2› auftreten). Dieses Unterverzeichnis muss eine Dokumentation im docbook-Format enthalten (d.h. dort müssen mindestens die Dateien index.docbook und index.cache.bz2 vorhanden sein). Sind diese Voraussetzungen erfüllt, wird die jeweilige Dokumentation im Hilfezentrum nach Klick auf den Titel im rechten Fensterteil angezeigt.

Nur falls sich jemand wundert, bei DocPath muss es wirklich …/index.html heißen, obwohl in dem Verzeichnis nur eine Datei index.docbook existiert.

Die KDE-Programme sind üblicherweise in diesem Format dokumentiert (in meiner openSuSE-Installation nicht immer richtig, teilweise fehlen Abbildungsdateien und *.docbook-Dateien von Unterabschnitten oder sind falsch benannt).

Manchmal bringen Programme ihre Dokumentationen in Form von *.xml-Dateien mit. Günstigenfalls lassen diese sich in das docbook- oder html-Format überführen (auch dazu später mehr).

DocPath=man:/…

Hat der Wert die Form man:/‹name›, wird die jeweilige man-Seite (vorausgesetzt, sie ist vorhanden) im Hilfezentrum nach Klick auf den Titel im rechten Fensterteil angezeigt. Das kann verwendet werden, wenn es zu einem Programm nur eine man-Dokumentation gibt oder diese am informativsten ist.

Durch die Form man:/, wie in der Datei …/meta/Administration/Linux/Manpages/.directory zu finden, wird eine Auflistung der man-Abschnitte angezeigt.

Diese Datei enthält übrigens auch den Eintrag X-DOC-DocumentType=text/man, d.h. die man-Seiten sind "durchsuchbar".

Durch die Form man:/(x), wobei x=1,2,…,9,n sein soll, wird eine Auflistung der man-Seiten des jeweiligen Abschnitts angezeigt (siehe Dateien …/meta/Administration/Linux/Manpages/manx.desktop).

DocPath=info:/…

Hat der Wert die Form info:/‹name›, wird die jeweilige info-Seite (vorausgesetzt, sie ist vorhanden) im Hilfezentrum nach Klick auf den Titel im rechten Fensterteil angezeigt. Das kann verwendet werden, wenn es zu einem Programm nur eine info-Dokumentation gibt oder diese am informativsten ist.

Durch die Form info:/dir, wie in der Datei …/meta/Administration/Linux/info.desktop zu finden, wird eine Auflistung der info-Seiten nach Hauptthemen geordnet angezeigt.

Der ebenfalls in dieser Datei vorhandene Eintrag X-KDE-KHelpcenter-Special=info veranlasst KHelpCenter, automatisch im Hilfezentrum auf der Karteikarte "Inhalt" unter "Administration/Linux-Dokumentation/Browse info pages" zwei Zweige zu generieren, worunter die info-Seiten einmal nach Kategorien und zum anderen alphabetisch eingeordnet sind (vergleiche auch Keine Regel ohne Ausnahmen).

Ich habe in diese Datei auch noch den Eintrag X-DOC-Identifier=info und X-DOC-DocumentType=text/info eingefügt, letzteren, um dann auch eine Suche in den info-Seiten zu ermöglichen.

DocPath=/…/

Bezeichnet der Wert keine einzelne Datei sondern lediglich ein Verzeichnis (in dem mehrere hilfreiche Dateien enthalten sind), so wird beim Anklicken des entsprechenden Titels im Hilfezentrum zusätzlich der Konqueror (als Dateimanager) gestartet, der dann den Inhalt dieses Verzeichnisses anzeigt.

DocPath=…

Es gibt noch mehr Möglichkeiten, wie der Wert aussehen kann (siehe die oben genannte Datei README.metadata). Auf die kann ich aber hier nicht eingehen, weil ich darüber (noch) nichts weiß.

Keine Regel ohne Ausnahmen

Wer mit den im Hilfezentrum z.B. unter "KDE-Anwendungs-Handbücher" angezeigten Titeln nicht zufrieden ist (sei es, dass sie anders benannt oder mit Kurzbeschreibungen versehen werden sollten), wird feststellen, dass keine entsprechenden *.desktop-Dateien vorhanden sind. Das entsprechende Verzeichnis /…/meta/Manuals/Applications/ ist bis auf die Datei .directory vollständig leer.

Ein Blick in eben diese Datei gibt aber Hinweise darauf, woher trotzdem die Einträge im Hilfezentrum kommen. Dort ist der Eintrag enthalten

X-KDE-KHelpcenter-Special=apps

der bedeutet, dass KHelpCenter andere Mittel als die *.desktop-Dateien nutzt, um Einträge im Hilfezentrum zu generieren (siehe wieder die Datei README.metadata, dort steht jedoch als Schlüsselname nur X-KDE-KHelpcenter). Dem Wert des Schlüssels Comment entnimmt man, dass diese anderen Mittel irgend etwas mit dem "Start-Menü" zu tun haben müssen.

Vergleicht man den Teilbaum im Hilfezentrum auf der Karteikarte "Inhalt" unter "Anwendungs-Handbücher/KDE-Anwendungs-Handbücher" mit den (am besten im 'KDE-Menü-Editor' sichtbaren) Eintragungen im Start-Menü, stellt man weitgehende Übereinstimmungen fest. Tatsächlich benutzt KHelpCenter für den Aufbau des Teilbaums Dateien, die vorrangig für das Startmenü gedacht sind. Das sind erstens *.menus-Dateien, die die Baumstruktur festlegen, und zweitens wieder *.desktop-Dateien, die die einzelnen Programme beschreiben (siehe "KDE Benutzerhandbuch" Kapitel 26 KDE Anpassen, Das KDE-Menü).

In den *.menus-Dateien gäbe es in Hinblick auf das Verhalten des Startmenüs auch einiges richtig zu stellen, aber das ist ein anderes Thema.

Die *.desktop-Dateien stehen in den Verzeichnissen $XDG_DATA_DIRS/applications und sind etwas anders geartet, als die bisher betrachteten 'meta-Dateien'. Aber auch sie enthalten Einträge der Form "‹Schlüssel›=‹Wert›".

XDG_DATA_DIRS ist eine Umgebungsvariable, die (nicht zuletzt durch unsere Ergänzung von prefixes, siehe Grundsteinlegung) folgenden Inhalt haben sollte:

/usr/local/share:/usr/share:/etc/opt/kde3/share:/opt/kde3/share

(nachprüfbar durch das Kommando echo $XDG_DATA_DIRS auf der Kommandozeile).

Mit der Reihenfolge der angegebenen Pfade ist eine Priorität (von hoch nach niedrig) festgelegt, d.h. tauchen im Verzeichnis applications/ in mehreren Pfaden gleichnamige *.desktop-Dateien auf, so "verdeckt" die Datei im höher priorisierten Pfad die im niedriger priorisierten.

Systemweit gültige Änderungen gelingen also am "schonendsten", wenn man die entsprechende *.desktop-Datei in das Verzeichnis /usr/local/share/applications/ (das wir uns ja schon angelegt haben, siehe Grundsteinlegung) kopiert und diese Kopie editiert.

Es gibt allerdings ein noch höher priorisiertes Verzeichnis und das ist standardmäßig $HOME/.local/share/applications. Es ist je nach Nutzer natürlich ein anderes und enthält *.desktop-Dateien, die dadurch entstanden sind, dass er mittels des 'Menü-Editor' Einträge im 'Start-Menü' geändert oder neu hinzugefügt hat. Auch diese Dateien werden ggf. von 'KHelpCenter' berücksichtigt, allerdings nur für den jeweiligen Nutzer. Er kann sie wenn nötig per Hand ändern (es sind dazu keine root-Rechte nötig).

In all diesen *.desktop-Dateien kann auch ein Eintrag mit dem Schlüssel DocPath auftreten. Ist der zugehörige Wert nicht leer (egal ob sinnvoll oder nicht), wird im Hilfezentrum ein entsprechender Titel (gegeben durch den Wert des Schlüssels Name) angezeigt.

Der Wert des Schlüssels Comment bleibt hier jedoch unbeachtet. Auch ein Eintrag der Form X-DOC-DocumentType=… (siehe DocPath=/….html), den man vielleicht hinzufügen möchte, bleibt wirkungslos. Das bedeutet, dass diese Dokumentation nicht unmittelbar durchsucht werden kann. Die meisten der im Start-Menü enthaltenen Programme sind jedoch KDE-Programme, deren Handbücher insgesamt durchsucht werden können (siehe khc_docbookdig.pl).

Leider sind auch die Möglichkeiten, einen Wert für DocPath anzugeben, nicht so vielfältig, wie unter "Das also ist des Pudels Kern" beschrieben (also nichts mit z.B. man:/… oder info:/…):

DocPath=

Ist der Wert leer oder fehlt die Zeile beginnend mit DocPath=, wird im Hilfezentrum auch nichts angezeigt.

DocPath=file:…

Bezeichnet der Wert file://‹vollständiger Dateiname› eine html-Datei, wird beim Anklicken des entsprechenden Titels deren Inhalt direkt im rechten Fensterteil des Hilfezentrums angezeigt. Für andere Dateitypen (Text-, *.ps- bzw. *.pdf-Dateien) öffnen sich zur Anzeige die entsprechenden Anzeigeprogramme (vergleiche entsprechenden Fall bei Sag mir, wo die Hilfen sind).

DocPath=http:…

Dieser Fall wird wie unter [[#DocPath=http://…|DocPath=http://…]] geschildert behandelt.

DocPath=‹sonstige Zeichenkette›

In allen anderen Fällen erfolgt eine Ergänzung zu help:/‹sonstige Zeichenkette› und wird dann, wenn möglich, wie unter DocPath=help:/… geschildert behandelt.

An dieser Stelle verfügen wir nun über Kenntnis und Mittel, die Peinlichkeit der fehlenden Hilfe zum Hilfezentrum (siehe Steine des Anstoßes) aus der (Rechner-)Welt zu schaffen.

Eine passende Datei Help.desktop findet sich im Verzeichnis /opt/kde3/share/applications/kde/ und auch in dem nur bei openSuSE vorhandenen höher priorisierten /etc/opt/kde3/share/applications/kde/. Letztere wird also verwendet, enthält aber für den Schlüssel DocPath den Wert susehelpcenter/index.html. Ein Verzeichnis susehelpcenter/ existiert aber weder unter /opt/kde3/share/doc/HTML/de/, dem Pfad, wo die KDE-Dokumentationen liegen, noch sonst irgendwo.

Ich habe also diese Datei Help.desktop in das (neu angelegte) Verzeichnis /usr/local/share/applications/kde/ kopiert und in der Kopie die Zeile DocPath=susehelpcenter/index.html nach dem Vorbild der anderen Datei Help.desktop geändert zu

DocPath=khelpcenter/index.html

Außerdem habe ich noch die Zeile

StartupNotify=true

hinzugefügt, die (nach einem Neustart) bewirkt, dass nach Start des Hilfezentrums neben dem Mauszeiger ein kleiner Rettungsring erscheint. Dies ist sehr beruhigend, da der Startprozess vergleichsweise etwas länger dauert und sich währenddessen scheinbar gar nichts tut.

Suchet, so werdet ihr finden

Wie schon mehrfach ohne Begründung erwähnt, sind die Einträge X-DOC-DocumentType=… in den 'meta-Dateien' ausschlaggebend für die Möglichkeit, die entsprechenden Dokumentationen durchsuchen zu können. Sieht man alle diese Dateien nochmal durch, findet man folgende Varianten:

X-DOC-DocumentType=text/html
X-DOC-DocumentType=text/docbook
X-DOC-DocumentType=text/man

und

X-DOC-DocumentType=text/info

die ich selbst erfunden habe (siehe DocPath=info:/…). Das ist aber erst die halbe Miete.

Handlungsbedarf

Einer Datei README.searchhandlers (sie liegt dem Quelltextpaket von 'kdebase' bei, auch zu erhalten bei [2]) kann man entnehmen, dass ein Dokument durchsucht werden kann, wenn KHelpCenter einen zu dessen Dokumententyp passenden "Searchhandler" findet.

Die mitgelieferten Searchhandler stehen im Verzeichnis /opt/kde3/share/apps/khelpcenter/searchhandlers/ und heißen htdig.desktop bzw. man.desktop. Ihr Inhalt besteht wieder aus Einträgen der Form "‹Schlüssel›=‹Wert›":

htdig.desktop:

[Desktop Entry]
DocumentTypes=text/html
SearchCommand=khc_htsearch.pl --indexdir=%d --config=%i --words=%w --method=%o --maxnum=%m --lang=%l
IndexCommand=khc_htdig.pl --indexdir=%d --docpath=%p --identifier=%i --lang=%l
X-SuSE-translate=true

man.desktop:

[Desktop Entry]
DocumentTypes=text/man
SearchCommand=khc_mansearch.pl --words=%w --maxcount=%m
X-SuSE-translate=true

Die wesentlichen Schlüssel sind folgende:

DocumentTypes: sein Wert gibt an, für welchen Dokumententyp der Searchhandler zuständig ist (korrespondiert mit dem Wert des Schlüssels X-DOC-DocumentType der entsprechenden 'meta-Dateien').
SearchCommand: hier ist als Wert ein Kommandozeilen-tool angegeben, das die eigentliche Suche leistet. KHelpCenter ruft dieses tool auf, nachdem es die symbolischen Parameter geeignet ersetzt hat.
IndexCommand: falls dieser Schlüssel existiert (das hängt von der bei SearchCommand angegebenen Suchmethode ab), ist hier als Wert ein Kommandozeilen-tool angegeben, das die Indizierung der zu durchsuchenden Dokumente leistet. Ggf. ruft KHelpCenter dieses tool auf, nachdem es die symbolischen Parameter geeignet ersetzt hat.

Wie man sieht, fehlt in man.desktop der Schlüssel IndexCommand. Die Suche in man-Seiten benötigt auch keinen Index. Genau genommen wird auch nicht in den man-Seiten selbst, sondern nur ihren Titeln und Kurzbeschreibungen, die in einer entsprechenden Datenbank stehen, gesucht.

Die Searchhandler stellen also nur eine Schnittstelle dar. Die eigentlichen Such- und Indizierungsprogramme khc_….pl, es sind lesbare Perl-Programme, stehen im Verzeichnis /opt/kde3/bin/ (die gleichen Dateien stehen zwar auch in /usr/bin/, diese werden aber nicht verwendet).

Hat man sie gefunden, kann man feststellen, dass es ja außerdem noch das Programm khc_docbookdig.pl gibt, welches einen Index für alle Dokumentationen im Verzeichnis /opt/kde3/share/doc/HTML/$lang/ (Dokumentationen der KDE-Programme) erstellen kann. Ist erst einmal ein Index erstellt, kann mit khc_htsearch.pl auch nach einem Begriff gesucht werden.

Ich habe also ein Verzeichnis /usr/local/share/apps/khelpcenter/searchhandlers/ erstellt und dort eine Datei namens docbookdig.desktop gespeichert. Dazu habe ich einfach die Datei htdig.desktop dorthin kopiert, die Kopie entsprechend umbenannt und so geändert, dass sie folgenden Inhalt hat:

[Desktop Entry]
DocumentTypes=text/docbook
SearchCommand=khc_htsearch.pl --indexdir=%d --config=%i --words=%w --method=%o --maxnum=%m --lang=%l --docbook
IndexCommand=khc_docbookdig.pl --indexdir=%d --docpath=%p --identifier=%i --lang=%l
X-SuSE-translate=true

Danach wurde tatsächlich im Hilfezentrum "KDE-Anwendungs-Handbücher" zur Indizierung angeboten.

Es gibt auch noch die Möglichkeit, info-Seiten, genauer deren Titel und Kurzbeschreibungen, zu durchsuchen (ähnlich wie die man-Seiten s.o.). Deshalb hier gleich noch ein Searchhandler, der wie eben beschrieben aus man.desktop hervorgeht, info.desktop heißen soll und folgenden Inhalt hat:

[Desktop Entry]
DocumentTypes=text/info
SearchCommand=khc_infosearch.pl --words=%w --maxcount=%m
X-SuSE-translate=true

Dieser bewirkt zunächst noch nichts. Es gibt zwar den Dokumententyp text/info (s.o.) aber noch nicht das Programm khc_infosearch.pl, "das kriege mer später".

Jetzt geht's an's Eingemachte

Letztlich habe ich an allen vier Programmen (khc_htsearch.pl, khc_htdig.pl, khc_docbookdig.pl und khc_mansearch.pl) aus dem Verzeichnis /opt/kde3/bin/ Änderungen vorgenommen und, wie oben schon angedeutet, ein neues (khc_infosearch.pl, dem Programm khc_mansearch.pl aber sehr ähnlich) hinzugefügt.

Immernoch dem Prinzip folgend, die ursprünglichen Dateien weitestgehend unberührt zu lassen, habe ich deshalb das Verzeichnis /usr/local/bin/ eingerichtet. Dorthin habe ich die Datei khc_mansearch.pl kopiert und die Kopie umbenannt in khc_infosearch.pl. Anschließend habe ich dann die vier erstgenannten Dateien khc_….pl ebenfalls in das neue Verzeichnis kopiert.

Danach wurden aber immer noch die "alten" Programme genutzt, offenbar sind die Prioritäten der Pfade wieder etwas anders. Ich wusste mir nicht anders zu helfen, als ihnen die Ausführungsrechte zu entziehen (Auswahl von "Eigenschaften" im Kontextmenü dieser Dateien und im Tab "Berechtigungen" das Kreuzchen bei "Ausführbar" entfernen). Jetzt werden die Programme aus dem neuen Verzeichnis genutzt, die natürlich Ausführungsrechte für alle haben müssen. Damit habe ich die ursprünglichen Dateien nun doch angetastet, aber nur ein bisschen.

Ich will nun meine Änderungen an den Dateien khc_….pl und deren Zweck beschreiben:

khc_mansearch.pl

Die Suche in man-Seiten funktionierte ja von Anfang an und meine Änderung ist auch nur kosmetischer Natur. Im Hilfezentrum werden die Treffer dafür in der Form
‹Titel› ‹Kurzbeschreibung›
angezeigt. Ich wollte aber noch die Abschnittsnummer (weil diese Information mit abfällt) in Klammern vorangestellt sehen, etwa so:
(x) ‹Titel› ‹Kurzbeschreibung›
Dazu dient folgende Programmänderung:

…
  my $count = 0;
  for my $result ( @results ) {
    my ( $page, $section, $description ) = @$result;
    my $url = "man:" . $page;
    print "<li><a href=\"$url\">";
#    print "$page - $description</a></li>\n";
# Um in der Suchergebnisanzeige auch noch die Abschnittsnummer anzuzeigen,
# vorhergehende Zeile gelöscht und folgende Zeile eingefügt:
    print "($section) $page - $description</a></li>\n";
    if ( ++$count == $maxcount ) { last; }
  }
…

khc_infosearch.pl

Die Existenz dieser Programmdatei bewirkt schon, dass im Hilfezentrum auf der Karteikarte "Such-Optionen" die info-Seiten als durchsuchbar angezeigt werden. Da dieses Programm eine Kopie von khc_mansearch.pl ist, werden zunächst wieder nur die man-Seiten durchsucht. Die sehr ähnlich ablaufende Suche in info-Seiten funktioniert aber, wenn hier folgende Änderungen vorgenommen werden:

…
if ( $help ) {
#  print STDERR "Usage: khc_mansearch.pl --maxcount=n --words=<string> " .
# Zur Anpassung des Mitteilungstextes vorige Zeile gelöscht und nachfolgende eingesetzt:
  print STDERR "Usage: khc_infosearch.pl --maxcount=n --words=<string> " .
    "--lang=<languagecode>\n";
  exit 1;
}
…
# Perform search
#if ( !open( MAN, "-|", "apropos", $words ) ) {
#  print "Can't open apropos.\n";
# Zur adäquaten Benennung der Datei und Aufruf des Suchkommandos
# vorige zwei Zeilen gelöscht und nachfolgende zwei eingesetzt:
if ( !open( INFO, "info --apropos $words|" ) ) {
  print "Can't open info.\n";
  exit 1;
}
my @results;
#while( <MAN> ) {
# Weil die Datei jetzt INFO statt MAN heißt,
# vorige Zeile gelöscht und nachfolgende eingesetzt:
while( <INFO> ) {
#  print "RAW:$_";
  chop;
#  /^([^\s]+)\s+\((.*)\)\s+-\s+(.*)$/;
# Zur Extraktion der benötigten Informationen aus dem Ausgabestring
# des Kommandos 'info' vorige Zeile gelöscht und nachfolgende eingesetzt:
  /^"\((.*)\)(.*)"\s+--\s+(.*)$/;
  my $page = $1;
  my $section = $2;
  my $description = $3;

  if ( $page ) { push @results, [ $page, $section, $description ]; }
}
#close MAN;
# Weil die Datei jetzt INFO statt MAN heißt,
# vorige Zeile gelöscht und nachfolgende eingesetzt:
close INFO;
…
  my $count = 0;
  for my $result ( @results ) {
    my ( $page, $section, $description ) = @$result;
#    my $url = "man:" . $page;
# Zwecks Bildung des URL, auf den der Treffer verweisen soll,
# vorige Zeile gelöscht und nachfolgende eingesetzt:
    my $url = "info:" . "\/$page\/$section";
    print "<li><a href=\"$url\">";
#    print "$page - $description</a></li>\n";
# Zwecks Bildung des Textes für die Trefferanzeige
# vorige Zeile gelöscht und nachfolgende eingesetzt:
    print "$page: $section - $description</a></li>\n";
    if ( ++$count == $maxcount ) { last; }
  }
…

khc_htsearch.pl

Dieses Programm leistet die Suche nach bestimmten Begriffen in html- bzw. docbook-Dokumenten, vorausgesetzt, sie wurden indiziert (siehe khc_htdig.pl bzw. khc_docbookdig.pl).

Obwohl es einen Parameter maxnum akzeptiert, der die anzuzeigende Trefferzahl begrenzen soll, wird er jedoch nicht benutzt. Damit bleibt die Auswahl für "Max. Treffer:" auf der Karteikarte "Such-Optionen" des Hilfezentrums wirkungslos und es werden immer nur bis zu 10 Treffer (vergleiche dazu khc_htdig.pl) angezeigt. Folgende (zugegebenermaßen nicht sehr elegante) Änderung an dem Programm soll Abhilfe schaffen:

…
my ($body,$liststart,$ref,$link,$error,$errorOut);
# Zwecks Berücksichtigung einer bestimmten Anzahl von Suchergebnissen
# folgende Zeile eingesetzt:
my $count = 0;
…
#    print "  <li><a href=\"$ref\">$link</a></li>\n";
# Zwecks Berücksichtigung einer bestimmten Anzahl von Suchergebnissen
# vorige Zeile gelöscht und folgende drei Zeilen eingesetzt:
    if ( $count++ < $maxnum ) {
      print "  <li><a href=\"$ref\">$link</a></li>\n";
    }
…

khc_htdig.pl

Dieses Programm erstellt einen Index für ein bestimmtes html-Dokument. Dabei entsteht nicht nur der Index selbst, sondern u.a. auch eine Konfigurationsdatei ‹Name›.conf, die bei einer späteren Suche in diesem Dokument (siehe khc_htsearch.pl) berücksichtigt wird. Unglücklicherweise wird dort auch die maximale Trefferzahl fest durch den Wert 10 vorgegeben.

Um die vom Hilfezentrum angebotenen Möglichkeiten zur Begrenzung der Trefferzahl (Max. Treffer: 5, 10, 25, 50 oder 1000) nutzen zu können (vergleiche dazu khc_htsearch.pl), habe ich durch folgende Änderung dafür gesorgt, dass der Wert 1000 vorgegeben wird (auch nicht sehr elegant):

…
my $locale;
if ( $lang eq "de" ) { $locale = "de_DE"; }
else { $locale = $lang; }

# Im folgenden Teil (Ausgabe in die Datei CONF) die Zeile
#matches_per_page:       10
# durch die Zeile
#matches_per_page:       1000
# ersetzt:
print CONF << "EOT";
# htdig configuration for doc '$identifier'
#
# This file has been automatically created by KHelpcenter

common_dir:		$commondir
locale:                 $locale
database_dir:           $htdigdb
local_urls:		http://localhost=
local_urls_only:	true
limit_urls_to:          http://localhost
ignore_noindex:		true
max_hop_count:		4
robotstxt_name:         kdedig
compression_level:	6
template_map:           Long long $kdeprefix/share/apps/khelpcenter/searchhandlers/htdig/htdig_long.html \\
                        Short short $htdigdata/short.html
search_algorithm:       exact:1 prefix:0.8
maximum_pages:          1
matches_per_page:       1000
database_base:		\${database_dir}/$identifier
start_url:		http://localhost/$docpath
# for pdf-files
max_doc_size:           5000000
external_parsers: application/pdf /usr/share/doc/packages/htdig/contrib/parse_doc.pl      application/postscript /usr/share/doc/packages/htdig/contrib/parse_doc.pl
#external_parsers: text/docbook /build/htdig/parser
EOT
…

khc_docbookdig.pl

Dieses Programm soll einen gemeinsamen Index für alle (im Verzeichnis /opt/kde3/share/doc/HTML/$lang/) vorhandenen KDE-Handbücher erstellen. $lang wird ihm als Parameter übergeben und legt die benutzte Sprache fest (in meinem Fall 'de').

Lässt man probeweise schon einen Index für "KDE-Anwendungs-Handbücher" erstellen, so findet man im dabei erstellten Protokoll (im Dialogfenster "Suchindex erstellen", "Details>>") u.a. eine Menge Eintragungen der Form

‹lfd.Nr›:‹ID›:‹Hop-Nr›:help://‹Name›/index.docbook: host not found

und

Unknown host or unable to contact server: help://‹Name›/index.docbook …

Der Grund für diese Fehlermeldungen ist kurz gesagt der, dass zunächst im "deutschen" Handbuchverzeichnis eine Liste der vorhandenen Handbücher erstellt wird und dann im "englischen" Handbuchverzeichnis anhand dieser Liste die Dokumente indiziert werden.

Nicht alle Handbücher sind auch in beiden Verzeichnisse enthalten und fehlt ein gelistetes Handbuch im "englischen" Verzeichnis, kommt es zur obigen Fehlermeldung.

Existiert ein Handbuch in beiden Sprachen, wird auch ein Index erstellt. Sucht man aber später nach einem deutschen Begriff in einem de facto englischen Dokument, kann man wohl mit der Trefferquote auch nicht ganz zufrieden sein.

Eine eigene Begrenzung der Anzahl der anzuzeigenden Treffer (vergleiche khc_htdig.pl) ist mit diesem Programm auch nicht möglich.

Folgende Änderungen beheben die angegebenen Fehler:

…
my $parserfile = "$tmpdir/docbookparser";
if ( !open( PARSER, ">$parserfile" ) ) {
  print STDERR "Unable to open '$parserfile' for writing.\n";
  exit 1;
}
# Im folgenden Teil (Ausgabe in die Datei PARSER) die Zeile
#	cd $kdeprefix/share/doc/HTML/en/\$orig
# durch die Zeile
#	cd $kdeprefix/share/doc/HTML/$lang/\$orig
# ersetzt:
print PARSER << "EOT";
#! /bin/sh

file=\$1
shift
mime=\$1
shift

if test "\$#" -gt 0; then
  orig=\${1/file:\\//}
  shift
fi

case "\$orig" in
  help:/*)
	orig=\${orig/help:\\//}
	orig=\${orig/\/index.docbook/}
	cd $kdeprefix/share/doc/HTML/$lang/\$orig
	file=index.docbook
	;;
  *)	
	file=\$orig
	cd `dirname \$orig`
	;;
esac

echo "t	apptitle"
$kdeprefix/bin/meinproc --htdig "\$file"
EOT
close PARSER;
chmod 0755, $parserfile;

if ( !open( CONF, ">$conffile" ) ) {
  print STDERR "Unable to open '$conffile' for writing.\n";
  exit 1;
}
# Im folgenden Teil (Ausgabe in die Datei CONF) die Zeile
#local_urls:             help://=$kdeprefix/share/doc/HTML/en/ file://=/
# durch die Zeile
#local_urls:             help://=$kdeprefix/share/doc/HTML/$lang/ file://=/
# und die Zeile
#matches_per_page:       10
# durch die Zeile
#matches_per_page:       1000
# ersetzt:
print CONF << "EOT";
# htdig configuration for doc '$identifier'
#
# This file has been automatically created by KHelpcenter
common_dir:		$commondir
locale:                 $locale
database_dir:           $htdigdb
database_base:		\${database_dir}/$identifier
local_urls:             help://=$kdeprefix/share/doc/HTML/$lang/ file://=/
local_urls_only:        true
limit_urls_to:          file:// help:/
ignore_noindex:         true
max_hop_count:          4
robotstxt_name:         kdedig
compression_level:      6
template_map:           Long long $kdeprefix/share/apps/khelpcenter/searchhandlers/htdig/htdig_long.html
search_algorithm:       exact:1 prefix:0.8
maximum_pages:          1
matches_per_page:       1000
start_url:              file://$tmpdir/index.html
external_parsers:       text/docbook $parserfile
valid_extensions:       .docbook .html
mime_types:             $mimetypefile
EOT
close CONF;
…

Nachdem diese Änderungen vollbracht sind, sieht das Protokoll bei einer erneuten Indexerstellung schon viel freundlicher aus.

Bei mir gab es dann nur noch ein "… host not found", nämlich für den Namen KRegExpEditor. Das liegt aber daran, dass htdig (ein Programm, das aus diesem aufgerufen wird) den Namen erst in Kleinbuchstaben umwandelt und den ursprünglichen Namen später nicht mehr wiederfindet.

Um diesen Fehler zu umgehen, wusste ich nichts besseres, als im Verzeichnis /opt/kde3/share/doc/HTML/de/ einen Link namens kregexpeditor auf das auch hier befindliche Unterverzeichnis KRegExpEditor/ zu setzen.

XML-Dokumentationen

Manchmal bringen Programme ihre Dokumentationen in Form von *.xml-Dateien mit. Auf meinem Rechner ist z.B. das (GNOME-)Programm Dia installiert, dessen Dokumentation im Verzeichnis /usr/share/doc/packages/dia/ zu finden ist. Anhand dessen will ich beispielhaft darstellen, wie ich zu einer docbook-Dokumentation gekommen bin.

Die Datei dia.xml bildet hier sozusagen den "Einstieg" (analog zu index.html für ein mehrteiliges html-Dokument). Diese Datei beginnt (wie bei Betrachtung in einem Texteditor zu sehen ist) mit folgenden Zeilen:

<?xml version="1.0" encoding="iso-8859-1"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "../../dtd/docbookx.dtd"[
…
]>
…

Dies legt die Vermutung nahe, dass das ganze mal eine docbook-Dokumentation werden sollte, zumindest aber "docbook-tags" zur Formatierung verwendet werden.

Wahrscheinlich ist die Dokumentation nicht ganz fertig geworden, denn bei meinem ersten Versuch, sie in das docbook-Format zu übertragen, traten noch einige Fehler auf. Bevor ich zeige, wie diese Übertragung geschieht, will ich erst meine Fehlerbehebungsmaßnahmen beschreiben.

Weil ich nicht die Originaldateien antasten wollte, habe ich zunächst wieder ein Verzeichnis /usr/local/share/doc/HTML/de/dia/ erstellt und die Dateien dia.xml und usage-layers.xml aus ihrem ursprünglichen Verzeichnis dorthin kopiert. An diesen Kopien sollen Änderungen vorgenommen werden. Die übrigen ….xml-Dateien bleiben unverändert, deshalb reicht es, in dem neuen Verzeichnis auf sie und auf das Unterverzeichnis graphics/ jeweils einen Link zu setzen.

In der Datei dia.xml habe ich sicherheitshalber die Zeile <book id="index" lang="pl">  durch die Zeile

<book id="index" lang="de"> <!-- prosz� nie zmienia� identyfikatora -->

ersetzt.

In der Datei usage-layers.xml gibt es eine Textpassage "… the default layer labelled �Background�.", wobei die das Wort Background einschließenden Zeichen unzulässig für docbook-Texte sind. Diese beiden Zeichen habe ich durch doppelte Anführungsstriche (") ersetzt.

Ebenfalls in dieser Datei kommt danach eine Zeile <tt>dia --show-layers=Background,Slide3 --filter=eps-builtin --export=foo.eps foo.dia</tt> vor, die das unbekannte "tt"-tag enthält. Diese Zeile habe ich ersetzt durch


      </para>
      <para>
      <command>dia</command> <option> --show-layers=<replaceable>Background,Slide3</replaceable> --filter=eps-builtin --export=<replaceable>foo.eps foo.dia</replaceable></option>
      </para>
      <para>

Nachdem diese Änderungen vollbracht sind, müsste die Erstellung einer docbook-Dokumentation für 'Dia' möglich sein. Dazu wird die Kommandozeile benötigt, d.h. es muss jetzt ein Terminalfenster geöffnet werden, das letztendlich folgende Ein- und Ausgaben anzeigt:

haberl@vpio:~> su
Passwort:
vpio:/home/haberl # cd /usr/local/share/doc/HTML/de/dia/
vpio:/usr/local/share/doc/HTML/de/dia # meinproc --cache index.cache.bz2 dia.xml
vpio:/usr/local/share/doc/HTML/de/dia # exit
exit
haberl@vpio:~>

Nach Öffnen des Terminalfensters erscheint der Eingabeprompt. Durch Eingabe von su und Passwort (das unsichtbar bleibt) wechselt man in den superuser-Status. Dann stellt man sich durch cd /usr/local/share/doc/HTML/de/dia/ auf das Verzeichnis, wo die zugrunde liegenden XML-Dateien stehen. In diesem Verzeichnis erzeugt das Kommando meinproc --cache index.cache.bz2 dia.xml nach einer kleinen Weile die Datei index.cache.bz2.

Nach Erscheinen des su-Prompt kann man mit exit den superuser-Status wieder verlassen und nach Erscheinen des normalen Prompt mit exit das Terminalfenster schließen.

Da KHelpcenter als "Einstiegsdatei" eine mit dem Namen index.docbook erwartet, habe ich in dem neuen Verzeichnis noch einen Link dieses Namens auf die Datei dia.xml im gleichen Verzeichnis gesetzt.

Nun kann man sich endlich die zuständige 'meta-Datei' suchen, bei mir ist es /usr/local/share/susehelp/meta/Manuals/Productivity/dia.desktop, und dort den richtigen Eintrag für DocPath vornehmen:

DocPath=help:/dia/index.html

Der Erfolg ist, im Hilfezentrum auf der Karteikarte "Inhalt" lässt sich nun der Titel "Dia" finden und es wird, klickt man ihn an, die Dokumentation angezeigt.

Ein Wermutstropfen bleibt aber noch, man kann diese Dokumentation nicht durchsuchen. Dazu müsste ein neuer Wert für den Schlüssel X-DOC-DocumentType vereinbart werden, der Wert text/docbook bewirkt ja, dass nur die KDE-Handbücher im Verzeichnis /opt/kde3/share/doc/HTML/$lang/ bei der Suche berücksichtigt werden (vergleiche Suchet, so werdet ihr finden). Dann müsste ein neuer "Searchhandler" erstellt und ein entsprechendes Indizierungsscript für einzelne docbook-Dokumente geschrieben werden (vergleiche Handlungsbedarf). Sicher aber keine unlösbare Aufgabe.

<keyword>hilfe,susehelpcenter,khelpcenter,hilfezentrum,kde-hilfezentrum</keyword>