39.4.1 Understanding what configuration files are available

Most of the supplied DITA2Go configuration files available for editing are located in subdirectories of %OMSYSHOME%\d2g\local, with the following exceptions: 

Table 39-3 lists the types of configuration files, shows where the files are located, and indicates the intended scope of settings for each type.

Table 39-3 Intended scope of settings by configuration type

Type

Orientation

Location of file(s)

Intended scope of settings

General

Project-specific

Project directory

Current project only

Source-specific

d2g\documents or 
..\_config (parallel to 
project directory)

All or most outputs to be generated from a given DITA source document

Output-specific

d2g\local\config

All or most DITA source documents to be converted to a given output type

Specialization-specific

d2g\specializations\.
..

All DITA sources that include the specialization

DITA2Go-wide

d2g\local\config

All DITA2Go projects for all documents and outputs

Site-wide

common\local\config

All Omni Systems projects

Format

Output category

d2g\local\formats

All or most DITA source documents to be converted to a set of output types

Language

Usually universal

d2g\local\lang

All or most DITA source documents

Macro

Usually output-specific

d2g\local\macros

All or most outputs of a given output type or set of output types

Each configuration file in a \d2g\local subdirectory references an eponymous configuration template in a \d2g\system subdirectory that contains default settings. Do not edit those referenced templates, because they will be overwritten whenever you update DITA2Go. Instead, override settings in the corresponding \local configuration file.

Table 39-4 shows a sample hierarchy of configuration files for an HTML Help project, with the most widely applicable configuration at the top of the chain, and the most narrowly applicable (the project configuration file) at the bottom. With the exception of the document-specific configuration file (shown in green), each file in Table 39-4 references the file above it. The project configuration file at the bottom references both the document-specific file and the next configuration file above that.

Each configuration file in the chain can override settings in all those above it in Table 39-4. This is true even for a document-specific configuration file that does not reference any of the other configuration files, because it is treated as though it were right above the project configuration file. If a document-specific configuration file does reference other configuration files, DITA2Go treats all their settings as overruling any files above the project configuration file in the main chain.

Note:  Edit only the files shaded in blue or green; the others are system files.

Table 39-4 Chain of general configuration files for HTML Help output

Scope of settings

General configuration file

All Omni Systems projects

System:

%OMSYSHOME%\common\system\config\omsys.ini

Local site:

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

All DITA2Go projects

System:

%OMSYSHOME%\d2g\system\config\d2g_config.ini

Local site:

%OMSYSHOME%\d2g\local\config\local_d2g_config.ini

All HTML/XML projects

System:

%OMSYSHOME%\d2g\system\config\d2htm_config.ini

Local site:

%OMSYSHOME%\d2g\local\config\local_d2htm_config.ini

All Help projects

System:

%OMSYSHOME%\d2g\system\config\d2help_config.ini

Local site:

%OMSYSHOME%\d2g\local\config\local_d2help_config.ini

All HTML Help projects

System:

%OMSYSHOME%\d2g\system\config\d2htmlhelp_config.ini

Local site:

%OMSYSHOME%\d2g\local\config\local_d2htmlhelp_config.ini

All output types from this source document

..\_config\docname_document.ini (under source directory) -- or --
%OMSYSHOME%\d2g\documents\docname_document.ini

This project only

_d2htmlhelp.ini (in project directory)

General configuration settings

If you have just one DITA document to convert to a single output type, most general configuration settings can go in the project configuration file; see §39.4.2 Editing a project configuration file.

If you think you might want to produce other types of output from the same source document, settings that are the same for all output types (but that would be different for other source documents) can go in a document-specific configuration file; that way you avoid duplicating the settings in every project configuration file. See §39.4.3 Editing a document-specific configuration file.

If you have many DITA documents to convert to a single output type, settings that are specific to that output type and the same for every document (but that would be different for other output types) can go in the appropriate output-specific configuration file; see §39.4.4 Editing an output-specific configuration file.

Format configuration files

To override DITA2Go default format configuration settings, redefine output formats by adding the definitions you prefer to the appropriate output-oriented format configuration files in d2g\local\formats. See §39.4.5 Editing a format configuration file.

Language configuration files

To override DITA2Go default text values for the output language you wish to use, specify settings for alternate text in the appropriate language configuration file in d2g\local\lang. See §39.4.6 Editing a language configuration file.

Macro configuration files

You can add macros to editable source-specific, output-specific, or project configuration files, as needed. Or you can add them to a macro library configuration file in d2g\local\macros. See §39.4.7 Editing a macro configuration file.

Previous Topic:  39.4 Deciding which configuration file to edit

Next Topic:  39.4.2 Editing a project configuration file

Parent Topic:  39.4 Deciding which configuration file to edit

Sibling Topics:

39.4.2 Editing a project configuration file

39.4.3 Editing a document-specific configuration file

39.4.4 Editing an output-specific configuration file

39.4.5 Editing a format configuration file

39.4.6 Editing a language configuration file

39.4.7 Editing a macro configuration file

39.4.8 Indicating the intended scope of a configuration file