Handbücher, Subversion, UDO

Nichts ist so alt wie der Handbuch-Ausdruck von gestern.

Da Handbücher ständig mit der Entwicklung der Programme Schritt halten müssen, empfiehlt es sich, die Handbuch-Daten auf einem gemeinsam nutzbaren Server abzulegen, damit alle Handbuch-Autoren und Übersetzer raschen Zugriff zu den Daten haben. Ideal ist unserer Meinung nach Subversion für diese Arbeit.

Subversion verwaltet Daten für gleichzeitige Bearbeitung

Dank Subversion (nachfolgend kurz SVN genannt) können wir unserer Handbuch-Dateien gleichzeitig allen Übersetzern zur Verfügung stellen und trotzdem gewährleisten, dass niemand die Daten beschädigt, dass mehrere Autoren gleichzeitig an Dateien arbeiten können und dass alle Dateien immer einen eindeutigen Zustand haben.

Dazu muss man als Autor nicht viel von SVN verstehen, nur soviel:

1. Repository
   Die Daten eines Handbuchs auf unserem SVN-Server werden in einem 'Repository' gespeichert. Das Repository stellt immer den für alle Autoren aktuellen Zustand der Daten dar.
2. Checkout
   Wer die Daten vom SVN-Server auf seine Festplatte herunterlädt (Check Out), legt damit auf seiner Festplatte eine 'Working Copy' an, eine Arbeitskopie, mit der er nach Belieben arbeiten kann.
3. Commit
   Erst, wenn er die Änderungen zum SVN-Server zurückschickt (Commit), werden sie dort übernommen und stehen von nun an allen anderen Autoren zur Verfügung.

Geschlossene Gesellschaft!

Zugang zu unserem SVN-Server bekommen nur die Entwickler, Handbuch-Autoren und Übersetzer. Unser SVN-Server verwaltet eine Vielzahl verschiedenster Repositories, doch nicht jeder hat Zugang zu jedem Repository. Wir meinen, zuviel Freiheit kann verwirren. Um also Zugang zu einem bestimmten Repository auf unserem SVN-Server zu bekommen, benötigst Du einen SVN-Account und ein SVN-Passwort, die beide von uns vergeben werden.

Wie komme ich an die Daten?

Mac OS X

Wenn Du mit dem Apple-Entwicklungswerkzeug Xcode arbeitest, brauchst Du keine weiteren Werkzeuge zu installieren, da Xcode SVN automatisch unterstützt. Man muss es nur aktivieren. Wie das geht, steht in der Xcode-Anleitung.

Ansonsten benötigst Du Subversion und eine graphische Oberfläche für SVN, damit Checkout und Commit einfacher gehen als mit der Kommandozeile.

• Subversion
• SVN-GUI: SmartSVN
• alternativ: SVN-GUI: svnX

Windows

Du benötigst Subversion und eine graphische Oberfläche (GUI) für SVN, damit Checkout und Commit einfacher gehen als mit der Kommandozeile. Wir empfehlen als GUI das Tool TortoiseSVN.

• Subversion
• SVN-GUI: TortoiseSVN

Wie sehen die Handbuch-Sourcen aus?

Wir schreiben unsere Handbücher im UDO-Format, einem sehr leicht lernbaren universellen Dokumentformat. Die Repositories sind üblicherweise so organisiert (das folgende Beispiel bezieht sich auf Mac-OS-X-Programme):

/cs.lproj/
/cs.lproj/<Handbuch-Ordnername>/
/da.lproj/
/da.lproj/<Handbuch-Ordnername>/
/de.lproj/
/de.lproj/<Handbuch-Ordnername>/
/en.lproj/
/en.lproj/<Handbuch-Ordnername>/
/fr.lproj/
/fr.lproj/<Handbuch-Ordnername>/
/it.lproj/
/it.lproj/<Handbuch-Ordnername>/
/nl.lproj/
/nl.lproj/<Handbuch-Ordnername>/
/UDoSource/
/UDoSource/_INCLUDE/
/UDoSource/<verschiedene Ordner>
/UDoSource/<Projektname>_main_cs.u
/UDoSource/<Projektname>_main_da.u
/UDoSource/<Projektname>_main_de.u
/UDoSource/<Projektname>_main_en.u
/UDoSource/<Projektname>_main_fr.u
/UDoSource/<Projektname>_main_it.u
/UDoSource/<Projektname>_main_nl.u

Die oben gezeigte *.lproj-Ordner-Struktur spiegelt die sprachenabhängigen Projektordner für das jeweilige Programm. Die Handbuch-Ordner, die dort enthalten sind, können direkt in die Programmsourcen übernommen werden.

Der UDoSource-Ordner enthält alle Dateien, die übersetzt werden müssen. Nach einer von uns festgelegten Nomenklatur verwenden wir folgende Dateiendungen:

• .cs = tschechische Textdateien
• .da = dänische Textdateien
• .de = deutsche Textdateien
• .en = englische Textdateien
• .fr = französische Textdateien
• .it = italienische Textdateien
• .nl = niederländische Textdateien

• .u = UDO-Steuerdateien
• .ui = UDO-Include-Dateien
• .uli = UDO-Library-Include-Dateien

Natürlich muss nicht jedes Repository exakt diese Ordnerstruktur und alle hier aufgeführten Sprachen enthalten.

UDO-Format, was ist das?

UDO benutzt eine sehr einfache Syntax, um Texte zu strukturieren, mit Textattributen zu versehen, Bilder, Links usw. einzubinden. Das geniale an UDO ist, dass die Syntax wirklich sehr leicht zu erlernen ist, obwohl sie sehr mächtig ist. Wir vermeiden in unseren Handbuch-Sourcen 'Featuritis' und verwenden nur wenige UDO-Syntaxelemente. Hier einige Beispiele:

Text-Strukturierung

!begin_node leitet ein neues Kapitel ein.
!end_node beendet ein Kapitel.
# am Zeilenanfang bedeutet, dass UDO diese Zeile ignorieren soll (Kommentarzeile).
!hline stellt eine waagerechte Trennlinie dar.
(!nl) erzwingt einen Zeilenumbruch. (Normalerweise wird erst, wenn zwei Zeilenenden im Quelltext hintereinander folgen, von UDO ein Abschnitt beendet.)

Textauszeichnung

(!B) und (!b) schalten fette Schrift ein/aus.
(!I) und (!i) schalten kursive Schrift ein/aus.
(!U) und (!u) schalten Unterstreichung ein/aus.

(Natürlich gibt es noch viel mehr Attribute; die meisten davon nutzen wir gar nicht.)

Listen

!begin_itemize und !end_itemize umspannen den Bereich einer unsortierten Liste.
!begin_enumerate und !end_enumerate umspannen den Bereich einer nummerierten Liste.
!begin_description und !end_description umspannen den Bereich einer Beschreibungs-Liste.
!item leitet ein Listen-Element ein.

(Natürlich gibt es noch viel mehr Gestaltungsmöglichkeiten; die meisten davon nutzen wir gar nicht.)