dita-ot/docs

DITA Open Toolkit documentation

DITA Open Toolkit Docs

This repository tracks the documentation source files for the DITA Open Toolkit project.

• Building the documentation output
• Building with development versions of DITA Open Toolkit
• Contribution guidelines
• Installing formatting tools
• Running Prettier

Building the documentation output

Note

The maps in this repository contain references to additional topics that are created at build time from the toolkit’s plug-in configuration.

To generate the missing topics and build the HTML and PDF versions of the documentation, run the Gradle build script from the root level of the docs repository and pass the path to your DITA-OT installation as a parameter.

Prerequisites

You must have a JRE and a local installation of DITA-OT. There is no need to download and install Gradle.

Steps

1. Open a command prompt, and change to the directory of your docs repository clone.

2. Type a variant of the following command for your operating system, adjust the path to your DITA-OT installation, and press Enter:

   • On Linux, macOS, or Git Bash, use ./gradlew:

     ./gradlew -PditaHome=/path/to/dita-ot
     

   • On Windows, use gradlew.bat:

     gradlew.bat -PditaHome=C:\path\to\dita-ot
     

Alternative: Using a DITA-OT repository clone

If you’re using a clone of the DITA-OT development repository as your toolkit installation alongside your clone of the docs repository:

1. In the root directory of your dita-ot repository, run Gradle to compile the Java code and install plugins.

   • On Linux, macOS, or Git Bash, use ./gradlew.
   • On Windows, use gradlew.bat.

2. Then run the Gradle build in the docs repository to generate topics and build the documentation output.

   • On Linux, macOS, or Git Bash, run the build script like this:

     ./gradlew -PditaHome=../dita-ot/src/main
     

   • On Windows, use gradlew.bat:

     gradlew.bat -PditaHome=C:\path\to\dita-ot\src\main
     

You can also specify a single output format. To build HTML for example, add html to the end of the command:

./gradlew -PditaHome=/path/to/dita-ot html

Results

If all goes well, you receive a "BUILD SUCCESSFUL" message, and the generated DITA topics are written to the extension-points and parameters directories in the out folder of the docs repository.

This folder is created automatically if it doesn’t exist. (Git ignores the contents so you don’t inadvertently commit these transient output files.)

Building with development versions of DITA Open Toolkit

The develop branch of the documentation repository may depend on features from recent development versions of DITA Open Toolkit.

To use these features when building the documentation, you may either download the latest development version of the distribution package, or clone the DITA-OT repository and install the bundled plug-ins via dita install.

Contribution guidelines

We welcome contributions to the DITA-OT documentation. Please review the guidelines for contributing to this repository before creating issues or opening pull requests.

For best results, follow the coding guidelines and best practices outlined in the docs project wiki:

• Test before committing
• Commit related changes
• Commit often
• Write good commit messages
• Sign your work

Installing formatting tools

The documentation repository uses the following JavaScript tools to keep source files consistently formatted:

• Prettier is an opinionated code formatter that enforces a consistent style by parsing code and re-printing it.
• Husky uses Git hooks to ensure that Prettier runs on all staged changes to format files before committing.

Prerequisites

• You must have a stand-alone installation of Git from git-scm.com/downloads.
• Include the Git installation location in the PATH environment variable.

Steps

To set these tools up:

1. Install Node.js® from nodejs.org
2. Open a command prompt, and change to the directory of your docs repository clone.
3. Run npm install

With these tools in place, any changes you make to the documentation source files will be automatically formatted when you commit them with Git. This ensures that commits contain only related changes, and no extra formatting.

Troubleshooting

If the git command is not available in your command-line environment, the Husky installation may fail with an error message:

"Cannot read property 'toString' of null"

Solution: Uninstall Husky via npm husky uninstall. Install Git. Add the installation location to the PATH environment variable. Re-run npm install.

Running Prettier

If you'd like to check whether your changes are formatted correctly, or format them before committing, you can run Prettier manually from the command line.

Check formatting

npm run check

Format all files

npm run format

docs's Issues

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).

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

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.

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.

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).

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.

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.

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.

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.

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.

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.

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.

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

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.

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 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.

Add information on building `docs` to ReadMe

Pending modifications to build scripts in #3.

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.

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.

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?

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.

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.

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.

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.

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.

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.

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

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 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.

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.

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.

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

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 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"/>

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.

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.

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.

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.

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

Update "gen-list" topic in docs

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

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.

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.

Remove documentation for the old command line tool

See dita-ot/dita-ot#1800

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).

Index the topics

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.

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.

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.

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.

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.