DocBook.sml

Mehrsprachige Dokumenation aus einer zentralen Quelle

Die Beschreibung ist einsetzbar. Sie wird laufend ergänzt. Die Übersetzung ist in Arbeit. Noch nicht übersetzte Texte werden in englischer Sprache ausgegeben.

Software und Dokumentation werden unter den Regeln der GNU LGPL LIzenz unter Ausschluss jeglicher Garantien und Gewährleistungen veröffentlicht.

2006-12-03

Revision History

Table of Contents

Was ist DocBook.sml?
Schnellstart
Ansatz
Leistungsumfang
Referenz
Roadmap
Beispiele
Tutorial
Glossar
Links
Rechtlicher Rahmen
Powered by

sml steht für singlesource multi-language, also eine einzige Quelle für eine mehrsprachige Dokumentation. DocBook.sml bietet einen einfachen und sicheren Form eine mehrsprachige Dokumentation zu pflegen. Der Kerngedanke von DocBook.sml ist, semantisch identischen, aber sprachlich unterschiedlichen Kontent in einer Quelle zusammen zu halten bzw. zu sammeln und von dieser Quelle alle gewünschten Dokumentations-Artefakte abzuleiten.

Mit DocBook.sml verwalten Sie Ihre Dokumentation in mehreren Sprachen in einem einzigen docbook-Dokument. Die gewünschten Dokumentations-Artefakte (html, pdf, txt,xml) werden dann in einem einzigen Produktionsschritt für die einzelnen Sprachen erzeugt. Die DocBook.sml-Dokumentation wurde selbst mit DocBook.sml erzeugt. Deshalb erklärt ein ein paralleler Blick auf a) die Quelldatei der Dokumentation, die Sie gerade lesen (siehe doc/docbooksml.xml) and b) die generierten Dokumentationsartefakte (siehe den Inhalt des Verzeichnisses doc/build) erklärt am Besten, was DocBook.sml leistet.

Der Kerngedanke von DocBook.sml ist, semantisch identischen, aber sprachlich unterschiedlichen Kontent in einer Quelle zusammen zu halten bzw. zu sammeln und von dieser Quelle alle gewünschten Dokumentations-Artefakte abzuleiten.

DocBook.sml bietet einen einfachen und sicheren Weg an mehsprachige Dokumentationen zu pflegen. Passend zu Ihrer inhaltlichen Vorgehensweise können Sie frei entscheiden, in welcher Art - oder besser auf welcher Ebene - Sie nach Sprachen getrennt arbeiten wollen. Sie können die Sprachversionen der Dokumentation auf der Ebene von sections separieren.


Oder Sie halten alles zusammen in einer section und Pflegen die Sprachversion der Dokumenation auf <para>- level. Beispiel:


Table 1.  Leistungsumfang

Leistungsmerkmal

Beschreibung

Konsistente Pflege von mehrsprachigen Dokumenten.

Der Kerngedanke von DocBook.sml ist, semantisch identischen, aber sprachlich unterschiedlichen Kontent in einer Quelle zusammen zu halten bzw. zu sammeln und von dieser Quelle alle gewünschten Dokumentations-Artefakte abzuleiten.

Vereinheitlichte Dokumentations-Strukturen für alle Projekte

DocBook.sml konzentriert alle Quell- und Artefakt-Vorlagen, Arbeitsabläufe und Verweise/Zugriffe auf die Subsysteme an einem Platz. Auf diese Weise kann DocBook.sml den zu dokumentierenden Projekten eine einheitliche Struktur bieten.

Anpassbare Quell- und Ziel-Vorlagen und Arbeitsabläufe

Beim Entwurf von DocBook.sml war Flexibilität ein zentraler Gedanke. Auf der Eingabeseite können Sie Ihr eigene Vorlagen entwerfen (bzw. die mitgelieferten anpassen), die DocBook.sml dann für die Projekte einrichtet. Auf der Ausgabeseite wir zur Erstellung Artefakte hauptsächlich DocBook XSL eingesetzt, womit ein hohes Maß an Flexiblität gewährleistet ist. Durch den Einsatz von ant unterstützt DocBook.sml auch die Arbeitsabläufe sehr flexibel.

Unterstützung von CAT (Computer aided Translation, d.h. Computer gestützte Übersetzung)

DocBook.sml kann mit OmegaT (derzeit das einzige open source CAT System) zusammen arbeiten. Diese Schnittstelle wird wahrscheinlich auch in der Zusammenarbeit mit anderen CAT Systemen eingesetzt werden können. (under construction)

Kann als Teil einer IDE und/oder standalone betrieben werden

Die Einrichtung und das Betreiben von DocBook.sml ist sehr einfach. Alle notwendigen classpath-Einträge sind bereits in den ant-Scripten enthalten und machen die classpath-Adaption (sowohl auf Betriebssystem- als auch auf eclipse-Ebene) überflüssig.

Fasst alle notwendigen Resourcen an einem Ort zusammen

Alle notwendigen Resourcen (Ein- und Ausgabevorlagen, Skripte) werden zentral in den Unterverzeichnissen von DocBook.sml verwaltet. Der Zugriff auf die eingesetzten Subsysteme ist durchgängig parametrisiert.

Entkoppelt die funktionalen Resourcen von den tatsächlichen Versionen der Subsysteme

Der Einsatz von xmlCatalog und Parametrisierung erleichtert die Installation und die Systemplege erheblich. Alle Subsystem sind über indirekte Referenzierung separiert. Ihre Versionen, Lokationen (und wenn Alternativen vorhanden sind auch die Anbieter) können Änderung der Referenz einfach ausgetauscht werden.

Umfassendes Beispiel für den Einsatz von DocBook XSL

In DocBook.sml ist die angepasste Generierung aller wesentlichen von DocBook XSL angebotenen arten von Artefakten (Html, Html chunked, PDF, eclipse) realisiert. Da zudem die DocBook.sml Dokumentationsquellen in der Distribution enthalten sind, stellt DocBook.sml ein umfassendes Beispiel der Nutzung von DocBook XSL dar.

kostenlos

DocBook.sml steht Ihnen kostenlos unter den Bedingungen der GNU LGPL Lizenz zur Verfügung.


Da DocBook.sml derzeit für die Dokumentation von Software-Projekten eingesetzt wird, ist die aktuelle Struktur auch auf diese Art von Projekten ausgerichtet. Mit der mitgelieferten Dokumentations-Vorgabedatei wird eine (sehr knappe) mögliche Struktur für eine Applikationsdokumentation vorgeschlagen. Desweiteren ist der Generierungsprozess so eingestellt, dass für jede Sprache eine HTML-Site, eine PDF-Datei, sowie Releasenotes in verschiedenen Zielformaten ausgegeben werden. Selbstverständlich sind Dokumentations- Vorgabedatei und Generierungsprozess entsprechend der eigenen Vorstellungen anzupassen.

docbook.build_doc besteht aus einem XSLT-Script-Set, dass eine komplette Projektdokumentation unter Verwendung der docbook xsl suite von Normanm Walsh generiert.

Das Script-Set ist für die Nutzung in einer Entwicklungsumgebung bestimmt. Sie können es aber auch stand-alone einsetzen. Bis jetzt wurde es in folgender Umgebung eingesetzt:

Wenn Sie noch nicht die Dokumentationsvorlage ausgewählt haben, die Sie in Ihren Projekten verwenden wollen, ist jetzt der richtige Zeitpunkt dafür. Folgende Werte sind zulässig:


Letztenendes können Sie DocBook.sml nutzen, indem Sie keine weiteren als die Konventionen der docbook.dtd einhalten. Wenn Sie DocBook.sml nutzen wollen, um andere Funktionen als die Unterstützung der mehrsprachigen Dokumentation nutzen wollen, können Sie die Ausführungen zu den 'Konventionen für die Trennung des Contents nach Sprachen' und natürlich auch den 'Konventionen für die Unterstützung von CAT (Computer Aided Translation; Computer gestütztes Übersetzen)' überspringen.

Einsprachige Elemente Elemente mit Content in nur einer Sprache erhalten KEIN <lang>-Attribut. Diese Elemente werden in jede Sprachversion übertragen.


Mehrsprachige Elemente Existiert Content in mehreren Sprachen, erhält jedes sprach-spezifisches Element ein <lang>-Attribut.


Subelemente Subelemente erben ausnahmslos die Wirkung des <lang>-Attributs ihres Superelements. Hat ein Superelement ein <lang>-Attribut bleiben etwaige <lang>-Attribute aller Subelements wirkungslos. Das <lang>-Attribut des Superelements wirkt immer für das Superelement selbst und alle Elemente, die es enthält.


todo

todo

todo


Das DocBook.sml-Projekt (bzw. der DocBook.sml-Ordner) enthält den 'doc'-Ordner und die ant Skripte


Sowohl das DocBook.sml-Projekt als auch die projecte, die DocBook.sml speichert und suchtalle relevanten Resourcen im Verzeichnis 'doc'.


'install' ist mit einigen kleinen Abweichungen eine 1:1-Kopie des 'doc'-Verzeichnisses. Der Inhalt von 'install' wird im Rahmen der Installation in andere Projekte in das 'doc'-Verzeichnis dieser Projekte übertragen.


Im 'conf'-Verzeichnis finden Sie sowohl die globalen als auch die lokalen Konfiguriatonsdateien. Im 'conf'-Verzeichnis eines Projektes, in das DocBook.sml installiert wurde, werden sie nur lokale Konfiguriatonsdateien finden.

Das ant Skript 'addToProject.xml' überträgt alle notwendigen DocBook.sml-Resourcen deploys zu dem gewünschten Projekt. Markieren Sie die Datei 'addToProject.xml' und wählen Sie 'External Tool..." vom 'External Tools'-Buttons (oder wählen Sie Menupunkt 'Run' -> 'External Tool... -> 'External Tool...').


Wählen sie ant als external program und betätigen Sie den 'Anlegen'-Button um eine neue Start-Konfiguration für ant anzulegen.


As Parameter type in name and location of the project you are deploy DocBook.sml to. Press the 'Apply'-Button to store the run configuration. Press the 'Run'-Button to run the ant script.


Wenn alles problemlos läuft, werden Sie eine Erfolgsmeldung erhalten, die in etwa wie folgt aussieht:

Buildfile: C:\develop\tests\eclipse\net.sf.docbooksml\addToProject.xml
check:
checkMessage:
install:
[copy] Copying 65 files to C:\develop\tests\eclipse\testProject1
[propertyfile] Updating property file: ...\testProject1\doc\conf\docbooksml.local.properties
[copy] Copying 1 file to C:\develop\tests\eclipse\testProject1\doc
all:
BUILD SUCCESSFUL
Total time: 1 second
	      

Sollte die Installation für dieses Projekt nicht das erste Mal laufen, erhalten Sie eine Fehlermeldung, die etwa wie folgt lautet:

Buildfile: C:\develop\tests\eclipse\net.sf.docbooksml\addToProject.xml
check:
checkMessage:
[echo] !!! W A R N I N G !!!!
[echo] The directory 'doc' still exists in '../testProject1'.
[echo] ...the target project directory must not contain a directory named 'doc'.
[echo] The installation aborts for avoiding unintentional overwriting.
install:
all:
BUILD SUCCESSFUL
Total time: 841 milliseconds
	      

todo

todo

Software und Dokumenation wird unter den Bedingungen der GNU LGPL Lizenz (see http://www.gnu.org/copyleft/lesser.html) unter Ausschluss jeglicher Garantien und Gewährleistungen veröffentlicht.

Copyright © 2006 joerg.moebius@hamburg.de

sourceforge logo

sourceforge logo

sourceforge logo

sourceforge logo