Das Tutorial
Redaktionssysteme - modular und offen
beginnt in wenigen Minuten
Herzlich willkommen zum Tutorial
Redaktionssysteme - modular und offen
Ferdinand Soethe
mail@soethe.net
Ferdinand Soethe
Einleitung
Situationsanalyse
Forrest Installation
Erste Schritte mit Forrest
Arbeitsumgebung erweitern
Arbeitsabläufe
Medien im System
Customizing
SSP nutzen
Teamwork
Standardformate
Tools
Mehrsprachigkeit
Rufus Redakteur eröffnet sein neues Redaktionsbüro und braucht schnell eine brauchbare Single-Source-Publishing-Lösung.
In Vorgesprächen mit Kollegen (und seiner Bank) hat er folgende Rahmenbedingungen identifiziert.
Nach gründlicher Recherche wählt Rufus Apache Forrest als erstes Werkzeug für seinen Einstieg in SSP.
Wichtige Aspekte seiner Entscheidung waren
Zur Vorbereitung nutzt Rufus die vielen Informationsangebote zu Forrest. Er
Kurzum, er macht sich vor seinem ersten Auftrag anhand einer Testinstallation mit der Funktionsweise und den Grenzen des Systems vertraut.
Gut vorbereitet ,akquiriert Rufus seinen ersten Auftrag, die Dokumentation eines kleinen Softwareprojekts.
Auf den guten Rat erfahrener Kollegen hin
Seinen neuen "Arbeitsrechner" installiert er bewußt von Grund auf neu.
Als Grundlage braucht und installiert er also
Rufus entscheidet sich dafür, zunächst die aktuelle Version 0.8 von Forrest für sein Projekt zu benutzen und lädt die Windows-Version auf seinen Rechner herunter.
Dann installiert er Forrest im Verzeichnis C:\Programme.
Die Installation von Forrest ist ziemlich einfach und unter http://forrest.apache.org/docs_0_80/your-project.html#installing ausführlich dokumentiert:
Forrest organisiert jedes Projekt in einem beliebigen Verzeichnis irgendwo auf einer Festplatte. Rufus legt das neues Verzeichnis handbuch für sein Projekt auf dem Desktop an und initialisiert von der Befehlszeile aus das neue Projekt.
Für die weitere Arbeit startet Rufus Forrest im dynamischen Modus, so dass er die ersten Ergebnisse seiner Arbeit sofort überprüfen kann.
Im dynamischen Modus (forrest run) läuft Forrest als Webserver (Application-Server) auf dem eigenen PC.
Wie einen Webserver sprechen wir ihn mit unserem Browser und einem bestimmten URL an ...
http://localhost:8888/
... und bekommen als Antwort eine dynamisch, d.h. in diesem Moment generierte Seite, unseres Projekts.
Zur Bearbeitung seiner Forrest-Projekte wählt Rufus mit JEdit einen kostenlosen OpenSource-Editor mit Unterstützung für verschiedene Programmiersprachen aus.
Den kann er später dann problemlos durch einen professionellen XML-Editor ersetzen, wenn er aus der Praxis weiss worauf es ihm ankommt.
Aus vielen Gesprächen weiss Rufus, wie wichtig die Versionierung von Projekten in der Praxis ist. Er will sein Projekt daher gleich unter Versionskontrolle stellen.
Aufgrund seiner überragenden Leistungsmerkmale wählt er ein Subversion-basiertes System (http://subversion.tigris.org/) aus.
Als Windows-Anwender ist der komfortable Subversion-Client Tortoise (http://tortoisesvn.tigris.org/) die erste Wahl.
Tortoise allein genügt für den Anfang völlig.
Zur Versionierung von Projekten müssen diese zunächst in einer Urfassung in ein Repository eingestellt werden.
Dabei ist es sinnvoll, je Projekt ein eigenes Repository (Verzeichnis mit speziellen Strukturen) anzulegen und diese gemeinsam unter einem Repository-Hauptverzeichnis zu speichern.
Darin ein neues Verzeichnis handbuch_repos anlegen
Im Repository-Verzeichnis muss nun eine Datenbank-Struktur eingerichtet werden
Tortoise erledigt diese Schritte besonders einfach und komfortabel:
Darin Rechtsklick, TortoiseSVN-Create repository here auswählen.
Im Verzeichnis erscheint die Grundstruktur des neuen Verzeichnisses.
Für die Erstbefüllung des Repositories verwenden wir die Ausgangsdaten des Forrest-Projekts.
Da Änderungen in diesem Verzeichnis für uns unwichtig sind, lassen wir das build-Verzeichnis künftig ignorieren.
Auf der ersten Seite seines Projekts beschreibt Rufus kurz den Sinn und Zweck dieses Handbuchs. Dazu braucht er lediglich den Inhalt der bereits eingestellten Startseite (index.xml) zu verändern.
Im dynamischen Modus genügt ein Aktualisieren der Seite im Browser, um die Änderungen zu sehen:
Die Änderung macht Tortoise im Explorer sofort sichtbar.
Um genau zu wissen, was geändert wurde, läßt Rufus sich mit Rechtklick auf die Datei Tortoise SVN-Diff die Veränderungen an der Datei aufzeigen:
Mit dem Rechtklick SVN Commit werden die Änderungen an das Repository übergeben (eingecheckt). Das kann eine Datei oder ein ganzes Projekt sein.
Vor dem Commit zeigt Tortoise noch mal eine Liste aller Änderungen und erwartet die Eingabe einer Beschreibung der Änderung
Als nächstes will Rufus die beschriebene Software kurz vorstellen. Um schnell neue Seiten anlegen zu können, speichert er die Index-Seite als Vorlage ohne Inhalte in vorlage.xml ab.
Da Forrest Dateien nicht automatisch ins Projekt einbindet, kann er beliebig viele frei benannte Vorlagen direkt im Projekt ablegen, ohne dass diese sichtbar werden.
Beim Versuch die Änderung einzuchecken wird eine Besonderheit deutlich:
Neue Seiten werden von Forrest erst berücksichtigt, wenn innerhalb des Projektes auf sie verwiesen wird.
Sinnvoll ist es für neue Seiten einen Eintrag im Navigator anzulegen, der ihre Position im Website wie auch in der PDF-Datei festlegt.
Jede Seite braucht ein Element site.xml, dass ihm einen Platz im Navigator/PDF zuweist.
Durch Anpassung der Label in site.xml wird der Navigator nun projektspezifisch eingedeutscht.
Im Browser wird auch diese Anpassung sofort sichtbar:
Auf einer zweiten Seite will Rufus nun das Programm vorstellen. Er legt sie als Kopie der Vorlage im xdocs-Verzeichnis an und fügt mit jEdit den Text ein.
Dann fügt er im Navigator einen Verweis auf die neue Seite ein:
Oft müssen in einem Projekt verschiedene Dateien geändert werden um ein gesetztes Ziel zu erreichen.
Durch gemeinsames Einchecken trägt man dieser Tatsache Rechnung:
Subversion bearbeitet den Vorgang auch transaktionsorientiert:
Klare Transaktionsorientierung macht auch die Subverion Protokolle leichter verständlich
Von Hause aus unterstützt Forrest auch Vektorgrafiken im SVG-Standard. Rufus nutzt dies von Anfang an um viele Skalierungs und Auflösungsprobleme zu vermeiden.
<img src="/images/apache-forrest-original.png" alt="Forrest Logo"/>
Für die bevorstehende Veröffentlichung einer ersten Version muss Rufus das Handbuch nun präsentationsfein machen.
Er nutzt dazu die Anpassungsmöglichkeiten in skinconfig.xml.
In skinconfig.xml kann er auch die Einblendung von Subnavigation bei nur einem Unterkapitel unterdrücken
Natürlich soll das Handbuch zu OneSourceDocs auch in einer Print-Version veröffentlicht werden.
Dank gründlicher Recherche kennt Rufus das Zauberwort, mit dem sich auf Knopfdruck ein konsolidiertes PDF aus Forrest erzeugen läßt.
Mittlerweile sind die Handbücher von Rufus so erfolgreich, dass er einen Mitarbeiter einstellt. Das wirft gleich mehrere Fragen bei der Zusammenarbeit bei Projekten auf:
Wie verhindern die Beiden Probleme durch gleichzeitiges bearbeiten von Dokumenten?
Rufus wählt den dritten Weg weil er entscheidend besser skaliert.
Bisher hatte Rufus sein Subversion lokal gehostet.
Zur größeren Flexibiltät mietet er einen Subversion-Account (100MB für <10€ im Monat) auf das alle Mitarbeiter von überall her sicher zugreifen können.
Damit schafft er zugleich auch eine zusätzliche Datensicherungsebene.
Wie behält Rufus die Übersicht? Wie kann er die Arbeit seines neuen Mitarbeiters gezielt prüfen und freigeben?
Da Absprachen absehbar nicht funktionieren, kombiniert Rufus die Varianten 2 und 3.
Er überprüft laufend die Commit-Protkolle seines Mitarbeiters und friert regelmäßig Versionsstände in Branches ein, die dann qualitätsgesichert und ggf. nachgebessert werden können.
Korrekturen in einem Branch können bei Bedarf auch wieder in den Hauptast (trunk) migiriert werden.
Nach den ersten Schritten realisiert Rufus, dass das Forrest-eigene Format proprietär und damit auch nicht sonderlich zukunftsträchtig ist.
Daher erstellt Rufus neue Seiten nur noch in XHTML.
Nebenbei sammelt Rufus auch Erfahrungen mit anderen Formaten. Für viele bietet Forrest mittlerweile Plugins (sie http://forrest.apache.org/pluginDocs/plugins_0_80/index.html) , die man nur noch installieren muss.
Für andere Formate (z.B. DITA) experimentiert Refus mit selbstgeschriebenen Transformationen. Da diese nur zum recht einfachen Document V2-Format transformieren müssen, stellt sich das als leichter heraus als gedacht.
Inzwischen schreibt Rufus sehr viel in seinem Single Source Publishing System und erkennt die Notwendigkeit für einen brauchbaren XML-Editor.
Aus verschiedenen Vorträgen weiss er, wie wichtig ein visueller Modus für die Arbeit mit großen Texten ist und, weil er keine leistungsfähigen Open Source Produkte findet, investiert in Oxygen,ein kommerzielles Produkt.
Das Handbuch ist inzwischen so erfolgreich, dass Rufus auch eine englische Version erstellen soll. Dafür bietet Forrest viele Möglichkeiten:
Rufus wählt die zweite Möglichkeit, weil diese seinen Anforderungen besser gerecht wird.