Skip to content

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-8
  • fop.xconf: Configuration for fop tool to produce PDF from a docbook source.
  • index_template.html: Template for index.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:

There are more requirements, a tool and fonts, to generate PDF:

The following fonts must be installed that are used to embed into PDF file:

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