Die Beschreibung ist einsetzbar. Sie wird laufend ergänzt. Die Übersetzung ist in Arbeit. Noch nicht übersetzte Texte werden in englischer Sprache ausgegeben.
Copyright © 2006 joerg.moebius@hamburg.de
Software und Dokumentation werden unter den Regeln der GNU LGPL LIzenz unter Ausschluss jeglicher Garantien und Gewährleistungen veröffentlicht.
2006-12-03
Table of Contents
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.
Java (Version 5.0 or above)
ant (Version 1.7.0Beta3 or above)
DocBook xsl (Version 1.71.1 or above)
DocBook.DTD (Version 4.4)
xalan (Version 2.7.0)
saxon (8.8)
fop (0.92beta or above)
lynx (current version)
Checken Sie DocBook.sml vom svn repository https://svn.sourceforge.net/svnroot/xsdtrans aus oder laden Sie docbooksml-n-n-n.zip von http://docbooksml.sourceforge.net (hier der Menüpunkt 'download') herunter und entpacken Sie die Datei in ein beliebiges <DocBook.sml-installation-directory>.
DocBook.sml ist im svn repository DocBook.sml als ein eclipse Projekt gepseichert. Deshalb können Sie docbook.smk in Ihren eclipse workspace auschecken, ohne Änderungen vornehmen zu müssen.
In <DocBook.sml-installation-directory>/doc/config/docbooksml.local.properties you will find a property called 'docbooksml.dir'. This files properties which point to the locations of SAXON, FOP and LYNX. Ajust these location properties to your individual environment.
In <DocBook.sml-installation-directory>/doc/config/docbooksml.local.properties you will find a property called 'docbooksml.local.dir'. Ajust it to <DocBook.sml-installation-directory>. Then copy this property file to <DocBook.sml-installation-directory>/doc/install/doc/conf/. You will overwrite a still existing file.
On OS-Prompt change to <DocBook.sml-installation-directory> and start
ant -f docBuild.xml
If this run ends with something like:
all: BUILD SUCCESSFUL Total time: 1 minute 46 seconds
DocBook.sml and all necessary subsystems are properly installed and configured. Now you should find new generated artifacts in the diectory <DocBook.sml-installation-directory>/doc/build/.
Assuming you have a project named 'project1' which resides at the location '/home/groups/develop/project1Location'. The ant script 'addToProject' transfers all necessary recoures for using DocBook.sml to your project.
on OS-Prompt change to <DocBook.sml-installation-directory> and start
ant -f addToProject.xml -Dtarget.project.name=project1 -Dtarget.project.location=/home/groups/develop/project1Location
If this run ends with something like:
all: BUILD SUCCESSFUL Total time: 1 minute 46 seconds
DocBook.sml is properly deployed to your project 'project1'. Now you can work with DocBook.sml within 'project1'. Try
ant -f docBuild.xml
and you will find the documentation artifacts within the subdirectory 'doc/build' of your project.
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.
Example 1. Trennung der Sprachen auf höchster Ebene
...
<section id="main">
<title>DocBook.sml</title>
<subtitle>
<phrase lang="en">Generates a Multilingual ...</phrase>
<phrase lang="de">Generiert aus einer ...</phrase>
</subtitle>
<section id="what.is">
<title>
<phrase lang="en">What is DocBook.sml?</phrase>
<phrase lang="de">Was ist DocBook.sml?</phrase>
</title>
<para lang="en">
sml stands for ...
</para>
<para lang="de">
sml steht für ...
also eine einzige ...
</para>
...
</section>
</section>
...
Oder Sie halten alles zusammen in einer section und Pflegen die Sprachversion der Dokumenation auf <para>- level. Beispiel:
Example 2. Trennung der Sprachen auf niedriger Ebene
... <section id="main" lang="en"> <title>DocBook.sml</title> <subtitle>Generates a Multilingual ...</subtitle> <section id="what.is"> <title> What is DocBook.sml? </title> <para> sml stands for ... </para> ... </section> </section> <section id="main.de" lang="de"> <title>DocBook.sml</title> <subtitle>Generiert aus einer ...</subtitle> <section id="what.is.de"> <title> Was ist DocBook.sml? </title> <para> sml steht für ... also eine einzige ... </para> ... </section> </section> ...
DocBook.sml
verwaltet eine Dokumentationsvorlage (siehe doc/install) und bietet einen einfachen und wirkungsvollen installationsmechanismus (siehe ant-script addToProject.xml)
konzentriert alle funktionalen und prozeduralen Resourcen im DocBook.sml-Projekt/Verzeichnis
abstrahiert von den unterliegenden Subsystemen bzw. ihren tatsächlichen versionen (siehe doc/conf/docbooksml.properties)
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:
docbook (experience made with Version xsl 1.71.1); mandatory
docbook.dtd (Version 4.4.); optional (if omitted dtd will be fetched via internet; access required!)
saxon (experience made with Version 6.5.3 and 8.8; 8.8 preferred); mandatory
fop (experience made with Version 0.91beta and 0.92beta, 0.92beta preferred); optional; you can omit if you don't want to generate pdf artifacts.
lynx (current version); optional; you can omit if you don't want to generate txt artifacts.
Das DocBook.sml-Projekt (bzw. der DocBook.sml-Ordner) enthält den 'doc'-Ordner und die ant Skripte
addToProject.xml - installiert DocBook.sml in ein anderes Projekt
build.xml - erstellt die DocBook.sml-Distributionsdateien
buildDoc.xml - erstellt die DocBook.sml Dokumentations-Artefakte
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.
Table 2. Notwendige Packages
|
Package |
Nutzung |
|---|---|
|
Java |
Version 1.5.0_08 wird derzeit genutzt. Sie können Java unter http://www.java.com/ beziehen. |
|
ant |
Version 1.7.0Beta3 wird derzeit genutzt. Mit ant werden die Prozessausführungen im Standalone Mode und im IDE Mode gesteuert. Der Standalone Mode ist zwar getestet, aber praktische Erfahrungen mit Docbook.sml liegen nur aus der Nutzung in einer eclipse-Umgebung vor. Sie können Java unter http://www.java.com/ beziehen. |
|
DocBook.DTD |
Version 4.4 wird derzeit genutzt. Sie können die DTD-Datei unter http://www.oasis-open.org/docbook/xml/4.4/ beziehen. |
|
DocBook XSL | |
|
xalan (Version 2.7.0) | |
|
saxon | |
|
fop (0.92beta or above) | |
|
lynx |
Checken Sie DocBook.sml vom svn repository https://svn.sourceforge.net/svnroot/xsdtrans aus oder laden Sie docbooksml-n-n-n.zip von http://docbooksml.sourceforge.net (hier der Menüpunkt 'download') herunter und entpacken Sie die Datei in ein beliebiges <DocBook.sml-installation-directory>.
DocBook.sml ist im svn repository DocBook.sml als ein eclipse Projekt gepseichert. Deshalb können Sie docbook.smk in Ihren eclipse workspace auschecken, ohne Änderungen vornehmen zu müssen.
In <DocBook.sml-installation-directory>/doc/config/docbooksml.local.properties you will find a property called 'docbooksml.dir'. This files properties which point to the locations of SAXON, FOP and LYNX. Ajust these location properties according to your individual environment.
In <DocBook.sml-installation-directory>/doc/config/docbooksml.local.properties you will find a property called 'docbooksml.local.dir'. Ajust it to <DocBook.sml-installation-directory>. Then copy this property file to <DocBook.sml-installation-directory>/doc/install/doc/conf/. You will overwrite a still existing file.
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:
Table 3. Leistungsumfang
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:
Table 4. Leistungsumfang
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.
Figure 5. Die Installation von DocBook.sml in ein anderes Projekt konfigurieren und den Prozess starten
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.
Example 3. Einsprachige Elemente
...
<title>DocBook.sml</title>
<subtitle>Generates a Multilingual ...</subtitle>
<section id="what.is">
<title>What is DocBook.sml?</title>
<para>
sml stands for ...
</para>
...
</section>
...
Mehrsprachige Elemente . Existiert Content in mehreren Sprachen, erhält jedes sprach-spezifisches Element ein <lang>-Attribut.
Example 4. Mehrsprachige Elemente
...
<title>DocBook.sml</title>
<subtitle>
<phrase lang="en">Generates a Multilingual ...</phrase>
<phrase lang="de">Generiert aus einer ...</phrase>
</subtitle>
<section id="what.is">
<title>
<phrase lang="en">What is DocBook.sml?</phrase>
<phrase lang="de">Was ist DocBook.sml?</phrase>
</title>
<para lang="en">
sml stands for ...
</para>
<para lang="de">
sml steht für ...
also eine einzige ...
</para>
...
</section>
...
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.
Example 5. Subelemente
... <title>DocBook.sml</title> <subtitle> <phrase lang="en">Generates a Multilingual ...</phrase> <phrase lang="de">Generiert aus einer ...</phrase> </subtitle> <section id="what.is"> <title> <phrase lang="en">What is DocBook.sml?</phrase> <phrase lang="de">Was ist DocBook.sml?</phrase> </title> <para lang="en"> sml stands for ... </para> <para lang="de"> sml steht für ... also eine einzige ... </para> ... </section> ...
Mehrsprachige Elemente . Elements die sprachspezifischen Kontent enthalten, haben (neben dem lang-Attribut) eine id. Alle Elemente, die semantisch gleichen Kontent in unterschiedlichen Sprachen enthalten, erhalten ids, die bis auf ein Sprach-Suffix, gleich sind. Das Sprach-Suffix hat den gleichen Wert wie das lang-Attribut.
.
Example 7.
...
<formalpara>
<title>
<phrase id="conventions.60.title.en" lang="en">
Mutlilingual Elements
</phrase>
<phrase id="conventions.60.title.de" lang="en">
Mehrsprachige Elemente
</phrase>
</title>
<para>
<phrase id="conventions.60.en" lang="en">
Elements containing ...
</phrase>
<phrase id="conventions.60.de" lang="en">
Elements die ...
</phrase>
<para>
</formalpara>
...
todo
Das DocBook.sml-Projekt (bzw. der DocBook.sml-Ordner) enthält den 'doc'-Ordner und die ant Skripte
addToProject.xml - installiert DocBook.sml in ein anderes Projekt
build.xml - erstellt die DocBook.sml-Distributionsdateien
buildDoc.xml - erstellt die DocBook.sml Dokumentations-Artefakte
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.
Figure 11. Die Konfiguration des Starts der Installation von DocBook.sml in ein anderes Projekt anlegen
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.
Figure 12. Die Installation von DocBook.sml in ein anderes Projekt konfigurieren und den Prozess starten
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
Nachdem Sie DocBook.sml in testProject1 installiert haben, können Sie erstmalig (zum Test ohne jede Änderung) Artefakte produzieren, indem Sie das ant Script 'buildDoc.xml' ausführen.
Das ant Skript 'buildDoc.xml' generiert alle Dokumentations-Artefakte. Markieren Sie die Datei 'buildDoc.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.
Press the 'Run'-Button to run the ant script.
Wenn alles problemlos läuft, werden Sie eine Erfolgsmeldung erhalten, die in etwa wie folgt endet:
... all: BUILD SUCCESSFUL Total time: 1 minute 44 seconds
Wenn wir von einer erfolgreichen Ausführung des Scripts ausgehen, werden Sie alle generierten Dokumentations-Artefakte in dem Verzeichnis 'build' finden.
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
