1. Viele Fragen, die wichtigsten Antworten

Wie läuft eine Übersetzung ab?

Wenn Sie selber ein Dokument übersetzen möchten, dann sollten Sie eine Nachricht an die gentoo-doc-de@gentoo.org Mailingliste senden und sich vergewissern, dass noch niemand mit der Übersetzung begonnen hat. Wenn Sie das Dokument fertig übersetzt haben, können Sie es entweder an die Liste schicken, oder direkt an Tobias Heinlein. Das Dokument wird dann Korrektur gelesen. Ist dies geschehen, wird das Dokument in das CVS von www.gentoo.org eingebracht. Eventuelle Änderungen und Korrekturen finden sich dort auch wieder.

Ihre Arbeitskopie der englischen Dokumentation können Sie aus dem gentoo.org CVS beziehen. Sie können entweder ViewCVS aufrufen oder sich eine lokale Kopie des CVS wie folgt herunterladen:

$ cvs -d :pserver:anonymous@anoncvs.gentoo.org/var/cvsroot co gentoo/xml

Mit diesem Login werden Sie nicht in der Lage sein ihre Übersetzungen ins CVS selber einzubringen. Dafür erstellen Sie dann einen Bug-Report im Bugzilla unter Doc Translations. Das Feld Summary sollte den Bearbeitern der Bugs auf einen Blick sagen worum es sich handelt.

Summary: [de] New translation, articles/l-awk1.xml (1.2)
Summary: [de] Updated translation for grub-error-guide.xml to 1.12

Mit welchem Editor kann ich die Dokumente bearbeiten?

Im Prinzip reicht ein einfacher Texteditor, der in UTF-8 abgespeicherte Dokumente bearbeiten kann, vollkommen aus. Bluefish bietet ein sehr schönes Syntax-Highlighting an. Aber auch die üblichen Verdächtigen, wie z.B. vim, sollten Sie durchaus in die nähere Auswahl mit einbeziehen.

Wenn Sie vim benutzen haben wir noch ein paar zusätzliche Tipps für Sie, mit denen Sie sich das Editieren der Dokumente etwas vereinfachen können. Zunächst sollten Sie sich das von Lars Weiler an die Erfordernisse des Schreibens von Gentoo Dokumentation angepasste vim xml-Pluginherunterladen und in das ~/.vim/ftplugins Verzeichnis legen. Damit vim dieses Plugin lädt, müssen Sie noch eine Einstellung in der .vimrc erstellen. Bei der Gelegenheit bringen Sie vim auch noch UTF-8 bei und machen aus einem tab zwei Leerzeichen.

Zunächst weisen Sie vim an, Filetype Plugins zu laden:
filetype plugin on
Nun setzen Sie das Encoding auf UTF-8:
set encoding=utf-8
Und nun machen Sie aus einem Tab zwei Leerzeichen, dies ist
für das Editieren von Tabellen gemäß Coding Style sinnvoll.
set expandtab
set tabstop=2
set shiftwidth=2

Was ist dies für eine komische HTML-ähnliche Syntax in den Dokumenten? Gibt es irgendwo eine Liste für die ganzen Optionen?

Klar. Der XML Guide Leitfaden gibt eine sehr schöne Einführung in das von uns benutzte GuideXML. Wenn Sie Dokumentation übersetzen wollen, müssen Sie nicht unbedingt sofort den Sinn eines jeden Tag verstehen, ich vermute aber mal dass Sie es trotzden wissen wollen ;)

Gibt es eine Richtlinie wie die Dokumente aussehen müssen?

Ja. Sowohl an der englischen Dokumentation, als auch an den deutschen Übersetzungen arbeitet eine Vielzahl von Leuten mit. Damit sich alle innerhalb möglichst kurzer Zeit in einem Dokument zurecht finden können, ist ein "Coding Style" festgelegt worden. Im "Coding Style" wird festgelegt, wie die xml-Tags im Dokument zu platzieren sind, ausserdem gibt es einige Regeln, die dazu dienen, die Dokumentation so lesbar wie möglich zu halten. Um einen Eindruck zu erhalten, wie ein Dokument mit angewandtem Coding Style aussieht, schauen Sie sich zum Beispiel kernel-upgrade.xml in Ihrer lokalen Kopie des CVS Tree an.

Solange diese übereinstimmen lässt sich einfach erschließen auf welche Version des Originals sich die Übersetzung bezieht. Weiterhin sollte beim Bug-Report des Dokuments auch immer die CVS-Revisionsnummer des Originaldokuments angegeben werden damit es passend in der Trads-Übersicht eingetragen werden kann.

Wie erhalte ich die GuideXML DTD (Document Type Definition) Datei?

Sie müssen keine zusätzlichen Pakete installieren. Alle DTD-Dateien (einschließlich der für GuideXML) befinden sich unter /usr/portage/metadata/dtd/. Die Dokumentationsentwicklungs-Tips & Tricks gehen weiter auf deren Benutzung ein.

Fertigstellen der Übersetzung

Bevor Sie Dokumentation zur Korrektur an die Liste schicken, sollten Sie noch kurz prüfen, ob das Dokument syntaktisch korrekt ist.

# xmllint dokumentation.xml

Optional können Sie sich die übersetzte Dokumentation auch anschauen. Dazu benötigen Sie die guide.xsl, main.css sowie optional einige Grafiken. Links zu diesen Dateien finden Sie im Docs-Team Tips&Tricks Guide unter Testing GuideXML. Mit diesen Dateien sind Sie in der Lage lokal eine HTML-Version Ihres Dokuments zu erstellen.

# xsltproc --novalid guide.xsl doku.xml > test.html

Da wir zwar nicht faul aber durchaus etwas bequem sind, erstellen wir uns ein kleines Makefile; ein make dokument geht nunmal schneller.

dokument:
  xsltproc --novalid guide.xsl dokument.xml > test.html

2. Ressourcen

Mailinglisten: Sie sollten sich zumindest auf der gentoo-doc-de@gentoo.org Liste anmelden, da hierüber - neben IRC - ein Großteil der Kommunikation unter den Übersetzern abläuft. Zum Anmelden senden Sie eine Nachricht an gentoo-doc-de-subscribe@gentoo.org

Statusupdates: Es existiert eine Übersicht über den aktuellen Status der Übersetzungen. Diese Auflistung wird mehrfach wöchentlich neu generiert.

Englische Dokumente: Hier finden Sie eine Übersicht der bisher auf Englisch verfügbaren Gentoo Dokumentation. Einen ständig aktuellen Schnappschuss der englischen Dokumentation können Sie auch als Tarball herunterladen. Dies wird auch für die deutsche Dokumentation angeboten. Zusätzlich bietet Ihnen das viewcvs auf gentoo.org die Möglichkeit in verschiedenen Ansichtsmodi zwischen den englischen Versionen zu diffen, ein interessantes Feature, wenn Sie bereits übersetzte Dokumentationen aktualisieren möchten.

Weiterführende Dokumentation: Sie sollten je nach Vorkenntnissen einen Blick in das GuideXML Howto werfen.

Übersetzungshilfen: Wir arbeiten außerdem am Aufbau einer Übersicht über die stilistischen Konventionen für die deutsche Gentoo Dokumentation. Sie finden diese hier.