Developer FAQ (Previous)
View this page in Last updated: Sun, 20 Jul 2008
English | Dutch | French | German | Japanese | Polish | Spanish | Plain HTML

Dokumentations- und Übersetzungs-FAQ

Ich habe neue Dokumentation für ein Packages ergänzt, aber die neuen Seiten erscheinen nicht im erzeugten Handbuch.

In den meisten Fällen haben Sie vergessen, erneut ./configure aufzurufen. Damit werden die neuen Seiten erkannt und auch eingebunden.

Ein anderer Grund kann sein, dass Sie nicht die erforderlichen Verknüpfungen in der der übergeordneten Seite eingefügt haben. Im Verzeichnis en/package/ befinden sich die XML-Dateien für die einzelnen Kategorien, welche die entsprechenden Verknüpfungen beinhalten. Ergänzen Sie in der entsprechenden Datei die Verknüpfung zu Ihrem neuen Eintrag.

Das gilt gleichfalls, wenn Sie einer Meldung der Art erhalten cannot generate system identifier for general entity "package.networking.net-ldap.search".

Das erzeugte Handbuch wird auf der Konsole ausgegeben, es werden aber keine Dateien erzeugt!

configure hat nicht die erforderlichen Docbook-DSSSL-Stylesheets gefunden. Prüfen Sie ob die Verzeichnisangaben stimmen und ob die Stylesheets auf dem Rechner verfügbar sind.

Gibt es ein Programm für Übersetzer, um die Änderungen an Dateien zu verfolgen?

Wenn Sie an der Übersetzung arbeiten, bedeutet das nicht nur einfach den englischen Text zu übersetzen und das Ergebnis hochzuladen. Ein Großteil der Arbeit besteht vorallem darin, die bereits übersetzten Inhalte auch aktuell zu halten. Um die Änderung an den englischen Originaltexte zu verfolgen, sollten Sie die Dokumentations-Mailingliste von PEAR abonnieren. So erhalten Sie die CVS-Benachrichtigungen, wenn neue Dateien hochgeladen oder geändert wurden. Wenn Sie die Übersetzung nicht regelmäßig pflegen, kann sie schnell nutzlos werden.

Es ist nicht einfach, den Überblick zu behalten, wenn man die Änderungen an Inhalten in einer fremden Sprache verfolgen muss. Deswegen existiert ein entsprechendes System um die Versionsänderungen und Modifikationen anhand von Zeitstempeln in peardoc zu verfolgen.

Die Revisions-Kommentare

Anstatt Informationen zum Übersetzungsstand in einer zentralen Datei zu speichern, enthält jede einzelne Datei einen entsprechenden Eintrag. Dieser Eintrag enthält den Benutzername des Übersetzers, die Revisionsnummer und den Übersetzungsstatus. Betrachten wir dies am Beispiel der Datei bookinfo.xml: 

<!-- EN-Revision: 1.16 Maintainer: jane Status: ready -->

Sie sehen die Revisionsnummer derjenigen englischen Datei, die für die Überstetzung verwendet wurde (EN-Revision: 1.16), und der Name des CVS-Accounts, welcher die (initiale) Übersetzung vorgenommen hat. Die Status-Angabe liefert weitere Informationen, wenn erforderlich, z.B. "partial" für unvollständige Übersetzungen. Die dezentrale Speicherung dieser Daten ist äusserst praktikabel, schließlich existieren mittlerweile mehr 2400 Dateien im englischen Sprachzweig.

Derzeit müssen alle drei Felder (EN-Revisionsnummer, Maintainer, Status) angegeben werden. Die Maintainer-Angabe sollte dem CVS-Benutzernamen entsprechen, kann aber auch ein beliebiger Name sein, dieser darf aber keine Leerzeichen enthalten. Die Statusangabe kann jeden Wert annehmen, aber auch dieser darf kein Leerzeichen enthalten. Achtung: Dieser Kopf-Angabe wird nicht durch das CVS aktuell gehalten! Sie müssen ihn manuell anpassen, wenn Sie Änderungen an einer Datei vornehmen.

So praktikabel dieses System für eine einzelne Datei ist, so schwierig wird es die Übersicht über alle Dateien zu behalten. Wenn Sie eine Liste benötigen, bei welchen Dateien z.B. die Übersetzung veraltet ist, dann rufen Sie im peardoc-Verzeichnis folgendes Kommando auf: 

./scripts/revcheck_pear.php xx > revcheck.html
Das xx steht für den Sprachcode der übersetzten Sprache. Nach dem das Skript durchgelaufen ist, befindet sich die Datei revcheck.html in diesem Verzeichnis. Sie finden Vergleiche der Revisionsnummern und Links zur Anzeige der Diffs für die betreffende Sprache. Sie können beim Skriptaufruf zusätzlich den Maintainer-Namen angeben, dessen Dateien ausschließlich beachtet werden sollen.

Leider können in den Kommentaren keine weiterführenden Informationen untergebracht werden. Deshalb können zusätzliche Angaben in translation.xml untergebracht werden. Diese werden in die erzeugte HTML-Seite eingefügt. Hier am Beispiel für die imaginäre Sprache XX: 

<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE translation SYSTEM "../dtds/translation.dtd">

<translation>

 <intro>
  Dieser Text enthält Informationen für Übersetzer für die Sprache XX,
  u.a. wer die Überstezung leitet und wo Sie weiterführende Informationen
  finden. Dieser Absatz wird am Anfang der erzeugten HTML-Seite
  ausgegeben.
 </intro>

 <translators>
  <person name="Joe Doe"     email="joe@hotmail.com"
   nick="joedoe" cvs="yes" editor="yes"/>
  <person name="Jane Smith"  email="jsmith@yahoo.com"
   nick="jane"   cvs="yes"/>
  <person name="Joe Forever" email="joe@forever.net"
   nick="joefo"  cvs="no"/>
 </translators>

 <work-in-progress>
  <file name="appendices/aliases.xml" person="joedoe"
   type="working"/>
  <file name="functions/dbx.xml"      person="joefo"
   type="working"/>
 </work-in-progress>

</translation>
In der Datei können auch Benutzer angegeben werden, die keinen CVS-Account besitzen. Weiterhin können Sie Dokumente auflisten, welche in Bearbeitung oder bereits fertig gestellt sind. Die enthaltenen Angaben werden verwendet, um die dynamisch erzeugten Tabellen der Übersetzer und Dateien zu bilden. Die Übersetzer werden mit den entsprechenden Dateien verknüpft, und es wird dargestellt, welchen Übersetzungs-Status die Dateien besitzen, für welche ein Übersetzer zuständig ist. Die Zuweisung von bereits übersetzten Dateien ist sinnvoll, wenn ein zeitaufwendiges Update der Übersetzung notwendig ist.

Sie können im <file>-Tag zwei optionale Attribute angeben: date und revision. Die Datums-Angabe kennzeichnet den Beginn der Übersetzung; die Revisions-Angabe enthält das Release der englischen Datei, welche als erste für die Übersetzung verwendet wurde. Für das Format des date-Attributes gibt es keine Vorgabe.

Mit einer weiteren Erweitung des Systems können Sie ehemalige Übersetzer Tribut zollen. Dazu können Sie einen Kommentar in der übersetzten Datei platzieren: 

<!-- CREDITS: joedoe -->
Sie können auch mehrere Namen angeben, getrennt durch Komma. Die Angaben werden in der HTML-Datei mit bei den Übersetzern aufgeführt.

Developer FAQ (Previous)
Download Documentation Last updated: Sun, 20 Jul 2008
Do you think that something on this page is wrong? Please file a bug report or add a note.
User Notes:
There are no user contributed notes for this page.