README.adoc

dita-topic

dita-topic is a custom converter for Asciidoctor that converts a single AsciiDoc file to a corresponding DITA topic. To convert the produced DITA topic to a specialized DITA concept, reference, or task, use the dita_convert Python package.

Installation

Install the asciidoctor-dita-topic Ruby gem:

$ gem install asciidoctor-dita-topic

Usage

To use the custom converter on the command line, load it with the -r dita-topic option and then select dita-topic as the backend output format with -b dita-topic:

$ asciidoctor -r dita-topic -b dita-topic your_file.adoc

This creates a new file, your_file.dita, in the same directory as your_file.adoc. You can also convert multiple files at the same time:

$ asciidoctor -r dita-topic -b dita-topic *.adoc

Important

dita-topic does not validate the converted content. If you have DITA Open Toolkit installed, you can check that the converted file can be built as follows: $ dita -i converted_file.dita -f xhtml To produce slightly more readable errors, you can also use xmlstarlet: $ xmlstarlet val -e -s path_to_dita-ot_directory/plugins/org.oasis-open.dita.v1_3/schema-url/technicalContent/xsd/topic.xsd converted_file.dita

Supplying attribute definitions

If your AsciiDoc files use attributes that are defined outside of these files, you can supply the attribute definitions on the command line with the -a attribute=value option:

$ asciidoctor -r dita-topic -b dita-topic -a attribute=value your_file.adoc

You can provide multiple -a attribute=value options at the same time. Providing relevant attribute definitions is especially important if your document contains conditional content.

Example 1. Providing a product version to resolve ifeval conditions

Your AsciiDoc files include a number of ifeval statements that provide different content for different versions of the product you are documenting:

ifeval::["{ProductNumber}" == "1"]
...
endif::[]
ifeval::["{ProductNumber}" == "2"]
...
endif::[]

To ensure that the converted DITA files include all content for version 2 of your product, run:

$ asciidoctor -r dita-topic -b dita-topic -a ProductNumber=2 *.adoc

Disabling floating titles

Unlike AsciiDoc, DITA does not support floating titles and only allows titles to be assigned to a limited number of elements. To avoid losing content during the conversion, as a workaround, the dita-topic converter uses the following markup by default:

<p outputclass="title"><b>Floating title</b></p>

To disable this behavior, set the value of the dita-topic-titles to off:

$ asciidoctor -r dita-topic -b dita-topic -a dita-topic-titles=off your_file.adoc

Disabling callouts

Unlike AsciiDoc, DITA does not support callouts as a method to add annotations to specific lines in verbatim blocks. To avoid losing content during the conversion, as a workaround, the dita-topic converter uses XML entities for circled numbers.

To disable this behavior, set the value of the dita-topic-callouts to off:

$ asciidoctor -r dita-topic -b dita-topic -a dita-topic-callouts=off your_file.adoc

Disabling include directives

By default, Asciidoctor resolves all include directives before converting the file. To only convert the contents of the selected file, specify the -S secure option:

$ asciidoctor -r dita-topic -b dita-topic -S secure your_file.adoc

Warnings

Despite aspiring to avoid losing content during conversion and produce a valid DITA output, there are limitations to what is possible because of the differences between the two markup languages. When the dita-topic converter encounters a possible problem, it prints a warning to standard error output in the following format:

asciidoctor: WARNING: dita-topic: The warning message

This possible warning messages are as follows:

Admonition titles not supported in DITA	AsciiDoc allows you to add a custom title to any admonition by including .Admonition title on the line above it. Unlike AsciiDoc, DITA does not allow titles for admonitions. dita-topic issues this warning whenever an admonition has a title defined in the converted AsciiDoc file.
Audio macro not supported	AsciiDoc allows you to embed audio content in your documents by using the audio::audio_file[] macro. dita-topic does not implement this feature and issues this warning whenever the audio macro is present in the converted AsciiDoc file.
Block titles not supported in DITA	AsciiDoc allows you to include .Block title on the line above most of the block elements to assign a custom title to them. Unlike AsciiDoc, DITA only allows titles to be assigned to a limited number of elements. dita-topic issues this warning when the -a dita-topic-titles=off option is specified and a block title is present in the converted AsciiDoc file.
Callouts not supported in DITA	AsciiDoc allows you to use <1>, <2>, <3> and so on in verbatim blocks to add annotations to the specific lines. Unlike AsciiDoc, DITA does not provide a direct equivalent for this functionality. dita-topic issues this warning when the -a dita-topic-callouts=off option is specified and these annotations are present in the converted AsciiDoc file.
Floating titles not supported in DITA	AsciiDoc allows you to use floating titles anywhere in the document. Unlike AsciiDoc, DITA does not support floating titles. dita-topic issues this warning when the -a dita-topic-titles=off option is specified and a floating title is present in the converted AsciiDoc file.
Inline breaks not supported in DITA	AsciiDoc provides multiple ways to insert line breaks in paragraphs, such as inserting  + at the end of the line or specifying [%hardbreaks] on the line preceding the paragraph. Unlike AsciiDoc, DITA does not provide direct equivalent for this functionality. dita-topic issues this warning whenever an inline line break is present in the converted AsciiDoc file and places the <!-- break --> comment in the output file to mark its place.
Inline index terms not implemented	AsciiDoc allows you to define index terms within the text by using the indexterm2:[primary] and indexterm:[primary, secondary, tertiary] macros and their ((primary)) and (((primary, secondary, tertiary))) alternatives. dita-topic issues this warning whenever an index term is defined in the converted file, but as DITA does provide equivalent functionality, I intend to implement this feature in the upcoming release.
Nesting of sections not supported in DITA	AsciiDoc allows you to nest sections up to 5 levels deep. Unlike AsciiDoc, DITA does not allow the <section> elements to be nested. dita-topic issues a warning whenever nested sections are present in the converted AsciiDoc file.
Page breaks not supported in DITA	AsciiDoc allows you to use <<< on a separate line to enforce a page break in output formats that support it. Unlike AsciiDoc, DITA does not support page breaks. dita-topic issues this warning whenever a page break is present in the converted AsciiDoc file and places the <p outputclass="page-break"></p> in the output file to mark its place.
Possible invalid reference: reference	AsciiDoc allows you to cross reference by using an ID no matter if this ID is defined within or outside of the converted document. Unlike AsciiDoc, DITA requires both the target ID and the ID of the target topic to be included in the cross reference if the reference leads outside of the current file. As dita-topic is meant to be run on individual AsciiDoc files, it does not have access to information from referenced files during conversion. dita-topic issues this warning whenever a cross reference is present in the converted AsciiDoc file.
STEM support not implemented	AsciiDoc provides multiple ways to insert Science, Technology, Engineering and Math (STEM) expressions in the document, including the stem:[formula] inline macro and the [stem] delimited block. dita-topic does not implement this feature and issues this warning whenever such an expression is present in the converted AsciiDoc file.
Table footers not supported in DITA	AsciiDoc allows you to set the footer option to mark the last table row as a table footer. Unlike AsciiDoc, DITA does not support table footers. dita-topic issues this warning whenever a table footer is present in the converted AsciiDoc file.
Thematic breaks not supported in DITA	Asciidoc allows you to use ''', ---, or *** (the last two with possible optional spaces in between the characters) to insert a thematic break in between two blocks, most commonly represented by a horizontal line. Unlike AsciiDoc, DITA does not support thematic breaks. dita-topic issues this warning whenever a thematic break is present in the converted AsciiDoc file.
Video macro not supported	AsciiDoc allows you to embed video content in your documents by using the video::video_file[] macro. dita-topic does not implement this feature and issues this warning whenever the video macro is present in the converted AsciiDoc file.

Copyright

Copyright © 2024 Jaromir Hradilek

This program is free software, released under the terms of the MIT license. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.