1.3.7 Establish system-wide configuration settings

Telling DITA2Go how to use certain tools will allow you to run conversions directly from the DITA2Go Project Manager.

To specify values for system-wide settings that apply to all Omni Systems applications, open the following configuration file in a text editor:

%omsyshome%\common\local\config\local_omsys.ini

This configuration file is accessed by all other DITA2Go configuration files, through chains of links; the settings it contains are available to all DITA2Go projects. You can place in this file any setting that will apply to most or all of your DITA2Go and Mif2Go projects. For particular DITA documents or conversion projects, you can override these settings in output- or document-specific configuration files.

Note:  For proper syntax, see §3.3 Understanding the rules for configuration settings.

Specify settings for any of the following features that might be required for your conversion projects:

XML catalogs

Specialized DTD

Archiving program and options

HTML Help compiler command

Eclipse Help zip command

JavaHelp, Oracle Help index and JAR commands

WinHelp copyright statement and compiler command

Location of document-specific settings

View-output command

XML catalogs

If you have specialized, you must prepare an XML catalog for your specialized DTDs, list their local paths here, and define an access key for each. See §4.1.1 Connecting to XML catalogs.

Specialized DTD

By default, DITA2Go uses the Oasis DITA 1.1 DTD located in directory %OMSYSHOME%\common\dtds\dita1.1, or whichever catalog you have specified. If your DITA XML includes specializations for which you did not create a catalog, you must tell DITA2Go where to find your own DTD:

[Setup]
DTDPath=path\to\specialized\dtd

See §4.1.3 Specifying a DITA XML DTD.

Archiving program and options

DITA2Go can package the output from your conversion projects in .zip files for distribution. You must provide an archiving program that can be run from a command line, and specify appropriate parameters:

[Automation]
ArchiveCommand = path\to\archiver
ArchiveStartParams = parameters preceding name of archive file
ArchiveEndParams = parameters following name of archive file
ArchiveExt = file extension; usually zip
MoveArchive = Yes to move archive, No to copy archive
LogAuto = Yes to record archiving steps in the run log

See §44.11 Archiving deliverables. You can use the DITA2Go Project Manager to specify an archive name and version for each project. The starting and ending parameters for the archive command have default values; for some output types you will need to override these defaults in your project configuration file.

HTML Help compiler command

For HTML Help projects, DITA2Go can run the Microsoft HTML Help compiler for you, to produce compiled CHM files. Unless the compiler is on your system PATH, you must tell DITA2Go where to find it:

[MSHtmlHelpOptions]
Compiler = path\to\hhc

See §18.13.1 Directing DITA2Go to run the HTML Help compiler.

Eclipse Help zip command

For Eclipse Help projects, DITA2Go can package your HTML topic files in doc.zip. You must provide an archiving program that can be run from a command line, and specify appropriate parameters:

[EclipseHelpOptions]
ZipCommand = path\to\archiver
ZipParams = all required parameters

See §21.8 Packaging Eclipse Help files.

JavaHelp, Oracle Help index and JAR commands

For JavaHelp projects, DITA2Go can run the JavaHelp indexer to produce a full-text search index, and also package the output in a .jar file. You must specify the indexer and JAR commands:

[JavaHelpOptions]
FTSCommand = path\to\jhindexer
JarCommand = path\to\jar

For Oracle Help projects, DITA2Go can run the Oracle Help indexer to produce a full-text search index:

[OracleHelpOptions]
FTSCommand = java -mx256m oracle.help.tools.index.Indexer

See §20.5 Providing full-text search for JavaHelp / Oracle Help, and §20.6.1 Creating a JAR file.

WinHelp copyright statement and compiler command

For WinHelp projects, DITA2Go can provide a copyright statement to be included in the WinHelp .hpj project file:

[HelpOptions]
HelpCopyright = your copyright statement

DITA2Go can also run the Microsoft WinHelp compiler for you, to produce compiled HLP files. Unless the WinHelp compiler is already on your system PATH, you must tell DITA2Go where to find it. For example:

[HelpOptions]
; Compiler = path\to\hcw; can include run parameters
Compiler = hcw /c /e

See §17.2.9 Compiling a WinHelp project.

Location of document-specific settings

You can choose a default location for document-specific configuration files on the Preferences tab of the DITA2Go Project Manager; see §2.6 Customizing the DITA2Go Project Manager. To determine which location is appropriate, see §39.3.3 Deciding where to keep document-specific configuration files.

View-output command

When you use the DITA2Go Project Manager to run a conversion, you can view the output immediately with the View Output button on the Run Project tab, provided the Project Manager can launch an appropriate viewer:

You can specify an absolute path or a path relative to the wrap directory. For example.

[JavaHelpOptions]
ViewOutputCommand = java -jar D:\JH2\demos\bin\hsviewer.jar -helpset

Specify each view-output command in an options configuration section specific to the output type: 

Output type

Options configuration section

DITA XML

[DITAOptions]

Docbook XML

[DocBookOptions]

Eclipse Help

[EclipseHelpOptions]

HTML/XHTML

[HTMLOptions]

JavaHelp

[JavaHelpOptions]

Microsoft HTML Help

[MSHtmlHelpOptions]

Microsoft Word

[WordOptions]

OmniHelp

[OmniHelpOptions]

Oracle Help for Java

[OracleHelpOptions]

WinHelp

[HelpOptions]

XML (flat)

[HTMLOptions]

Your DITA2Go installation is now complete, and you can set up a DITA2Go conversion project, or run an existing conversion. Your existing project configuration files will work without modification. See §2. Converting DITA documents.

Previous Topic:  1.3.6 Obtain tools for Help systems or eBooks

Next Topic:  1.3.8 Obtain a file comparison tool (optional)

Parent Topic:  1.3 What you need to do

Sibling Topics:

1.3.1 Set up a framework for Omni Systems applications

1.3.2 Download a DITA2Go distribution

1.3.3 Install DITA2Go

1.3.4 Make Omni Systems executables accessible

1.3.5 Check your DITA2Go installation

1.3.6 Obtain tools for Help systems or eBooks

1.3.8 Obtain a file comparison tool (optional)

1.3.9 Download the DITA2Go User’s Guide (optional)

1.3.10 Integrate DITA2Go with <oXygen/> (optional)