#### 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:

- Starting project configuration file, copied by DITA2Go the DITA2Go Project Manager from %OMSYSHOME%\d2g\local\starts (or from %OMSYSHOME%\d2g\system\starts) to your project directory
- Document-specific configuration files in the document _config subdirectory; see §39.3.2 Deciding where to keep document-specific configuration files
- Specialization-supporting configuration files in subdirectories of %OMSYSHOME%\d2g\specializations
- Site-specific configuration file local_omsys.ini, located in %OMSYSHOME%\common\local\config.

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