Building the documentation manually
scripts, configuration, styles, and a template
There are several scripts, common configuration, styles, and a template among languages.
doc_src/docgen
: shell script to launch container to produce manuals.build.xml
: Main configuration of ANT build tool.doc_src_paths.xml
: Set the paths for utilities.docbook-utf8.xsl
: Allows issuing the First Steps in UTF-8fop.xconf
: Configuration for fop tool to produce PDF from a docbook source.index_template.html
: Template forindex.html
web manual default page.lang_exceptions.properties
: List of languages to skip a manual build.OmegaT_new.css
: Stylesheet for HTML5 manuals and First Steps.OmegaT_old.css
: Stylesheet for HTML manuals with languages that manual version is 4 or before.whc-header.xsl
,whc-index.xsl
,whc-toc.xsl
: XSL for whc tool kit.
Setting files for a specific environment
The modified doc_src_paths.xml
and docbook-utf8.xsl
must be copied to the
same location as docbook-xml-4.5
.
/path/to/omegat/doc_src/en/
└────/docbook-xml-4.5/
└────/doc_src_paths.xml
└────/docbook-utf8.xsl
command line examples
All the scripts require the language folder as argument and must be run from the
doc_src
directory.
If you want to build with ant
, you must install all the requirements on your environment.
You can also generate with container image, please refer a section
Use a container to build the documentation
Building First Steps only
ant -Dlanguage=en -Dtarget=../docs/en first-steps
Building everything except Javahelp:
ant -Dlanguage=en -Dtarget=../docs/en
Building HTML
ant -Dlanguage=en -Dtarget=../docs/en html5
Building PDF
ant -Dlanguage=en -Dtarget=../docs/en pdf
Building Javahelp
ant -Dlanguage=en -Dtarget=../docs/en javahelp
Dependencies
The creation of the documentation requires a number of tools to build HTML5 manuals:
- DocBook XSL Stylesheets 1.79.2 ("dbk") or above https://github.com/docbook/xslt10-stylesheets
- DocBook XML 4.5 ("docbook-xml-4.5") https://docbook.org/xml/4.5/
- libxml2 2-2.12.4 ("libxml2-2.12.4") http://xmlsoft.org
- Saxon 6-5-5 ("saxon") https://sourceforge.net/projects/saxon/files/saxon6/
- XMLmind Web Help Compiler 3.5_1 ("whc") https://www.xmlmind.com/ditac/whc.shtml
- Ant 1.7.1 or above ("apache-ant") https://ant.apache.org
There are more requirements, a tool and fonts, to generate PDF:
- fop 2.9 ("fop-2.9") https://xmlgraphics.apache.org/fop/2.9/
The following fonts must be installed that are used to embed into PDF file:
- Latin: DejaVu Sans
- Japanese: Noto Sans CJK JP
- Chinese: Noto Sans CJK SC
Installation
Path to the DTD
For efficiency reason, the path to the DTD in the DocBook files (e.g.,
AboutOmegaT.xml
) has been changed to a local path
(../../../docbook-xml-4.5/docbookx.dtd
instead of an http://
reference). Depending on the actual configuration, it might be changed to a
standard reference (http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
) or
to another local reference.
Windows
dbk must be installed at the root of C:
C:\dbk\common
C:\dbk\docsrc
⋮
docbook-xml-4.5 must be installed at the same level as your OmegaT development folder.
So, if you have
C:\dev\omegat
C:\dev\omegat\src
C:\dev\omegat\doc_src
⋮
you would have
C:\dev\docbook-xml-4.5\ent
C:\dev\docbook-xml-4.5\calstblx.dtd
⋮
libxml2-2.12.4 and apache-ant must be installed where a path can find them, usually in Program Files.
C:\Program Files\libxml2-2.12.4.win32
C:\Program Files\apache-ant
Corresponding path
:
path=C:\Program Files\libxml2-2.12.4.win32\bin;C:\Program Files\apache-ant\bin
fop-1.1 can be installed anywhere, usually in Program Files.
C:\Program Files\fop-2.9
The location of fop-2.9, dbk and Saxon must be set in doc_src_paths.xml
,
in the corresponding properties:
<property name="fop.home" value="C:\Program Files\fop-2.9" />
Alternatively, it is possible to set the values of fop.home.lib
and
fop.home.build
separately:
<property name="fop.home.lib" value="C:\Program Files (x86)\fop-2.9\lib" />
<property name="fop.home.build" value="C:\Program Files (x86)\fop-2.9\build" />
<property name="dbk" value="c:\dbk" />
<property name="saxon" value="C:\Program Files\saxon6-5-5\saxon.jar" />
The location of dbk must also be set in docbook-utf8.xsl
:
<xsl:import href="file:///c:\dbk\html\docbook.xsl"/>
Both doc_src_paths.xml
and docbook-utf8.xsl
must be copied at the same level
as your OmegaT development folder.
C:\dev\doc_src_paths.xml
C:\dev\docbook-utf8.xsl
The ones available in doc_src
are only there for reference.
macOS
All the dependencies can be installed through MacPorts except for saxon and whc.
sudo port install apache-ant docbook-xml-4.5 docbook-xsl-nons fop libxml2
Please download and extract saxon and whc and unzip the downloaded packages,
and put them in your preferred location.
The example below uses the /Applications
folder.
Paths
If you use Macports, the doc_src_paths.xml
settings are:
<project>
<property name="fop.home" value="/opt/local/share/java/fop/2.9" />
<property name="dbk" value="/opt/local/share/xsl/docbook-xsl-nons" />
<property name="saxon" value="/Applications/saxon6-5-5/saxon.jar" />
<property name="whc" value="/Application/whc-3_5_1/lib/whc.jar" />
</project>
and the docbook-utf8.xsl
settings are:
<xsl:import href="file:///opt/local/share/xsl/docbook-xsl-nons/html/docbook.xsl"/>
DocBook 4.5 installation
Create a symbolic link from the installed DocBook 4.5 files to the location
where the build process will look for the DocBook DTD: the folder "above"
doc_src
in the OmegaT source tree:
ln -s /opt/local/share/xml/docbook/4.5 /path/to/omegat/docbook-xml-4.5