dita-ot / docs

DITA Open Toolkit documentation

DITA Open Toolkit

DITA Open Toolkit, or DITA-OT for short, is an open-source publishing engine for content authored in the Darwin Information Typing Architecture.

Visit the project website at dita-ot.org for documentation, information about releases, and download packages.

For information on additional DITA and DITA-OT resources, see SUPPORT. To report a bug or suggest a feature, create an issue. For more information on how you can help contribute to the project, see CONTRIBUTING.

• Prerequisites: Java 17
• Installing
• Building output
• Development
  • Running tests
  • Formatting code
  • Distribution builds
• License

Prerequisites: Java 17

To build and run DITA-OT, you’ll need Java Development Kit (JDK), version 17 or newer.

You can download the OpenJDK from AdoptOpenJDK.

Installing

1. Download the distribution package from dita-ot.org/download.
2. Extract the contents of the package to the directory where you want to install DITA-OT.

Installing via Homebrew

On macOS and Linux, you can also install DITA-OT using the Homebrew package manager:

brew install dita-ot

Homebrew will automatically download the latest version of the toolkit, install it in a subfolder of the local package Cellar and symlink the dita command to the bin subfolder of the Homebrew installation directory.

Note

Homebrew’s default installation location depends on the operating system architecture:

• /usr/local on macOS Intel
• /opt/homebrew on macOS ARM
• /home/linuxbrew/.linuxbrew on Linux

Building output

You can generate output using the dita command-line tool included with DITA Open Toolkit.

1. On the command line, change to the bin folder of the DITA-OT installation directory:

   cd path/to/dita-ot-dir/bin

2. Run the dita command to generate output:

   dita --input=input-file --format=format [options]

   where:

   • input-file is the DITA map or DITA file that you want to process
   • format is the output format (or “transformation type”)

See the documentation for arguments and options.

Development

Building the toolkit from source code and compiling the distribution package

1. Clone the DITA-OT Git repository, including submodules:

   git clone --recurse-submodules git://github.com/dita-ot/dita-ot.git

2. Change to the DITA-OT directory:

   cd dita-ot

3. In the root directory, run Gradle to compile the Java code and install plugins:

   ./gradlew

Running tests

./gradlew check

All tests are run by GitHub Actions test workflow on each push and for every pull request.

Formatting code

Requirements:

• Node.js

Prettier is used retain consistent Java formatting.

1. Run Prettier:

   npm run fmt

Distribution builds

1. In the root directory, set up the build environment:

   ./gradlew

2. Build the distribution packages:

   ./gradlew dist

   Distribution packages are built in the build/distributions directory.

   If Gradle throws an error like java.lang.OutOfMemoryError: Java heap space, you probably need to increase the maximum Java heap size. One way to do this is to set the GRADLE_OPTS environment variable to a value like -Xmx1024m.

   For more information on the -Xmx option, see the Java SE Documentation.

License

DITA Open Toolkit is licensed for use under the Apache License 2.0.

docs's Issues

Add section on Migrating Customizations

Since recent versions of the documentation no longer include an archive of the Release Notes from prior releases, there is no single source of information on the changes required to port earlier customizations to recent toolkit versions.

To facilitate and encourage upgrades, the Developer Reference should include a dedicated section on Migrating Customizations with the migration-related information from the Release Notes of recent releases.

This information is available for v1.5.4 onward, and will be added for v2.0 for #29.

Error in "Building output using Ant" topic

Refers to the startcmd.bat and startcmd.sh files that are no longer shipped with the DITA-OT.

Topic about how to contribute a new language to the DITA OT

There seems to be a topic on globalizing the DITA OT:

http://www.dita-ot.org/2.0/readme/DITA-globalization.html

But it does not seem to say anything about how to contribute new translations as a plugin for example.

We probably need to have separate explanations for the PDF processing and for the other transformations.

Based on this question on the DITA Users List:

https://groups.yahoo.com/neo/groups/dita-users/conversations/messages/37719

    I am currently adding a few languages to my documentation set. 
     Some of these languages are not supported by my DITAOT. 
      Does anyone know if there are resources that can allow me to add more languages?

Remove documentation for the old command line tool

See dita-ot/dita-ot#1800

Remove references to obsolete distribution packages

After consolidation of distribution packages for dita-ot/dita-ot#1914, references to the obsolete standard and minimal distribution packages should be removed from the documentation.

Remaining references to the client package should be verified & simplified accordingly.

New doc topic: changes during preprocess

The DITA-OT preprocess adds several items that later rendering steps can make use of, and which might change the content to be not-quite-pure DITA. This can simplify the shipped rendering in many ways, such as eliminating any need to process a DITAVAL file to support flagging.

We should document these changes so that developers of new transform types are aware of them. This lets them take advantage of the updates, and also lets them know what has changed that might not be "pure DITA".

I don't think we need to list all of the stuff that is already covered / assumed, such as "conref is resolved". Offhand the things I know of that we need to document are:

• Processing instructions added by "topicpull" when text is pulled into a link or xref element. This lets later steps distinguish between generated text and authored text. Authored text should always be preserved, but a rendering step may want to change the format of generated text; for example, PDF processing replaces generated "Figure N" text with a different figure number and possibly with a page number.
• Flagging information is added using pseudo-foreign specializations (this may already be documented in the flagging documentation?)

Also considering an update that would add things like @dita-ot:href in this newly opened issue; if we move forward it would need to be documented as well: dita-ot/dita-ot#1837

Add args.xhtml.toc.xsl to "Ant parameters: Common HTML-based transformations"

The Ant parameter args.xhtml.toc.xsl is missing from the docs. It specifies a custom XSLT file to use for the TOC (index.html).

Expand extension point descriptions

A topic with a list of all extension points is now generated automatically when the documentation build process runs.

The extension point descriptions are generated from the name attribute of each <extension-point> element in the plugin.xml configuration file for each plugin.

The conref mechanism should be used to expand or override the descriptions for the default toolkit plugins as used for the generated parameter listings and messages topics.

Create Gradle build file for docs

Now that the main DITA-OT repo uses Gradle to build, we should prepare a build.gradle file for docs to employ the DITA Open Toolkit Gradle Plugin for better performance, incremental builds and continuous builds via the Gradle Daemon.

This solution would facilitate local testing by rebuilding docs whenever source files change, and could also serve as a foundation for continuous integration of changes to Development docs on the project website at www.dita-ot.org/dev per dita-ot/website#9.

NOTE: To prevent code duplication and still allow users that don't have Gradle to build the docs, it might be best if the build.gradle file could call the existing Ant build file, or re-use the targets it defines.

Document PDF2 interpretation of the DITAVAL @changebar attribute

The PDF2 transform handles a special syntax for the @changebar attribute in order to generate revision bars with FO when it is supported (AHF, XEP). This appears to be undocumented. I will document it.

Document additional configuration properties

@georgebina reported:

The documentation for the configuration.properties file lists a few properties but from Configuration.java it looks like there are also entries like print_transtypes, plugin.[name].dir and parser.[format]=[value]

The existing topics in the Configuration properties section of the Parameter Reference should be updated to cover the missing properties, explain how properties files are used internally by the toolkit, and clarify the difference between configuration properties and argument properties that users can set at transformation time.

We should also consider extending this section to cover not only configuration properties, but also include information on how users can use property files to specify transformation parameters by passing a property file as an argument to the dita command:

dita -propertyfile file

Load all properties from a file. Properties specified with the -D option take precedence.

Add troff extension points to developer docs

As part of other updates to troff, I've declared extension points that let the troff XSL accept overrides like any other XSL output. They should be added to this topic:
http://www.dita-ot.org/2.0/dev_ref/plugin-overridestyle.html

Specifically:
"dita.xsl.troff-ast" Overrides the intermediate block-and-phrase format generated as input to troff processing.
"dita.xsl.troff" Overrides the XSL that converts block-and-phrase intermediate markup into troff.

For example, for my own domain, I'd add this extension to get formatting tweaks into the intermediate format:

    <feature extension="dita.xsl.troff-ast" file="xsl/our-domain.xsl"/>

Consider documenting hidden parameters like "include.rellinks"

Based on: dita-ot/dita-ot#1887

The official parameter for controlling related links generation is "args.rellinks". But some people who publish output might want a more precise way of controlling the generated links by setting directly the parameter "include.rellinks" which specifies in clear what types of links are allowed for generation.

plugin.xml <transtype> element not documented

It looks like the element in plugin.xml is not documented on this page:

https://github.com/dita-ot/docs/blob/develop/dev_ref/plugin-configfile.dita

An example of this element is here:

https://github.com/oxygenxml/dita-css/blob/master/com.oxygenxml.pdf.css/plugin.xml

Thanks,
Mark

Add info on migrating to v2.x

To assist users in migrating from OT v1.x to v2.x, the documentation should include an overview of the types of changes required to update existing projects for use with v2.0.

Topics may include:

• Changes in Ant target names
• Deprecated XSLT templates
• Updating existing Ant build scripts
• Configuration via properties files vs. environment variables, $DITA_HOME, etc.

Separate topics should be created with migration info for each 2.x release:

• 2.0
• 2.1
• 2.2
• 2.3

Update documentation for plugins.xml

In dita-ot/website#7, @liujason writes:

It seems there are a few elements in plugins.xml are updated.
For example, the http://www.dita-ot.org/2.1/dev_ref/plugin-newtranstype.html seems out dated. In plugins/org.dita.xhtml/plugin.xml, there's a new element, with elements underneath. I can't find any documentation on how they are used.

Commit 864dad6 extends the Plug-in configuration file topic with a description of the new <transtype> element and provides an example, but further information may be necessary.

Add info on migrating PDF customization folders to plugins

User-defined customizations in the org.dita.pdf2/Customization directory or custom locations specified via the customization.dir parameter should be migrated to custom PDF plugins.

Add a topic that describes the differences between the customization folder approach and plugins, and the changes required to port customization folders to plugins.

Use <coderef> for sample files

Live code references should be used for sample files wherever possible to ensure that examples are updated automatically.

This would also facilitate testing, as the code samples for things like Ant scripts could be run directly to verify they work as intended.

Multiple documentation issues in: Modifying or adding generated text

The page Modifying or adding generated text contains multiple documentation errors.

For example, the files previously living in xsl\common have moved to cfg\common\vars. Further on, some file names have changed. I didn't check the whole page yet. Is anybody working on this? Otherwise I'd send you a pull request.

Create oXygen project for `docs` repo

Since many contributors use oXygen, a project file should be added to store common settings like line width, etc.

Transformation scenarios and/or external tool scripts can be used to build output by calling the project build scripts from the oXygen UI.

Add information on building `docs` to ReadMe

Pending modifications to build scripts in #3.

Standardize references to HTML transformation types

The documentation currently refers to HTML-based transformation types in different ways, sometimes using the generic "HTML" form, while in other places mentioning specific flavors XHTML and HTML5.

These occurrences should be reviewed to use the generic "HTML" form where all HTML-based transformations are implied, and only mention XHTML or HTML5 where the implementation details are relevant.

Certain extension points are not explained anywhere

For example all the extension points in the pdf2 plugin:

<extension-point id="org.dita.pdf2.xsl.topicmerge" name="PDF2 topic merge XSLT import"/>
<extension-point id="depend.org.dita.pdf2.format.pre" name="Formatting pre-target"/>
<extension-point id="depend.org.dita.pdf2.format" name="Formatting target"/>
<extension-point id="depend.org.dita.pdf2.format.post" name="Formatting post-target"/>
<extension-point id="org.dita.pdf2.catalog.relative" name="Configuration XML catalog"/>
<extension-point id="dita.conductor.pdf2.param" name="PDF XSLT parameters"/>

I cannot find them anywhere in the docs. Actually I cannot find in the docs a list with all extension points anymore.

Move generate-debug-attributes and processing-mode configuration to runtime properties

dita-ot/dita-ot/issues/1799 changes generate-debug-attributes and processing-mode configuration options to be runtime properties; there is no change in functionality on either property.

Refactor build scripts

After separating the docs repository from the parent dita-ot repository, build scripts should be refactored to reduce dependencies on the main repo to ensure that new contributors can just clone docs and build documentation output without cloning the the parent dita-ot repository.

Standardize indentation & line widths

Format & indent current source files for readability.

Hard-wrap lines @ 120 characters to avoid horizontal scrolling in GitHub's edit & unified diff views

Update Plugins topics

Kris provided updated versions of the topics in the plug-in section of the Developer Reference in response to #20.

This work-in-progress should be merged with the latest versions of the topics.

Remove links to developerWorks articles

The PDF version of the User Guide contains an appendix with links to the old IBM developerWorks articles, but the URLs have since changed, so all the old links currently redirect to the IBM home page.

We should either update the links to point to new URLs (if available) or remove the topic entirely. The topic no longer appears any of the HTML-based output formats.

Confirmed w/ @robander during 2015-02-03 contributor call: remove topic, since these articles were written for early versions of DITA, and best practices have evolved significantly since then.

Add Tutorials section

The OT docs should be extended with a dedicated Tutorials section that guides the reader through common use cases for new toolkit users, such as:

• Building output with the dita command
• Running dita builds with scripts
• Creating an Ant build script
• Customizing PDF output
• Adding custom branding to HTML output
• Publishing draft output with comments
• Highlighting revised content
• Creating plugins to override stylesheets & document type shells
• Best practices for plugin development

Several similar topics are currently available elsewhere in the docs (checked in the list above), but a dedicated Tutorials section would make them easier to find and provide a more task-oriented approach to learning.

For those familiar with earlier toolkit releases, tutorials could also serve to illustrate new approaches in recent toolkit versions, such as:

• Setting DITA-OT parameters with .properties files
• Embedding DITA-OT in other programs
• Installing and removing plugins

Please add comments below to suggest additional topics.

Remove obsolete unreferenced files

The docs subrepository currently contains many obsolete files that are no longer referenced in recent versions of the documentation. Most are remnants of earlier documentation releases that no longer apply to the current toolkit distributions and can be safely removed.

Unreferenced content may be preserved if useful as a basis for new topics, but should probably be moved to a dedicated subdirectory.

Update "gen-list" topic in docs

Topic describes what lists are generated, and is out of date for 2.0. [Noticed by Kris, thanks!]

Revise documentation landing page

The landing page that serves as the introduction to the toolkit docs should provide an overview of the documentation structure rather than duplicating information from the project home page www.dita-ot.org.

The page should provide a direct link to the latest release notes and pull in the short descriptions from each of the documentation parts that appear in the top level of the site navigation (ToC).

Extend Specification Support section

Create a new DITA Specification Support section with two children:

• Current DITA 1.2 Support topic
• New DITA 1.3 Support topic

1.3 Support topic should provide an overview of supported 1.3 features.

Consider including status of planned feature support w/ links to related issues per @raducoravu's suggestion.

Redo graphic in Developer Reference

The mainarch.gif diagram in the Processing structure topic should be updated to reflect recent changes to the toolkit architecture and prepared in a format such as SVG to ensure optimum quality in all docs output formats.

An editable source file for the diagram should be added to the repository to facilitate future updates.

The docs should link to the DITA generator

The DITA generator is the starting point to create a specialization or a PDF plugin. Starters waste a lot of time (trust me) when trying to write a specialization or a PDF plugin the first time, because there is only little information out there, e.g. Eliots DITA Configuration and Specialization Tutorials.

Update “Tested platforms and tools”

On 2016-01-2, at 13:08 CET, @xephon2 wrote:

Is Tested platforms and tools up to date?
The test environment still covers Windows XP but no Windows 10?

Several of the operating systems and other listed tools are a bit dated.

We need to review the list, prune older versions we no longer intend to support, and add latest supported versions.

Add tips on reducing processing time

Based on http://jelovirt.github.io/2013/11/25/reducing-processing-time.html per @jelovirt's suggestion.

Consider adding as subsection of Configuring the DITA Open Toolkit.

Move Contribution Guidelines to dedicated file

The contribution guidelines outlined in the README should be moved to a CONTRIBUTING.md file in the root of the repository to display a banner when a contributor creates an Issue or opens a Pull Request.

See https://github.com/blog/1184-contributing-guidelines.

Update references to DITA 1.3 spec

After the approval of DITA 1.3 as an OASIS standard, links to the spec should be updated to point to the final standard documents once these are published by the TC.

Existing text references should be reviewed and revised to reflect the final approved standard status.

Update Implementation dependent features for DITA 1.3

On Wednesday, 2015-09-02, at 16:30 CEST, @jelovirt wrote:

We will probably need to update http://www.dita-ot.org/dev/dev_ref/DITA1.2-implementation-dependent-features.html to fill in how we implement DITA 1.3

Basically, we’d need to go though the 1.3 spec and find all places that state that an implementation MAY do X. Then just list what we do.

Add topic(s) on DITA features used in docs

The docs should be extended with a dedicated topic or set of topics that describes how the DITA-OT documentation uses certain DITA and DITA-OT features, such as:

• profiling and filtering
• keys and key references
• subjectScheme classification for controlling available attributes
• automatic generation of topic files based on the content of installed plug-ins
• conref push to inject additional descriptions into generated topics for messages, parameters & extension points

Wherever possible, these topics should use <coderef> elements to link directly to live source files rather than copying code (see #49).

Troubleshooting builds

I think we need a set of topics helping users understand how to use the logs to identify and troubleshoot build problems. This should follow the tutorial approach outlined in #37.

Add books to “DITA Resources” section

A topic that lists books about DITA and the DITA-OT should be added to the DITA and DITA-OT Resources section.

Restore missing JavaHelp transform description

The JavaHelp transformation is missing from the list of available transformations in publishing.ditamap, though the topic itself exists and is referenced in reltable.ditamap.

Index the topics

Add/update license comments in `docs` source files

Many files in the docs subrepository do not contain any reference to the project's license.

Others contain comments that still refer to SourceForge hosting or a license.txt file that is not present in the repository. Update files to point to the current license file LICENSE.md.

Add topic on chunking considerations

Include link to chunking info in the implementation dependent features topic with additional information on pros, cons, side effects & any caveats w/r/t the DITA-OT implementation of chunking.

The focus here should be on specific considerations related to how DITA-OT handles chunking, as more general DITA best practices tutorials are beyond the scope of the OT docs.

Fix links to latest stable release

Several locations in the documentation still point to the SourceForge site.

Replace links to http://sourceforge.net/projects/dita-ot/files/DITA-OT%20Stable%20Release [...] with https://github.com/dita-ot/dita-ot/releases/tag/2.0

Error in "Building output using the dita command"

In the example section, the path to sequence.ditamap is wrong. It should be ../samples/sequence.ditamap

Mention plugin.rnc in the docs

There is a Relax NG schema (plugin.rnc) that can be used to validate plugin.xml files. This schema should be mentioned in the Plug-in configuration file topic.