Coding guidelines

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

Coding conventions

• Use soft-tabs (spaces) with a two-space indent.
  (They're the only way to guarantee code renders the same in any environment.)
• Nested elements should be indented once (two spaces).
• Keep lines fewer than 120 characters.
  (This prevents horizontal scrolling in GitHub edit & unified diff views.)
• Use UTF-8 encoding.
• Trim trailing white space on save.
• End each file with a blank newline.

Note: Most of these preferences are defined in the oXygen project file and an .editorconfig file, so if you use oXygen to edit the docs or a tool that supports the EditorConfig convention, your editor 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 <parmname> for the name of the parameter (and for DITA-OT extension points).
• Use <option> for the permissible values for the parameter.
• Use <option> for transformation types (output formats), as these are options passed to the transtype/--format parameter.

For example:

<cmdname>dita</cmdname> <parmname>--input</parmname>=<filepath>sequence.ditamap</filepath> \
                        <parmname>--format</parmname>=<option>html5</option>

Plug-ins

Use <codeph> or <filepath> for plug-in names. Rendering of both tags is currently identical in the distribution documentation output formats.

(Use <filepath> in cases where the plug-in folder is meant.)

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.