Coding guidelines

Please follow these guidelines when contributing changes to the DITA Open Toolkit docs.

Coding conventions

• Use soft-tabs with a two space indent.
• Keep lines fewer than 120 characters.
  (This prevents horizontal scrolling in GitHub edit & unified diff views.)
• Never leave trailing whitespace.
• End each file with a blank newline.
• Use UTF-8 encoding.

Note: These preferences are defined in the oXygen project file, so if you use oXygen to edit the docs, the tool should do the right thing.

Terminology

The abbreviation for DITA Open Toolkit is “DITA-OT”, not DITA OT.

The options for the DITA-OT transformations are called “parameters”, not properties or arguments.

In earlier toolkit releases, the full distribution package was called the “full-easy-install package”. Recent toolkit releases provide a single distribution package, with a .tar.gz compressed version for UNIX-based operating systems and a .zip package for Windows.

Download the distribution package for your operating system from the project website at www.dita-ot.org.

DITA-OT output formats are called “transformation types”. Avoid abbreviating to “transtype” or “transform type” unless explicitly referring to elements or attributes by name:

The <transtype> element defines an output format (transformation type).

Tagging

DITA-OT parameters

Use <paramname> for the name of the parameter.

Use <option> for the permissable values for the parameter.

Transformation types (output formats)

Use <option> for transformation types, as these are options passed to the transtype parameter.

Ant targets

Use <codeph> for Ant target names (as in processing modules topics).

(Pre)processing modules/steps

Use <codeph>.

DITA-OT error messages

Use <msgnum>.

Style guidelines

Use the IBM Style Guide.

Information architecture

Indexing

Do not index container topics.