### 3.3 Understanding the rules for configuration settings

Every DITA2Go configuration file must begin with at least one line of header text, even if it is an empty line. The content of the line does not matter to DITA2Go, as long as it does not duplicate the name of a configuration section.

After the header text, each configuration file contains a series of sections. Each section consists of a section name in square brackets, followed by a list of settings of the form Key=Value or Key=Command, each on a separate line; and possibly by one or more comments:

    [Section]
    Key = Value
    Key = Value1 Value2 Value3 ...
    Key = Command
    ; Comment

The opening bracket for each section name must be in column 1.

Keep in mind these Microsoft rules for configuration files:

- Section names must be unique; if there are duplicate section names, only the first instance is processed.
- Key names must be unique in a section; if you repeat a key name, only the first instance is processed.

And these DITA2Go rules:

- The first line in the file must be a comment; DITA2Go requires a header line.
- No more than one space after the equals sign; otherwise, bad things can happen:
  - If the value is Boolean (Yes/No), DITA2Go treats it as No, even if you typed Yes.
  - If the value is a string, all spaces after the first are included in the string.

Consider all of the following:

Section names must be unique

Key names must be unique in a section

Key names must be valid ASCII

Key names are not case sensitive by default

Fixed-key sections differ from variable-key sections

Order of settings can be important for variable keys

Multiple values are separated by spaces

Spaces and tabs: some retained, some removed

Comments start with a semicolon

Boolean values can be expressed various ways

Section names must be unique

Section names must be unique. If you use the same section name twice in your configuration file, only the first section is processed. Otherwise, order of sections does not matter, except for macro sections (see §37.1.1.2 Understanding where you can define named macros).

Key names must be unique in a section

Each Key= setting in a given section must be the only setting for that key in that section. A common error is to add a setting to a section that already has a setting for that key. For example, any repeated lines assigning additional values to the same format name are ignored; only the first line is processed. Instead, place any additional values on the same line as the first, separated by spaces.

Key names must be valid ASCII

All ASCII characters are valid in key names, with the following exceptions:

- “?” and “*” are treated as wildcards, unless you turn off wildcard usage; see §4.1.10 Specifying how to treat cases, spaces, and wildcards. (However, when you override a configuration setting with a configuration variable, DITA2Go does not recognize wildcards in the key name; see §42.2.4 Assigning values to configuration variables.)
- “;” or “[” must be prefixed with escape character “\” if you want to start a key name with either of these characters.

Key names are not case sensitive by default

Comparisons of key names are caseless, unless you turn on case sensitivity; see §4.1.10 Specifying how to treat cases, spaces, and wildcards. (However, when you override a configuration setting with a configuration variable, the key name is case sensitive; see §42.2.4 Assigning values to configuration variables.)

Fixed-key sections differ from variable-key sections

Configuration files contain two kinds of sections: those with fixed keys (key names predefined by DITA2Go) and those with variable keys. For example, sections such as [HTMLOptions] and [WordOptions] are for settings with fixed key names; sections such as [HtmlStyles] and [HelpStyles] are for settings with key names you specify, typically names of formats assigned to DITA elements.

Order of settings can be important for variable keys

In a fixed-key section, the order of settings does not matter. Order is important only in sections where you can use variable keys, and usually only if you use wildcards in key names (see §3.5 Using wildcards in configuration settings).

Often the variable-key names you specify are names of formats assigned to DITA elements, such as paragraph, character, or table formats.

Multiple values are separated by spaces

Some variable-key sections allow multiple values for each key: sections such as [HtmlStyles], [WordStyles], and [HelpStyles], where you can assign multiple properties to each format. Use spaces between values.

Spaces and tabs: some retained, some removed

DITA2Go treats spaces and tabs in configuration settings as follows:

- Spaces and tabs before the Key and before the equals sign are ignored, unless [Options]SpacelessMatch=No, in which case those before the Key are not ignored (see §4.1.10 Specifying how to treat cases, spaces, and wildcards).
- If the equals sign is followed by one or more spaces or tabs, the first such space or tab is removed, and the rest are treated as part of the value. Put no more than one space after the equals sign. If you want to align settings vertically for readability, put extra spaces before the equals sign, not after.
- All spaces and tabs that follow a value are retained in the output.

Comments start with a semicolon

Lines that start with a semicolon “;” are comments. For a line to be treated as a comment, the semicolon must be the first character on the line (no leading blanks or tabs). DITA2Go pays no attention to comment lines; you can use them to add your own notes. However, do not try to “comment out” a section by inserting a “;” in front of the section name; all settings that follow such a line, up to the next line that starts with a “[”, would be added to the settings for the preceding section. To comment out a section, see §3.6 Commenting out configuration sections.

Boolean values can be expressed various ways

For an On/Off value, DITA2Go recognizes “1” (numeral one), “Yes”, and “True” as On, and “0” (zero), “No”, and “False” as Off.

Previous Topic: 3.2 Understanding where project settings come from

Next Topic: 3.4 Specifying file paths in configuration settings

Parent Topic: 3. Editing configuration files

Sibling Topics:

3.1 Working with DITA2Go configuration files

3.2 Understanding where project settings come from

3.4 Specifying file paths in configuration settings

3.5 Using wildcards in configuration settings

3.6 Commenting out configuration sections