description usable, to be completed.
Copyright © 2006 joerg.moebius@hamburg.de
Software and documentation is released under the terms of the GNU LGPL license and comes without a warranty of any kind.
2006-12-03
Table of Contents
sml stands for singlesource multi-language. DocBook.sml provides an easy and secure way to maintain multilingual documentations. The core idea of DocBook.sml is keeping/assembling all documentation content of identical semantic, but of different language together in/into one document and deriving from such a 'documentation repository' all desired documentation artifacts.
With DocBook.sml you maintain your multilingual documentation in a single docbook-document. Based on that 'documentation repository' you can easily produce your documentation artifacts separeted by language in a single run. Obviously the DocBook.sml-documentation itself is built using DocBook.sml. Therefore a parallel look at a) the source (see doc/docbooksml.xml) and b) the generated artifacts (see the content of the directory doc/build) of the documentation you are still reading depicts at best where DocBook.sml is good for.
The following packages have to be available (installed) on an arbitrary location:
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)
Check out DocBook.sml from svn repository https://svn.sourceforge.net/svnroot/xsdtrans or download docbooksml-n-n-n.zip from http://docbooksml.sourceforge.net (menu item 'download') and unpack the file into an arbitrary <DocBook.sml-installation-directory>.
Within the svn repository DocBook.sml is stored as an eclipse project. So you can check out DocBook.sml into your eclipse workspace without any changes.
In <Docbook.sml-installation-directory>/doc/config/docbookCatalog.xml you will find the pointers to the DocBook-XSL location. 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.
The core idea of DocBook.sml is keeping/assembling all documentation content together in/into one document and deriving from such a documentation repository all desired documentation artifacts.
DocBook.sml provides an easy and secure way to maintain multilingual documentations. Depending on your individual working procedures you can decide the manner - or better the level - you would like to treat language-sensitiv content. For example you can maintain a top-level-section for each language (you will find an English and a German section of the section you are still reading).
Example 1. Separating Languages on Top Level
...
<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>
...
Or you keep all together in one single section and separete the language-content on the <para>-level. Example:
Example 2. Separating Languages on Low Level
... <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
maintains a documentation template (see doc/install) and provides an easy deployment mechanism (see ant-script addToProject.xml)
holds all procedural resources for generating the documentation-artifacts (see doc/script)
abstracts from the underlaying subsystems resp. its actual versions (see doc/conf/docbooksml.properties)
Table 1. Features
|
Feature |
Description |
|---|---|
|
Consistent maintenance of multilingual documentation. |
The core idea of DocBook.sml is keeping/assembling all documentation content of identical semantic, but of different language together in/into one document and deriving from such a 'documentation repository' all desired documentation artifacts. |
|
Unified documentation structures for all projects |
DocBook.sml gathers all source and target templates, procedures and references to the subsystems into one place. In that way DocBook.sml can provide unified documentation structures (templates AND procedures) to the projects. |
|
Customizable input and output templates and documentation procedures |
DocBook.sml is designed with flexibility in mind. At input side you design your own templates (reps. adapt the provided ones) according your needs once and DocBook.sml will deploy it to the projects. At output side the production of artifacts based mainly on DocBook XSL which implies a high degree of flexibility. Due to the use of ant Docbook.sml supports the documentation procedures in a very flexible manner. |
|
CAT (Computer aided Translation) Support |
DocBook.sml provides a collaboration with OmegaT (at the moment the only open source CAT sytem). This interface should also be usable in collaboration with other CAT systems. (under construction) |
|
Runs as part of an IDE and/or standalone |
You can easily deploy and run DocBook.sml in any ant-enabled environment (like eclipse). All classpath entries are captured within the ant-script. No classpath adaption (nor on system neither on eclipse level) is necessary. |
|
Concentrates all necessary resources at one location |
All necessary resources are stored centraly in DocBook.sml's Subdirectories. The access to the used subsystem is totally parameterized. |
|
Decouples the functional resources from subsystem versions |
The usage of xmlCatalog and Parameterization facilitates the deployment and maintenance. All subsystems are cleary separated and can easily changed in version and location (and vendor if alternatives are available). |
|
Comprehensive example for the usage of DocBook XSL |
In DocBook.sml the customized generation of all major kinds of artifacts DocBook XSL provides (Html, Html chunked, PDF, eclipse) is realized. As the DocBook.sml documentation sources are part of the distribution DocBook.sml is a comprehensive example for the usage of DocBook XSL. |
|
Free of charge. |
DocBook.sml comes free of charge under the terms of GNU LGPL license. |
As DocBook.sml is recently used for the documentation of software projects, the present structure is designed for such kind of documentation. The contained documentation template file suggests a brief application documentation structure. Furthermore the build process is ajusted to generate for each language an html-site, pdf-file and releasenotes of several formats. Obviously you have to adopt templates and the generation process of the desired results according your needs.
DocBook.sml constists of a set of ant and xsl scripts which generates a complete project documentation. It uses the docbook xsl suite of Norman Walsh.
The scripts are made to be used in a development environment. Though you can use it also stand-alone. Until now they have been used in the following eclipse environment.
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.
The DocBook.sml project (resp. the DocBook.sml-Directory) contains the directory 'doc' and the ant scripts
addToProject.xml - deploys DocBook.sml to another Project
build.xml - builds the DocBook.sml Distribution files
buildDoc.xml - builds the DocBook.sml documentation artifacts
The DocBook.sml project as well as the project which uses DocBook.sml stores and seeks all relevant resources within a subdirectory called 'doc'.
'install' is (with some small exceptions) an image of the 'doc' directory. By deploying DocBook.sml the content of 'install' will be tranfered to the 'doc'-directory of these projects.
In the 'conf'-directory you find the global configuriaton files as well as the local configuration files. In the 'conf'-directory of an project DocBook.sml is deployed to you will find only the local configuration files.
The following packages have to be available (installed) on an arbitrary location:
Table 2. Required Packages
|
Package |
Usage |
|---|---|
|
Java |
Version 1.5.0_08 is currently in use. You can obtain Java at http://www.java.com/. |
|
ant |
Version 1.7.0Beta3 is currently in use. ant controls the processing in standalone mode and IDE mode. DocBook.sml is tested in standalone mode, though until now operational experiences are present only for the usage within an eclipse-environment. You can obtain ant at http://ant.apache.org/. |
|
DocBook.DTD |
Version 4.4 is currently in use. You can obtain the DTD-file at http://www.oasis-open.org/docbook/xml/4.4/. |
|
DocBook XSL |
Version 1.71.1 is currently in use. DocBook XSL is used for generating the documentation artifacts. You can obtain DocBook XSL at http://www.oasis-open.org/docbook/xml/4.4/. |
|
xalan (Version 2.7.0) | |
|
saxon | |
|
fop (0.92beta or above) | |
|
lynx |
Check out DocBook.sml from svn repository https://svn.sourceforge.net/svnroot/xsdtrans or download docbooksml-n-n-n.zip from http://docbooksml.sourceforge.net (menu item 'download') and unpack the file into an arbitrary <DocBook.sml-installation-directory>.
Within the svn repository DocBook.sml is stored as an eclipse project. So you can check out DocBook.sml into your eclipse workspace without any changes.
In <DocBook.sml-installation-directory>/doc/config/docbookCatalog.xml you will find the pointers to the DocBook-XSL location. 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.
If you haven't yet choosen your input template (parameter 'docbook.template') you would like to deploy your projects it is recommended to do it now. You can find this parameter 'docbook.template'in the global property file 'docbook.properties'. Valid value are:
Table 3. Features
If you haven't yet choosen your input template (parameter 'docbook.template') you would like to deploy your projects it is recommended to do it now. You can find this parameter 'docbook.template'in the global property file 'docbook.properties'. Valid value are:
Table 4. Features
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.
Finally you can use DocBook.sml without following other conventions than the constraints of the docbook.dtd. If you only want to benefit from other DocBook.sml feature than the support for multilingual documentation you can skip the 'Conventions For Separating Content By Language' and obviously also the 'conventions for supporting CAT (Computer Aided Translation)'.
Monolingual elements . Language-insensitive elements gets NO <lang> attribute. Such elements will be passed into each language version.
Example 3. Monolingual elements
...
<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>
...
Multilingual elements . Language-sensitive elements gets an <lang> attribute.
Example 4. Multilingual elements
...
<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>
...
Subelements . Subelements inherits unexceptionally the effect of the <lang> attribute of their super element. When a super element contains an <lang> attribute, any <lang> attribute of any sub (and sub sub) element takes no effect. The <lang> attribute of the super element keeps always its effect for the super element itself and all elements it contains.
Example 5. Subelements
... <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> ...
Mutlilingual Elements . Elements containing language-specific content gets (beside the lang attribute an id. All elements containing content of identical semantic in different languages gets ids which are equal except the language suffix. The value of the language suffix is equal to the value of the lang attribute.
.
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
The DocBook.sml project (resp. the DocBook.sml-Directory) contains the directory 'doc' and the ant scripts
addToProject.xml - deploys DocBook.sml to another Project
build.xml - builds the DocBook.sml Distribution files
buildDoc.xml - builds the DocBook.sml documentation artifacts
The DocBook.sml project as well as the project which uses DocBook.sml stores and seeks all relevant resources within a subdirectory called 'doc'.
'install' is (with some small exceptions) an image of the 'doc' directory. By deploying DocBook.sml the content of 'install' will be tranfered to the 'doc'-directory of these projects.
In the 'conf'-directory you find the global configuriaton files as well as the local configuration files. In the 'conf'-directory of an project DocBook.sml is deployed to you will find only the local configuration files.
The ant script 'addToProject.xml' deploys all necessary DocBook.sml stuff to the appropriate project. Select the file 'addToProject.xml' and choose 'External Tool..." from the 'External Tools'-Buttons (or choose Menuitem 'Run' -> 'External Tool... -> 'External Tool...').
As external program select ant and press the 'new'-Button for creating a new run-configuration for ant.
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.
If everything works find, you will get a success message similar the following:
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
But if it is not the first time, the deployment for this programs is running, you will an error message like:
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
After deploying DocBook.sml to the testProject1 you can build the artifacts the first time for testing by running the 'buildDoc.xml' script.
The ant script 'buildDoc.xml' produces the hole set of documentation artifacts. Select the file 'buildDoc.xml' and choose 'External Tool..." from the 'External Tools'-Buttons (or choose Menuitem 'Run' -> 'External Tool... -> 'External Tool...').
As external program select ant and press the 'new'-Button for creating a new run-configuration for ant.
Press the 'Run'-Button to run the ant script.
If everything works fine, you will get a success message which ends with something like:
... all: BUILD SUCCESSFUL Total time: 1 minute 44 seconds
Assuming a successful run you will find all generated artifacts within the 'build' directory.
Software and documentation is released under the terms of the GNU LGPL license (see http://www.gnu.org/copyleft/lesser.html) and comes without a warranty of any kind.
Copyright © 2006 joerg.moebius@hamburg.de
