Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/jhradilek/asciidoctor-dita-topic

An AsciiDoc converter that generates individual DITA 1.3 topics
https://github.com/jhradilek/asciidoctor-dita-topic

asciidoc asciidoctor asciidoctor-extension dita dita-ot

Last synced: 12 months ago
JSON representation

An AsciiDoc converter that generates individual DITA 1.3 topics

Awesome Lists containing this project

README 

          
= dita-topic



`dita-topic` is a custom converter for Asciidoctor that converts a single AsciiDoc file to a corresponding DITA 1.3 topic.



In combination with link:https://github.com/jhradilek/asciidoctor-dita-vale[asciidoctor-dita-vale] and link:https://github.com/jhradilek/dita-custom-xslt#installation[dita-convert], this project can be used to rapidly convert AsciiDoc content to DITA:



. Identify incompatible markup in the AsciiDoc source file:

+

[literal,subs="+quotes"]

....

$ *vale source_file.adoc*

....



. Convert the AsciiDoc file to a generic DITA topic:

+

[literal,subs="+quotes"]

....

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

....



. Convert the generic DITA topic to a specialized DITA concept, reference, or task:

+

[literal,subs="+quotes"]

....

$ *dita-convert -gt task source_file.dita*

....



[#install]

== Installation



Install the `asciidoctor-dita-topic` Ruby gem:



[literal,subs="+quotes"]

....

$ *gem install asciidoctor-dita-topic*

....



[#use]

== 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`:



[literal,subs="+quotes"]

....

$ *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:



[literal,subs="+quotes"]

....

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

....



[IMPORTANT]

====

`dita-topic` does not validate the converted content. If you have link:https://www.dita-ot.org/[DITA Open Toolkit] installed, you can check that the converted file can be built as follows:



[literal,subs="+quotes"]

....

$ **dita -i _converted_file_.dita -f xhtml**

....



To produce slightly more readable errors, you can also use `xmlstarlet`:



[literal,subs="+quotes"]

....

$ **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**

....

====



[#attributes]

=== 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:



[literal,subs="+quotes"]

....

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



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



[source]

----

\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:



[literal,subs="+quotes"]

....

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

....

====



[#authors]

=== Enabling author lines



AsciiDoc topics are expected to be included in other files and therefore should not contain link:https://docs.asciidoctor.org/asciidoc/latest/document/author-line/[author line] definitions. In most cases, lines that directly follow the topic title are intended as first paragraphs. For this reason, author lines are disabled by default. To avoid losing content during conversion, as a workaround, the `dita-topic` converter interprets the raw content of the author line as a paragraph and issues a warning.



To enable processing of author lines as metadata, set the value of the `dita-topic-authors` to `on`:



[literal,subs="+quotes"]

....

$ **asciidoctor -r dita-topic -b dita-topic -a dita-topic-authors=on _your_file_.adoc**

....



[#titles]

=== 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 conversion, as a workaround, the `dita-topic` converter uses the following markup by default:



[source,xml]

----

Floating title


----



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



[literal,subs="+quotes"]

....

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

....



[#callouts]

=== 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 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`:



[literal,subs="+quotes"]

....

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

....



[#includes]

=== 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:



[literal,subs="+quotes"]

....

$ **asciidoctor -r dita-topic -b dita-topic -S secure _your_file_.adoc**

....



[#abstracts]

=== Adding short descriptions



DITA provides the `` element which allows the user to describe the purpose of the topic and is often used as preview text in search results. To replicate this behavior, the `dita-topic` converter recognizes a paragraph preceded by the `[role="_abstract"]` attribute list and adds the `outputclass="abstract"` attribute to it. The link:https://github.com/jhradilek/dita-custom-xslt#installation[dita-convert Python package] transforms such a paragraph to `` during conversion to a specialized DITA concept, reference, or task.



For example, to designate a paragraph as a short description, use the following AsciiDoc markup:



[source,asciidoc]

----

[id="topic-id"]

= Procedure title



[role="_abstract"]

A short description of the procedure module and what it helps the

user accomplish.



An introductory paragraph.

----



[#semantics]

=== Adding semantic markup



Unlike AsciiDoc, DITA provides a number of semantic elements for software components such as file names, commands, or command-line options. To replicate this behavior, the `dita-topic` converter recognizes the following link:https://docs.asciidoctor.org/asciidoc/latest/attributes/role/#assign-roles-to-formatted-inline-elements[roles] assigned to monospace (```) inline text:



[cols="1,1"]

|===

| AsciiDoc Role

| DITA Element



| command

| ``



| directory

| ``



| filename

| ``



| option

| ``



| variable

| ``

|===



For example, to describe a file name, use the following AsciiDoc markup:



[source,asciidoc]

----

Read the [filename]`/etc/passwd` file to see the complete list of

available user accounts.

----



[#warnings]

== 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:



[literal,subs="+quotes"]

....

asciidoctor: WARNING: dita-topic: _The warning message_

....



This possible warning messages are as follows:



[horizontal]

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.



Author lines not enabled for topics:: AsciiDoc interprets the first line that directly follows the document title as an author line. Because topics are not expected to have author lines, `dita-topic` issues this warning when an author line 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.



Examples not supported within _object_ in DITA:: AsciiDoc allows you to use an example block anywhere in the document. Unlike AsciiDoc, DITA only allows examples to appear directly in the topic body. `dita-topic` issues a warning whenever an example is nested in another AsciiDoc element.



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 `{nbsp}+` 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 `