asciidoctor-dita-topic 1.0.8 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 073b164893413640198b0938df78f0b180a4a25366a34bee47cf85585efddd51
-  data.tar.gz: 75b381d82f68f838a237b666fe8a38929dbc99101f0024086888d83a4c59471a
+  metadata.gz: 134df897545adafba05f060ea22079c3fa927204b47fff2eec8ffbc8ae5ef84a
+  data.tar.gz: 354b8abadd320b9a4c63b3c170a85974a2231836da07851e1cde58da06aafff3
 SHA512:
-  metadata.gz: f1b4cf1080f6ab776de1d62c122f89c190f68d03836bd3a41e2612c4b673ab97e2947abab161f9f4c1f976acddc9a41acf9ffcbdbfd7308a4c0e1bc64da87e17
-  data.tar.gz: 9acb585946816133087779410d66279ec4567118a3ed14a9ec318c353a647e50dcb5ee46adf835bfa9a94a511b0a8ec772e49fe224bac042946021ad902c5902
+  metadata.gz: 4b7e9fcd688f450a2e05effca4c30d5969db15d7056cd23b6c1829d6f65de79cc95e0208f5dc543b5bd2f87117aa972f49dcff76963ef8b67879f5a40a97af6f
+  data.tar.gz: 05122aac651d614082cc4cb350197bdbb897d2b7436189eb225a230ffc3f8ad2f3ee5d66f1b882f78bab39d4fd38d18caaeba0d1b5dd965c98ccd7f52a530f97

data/AUTHORS

@@ -0,0 +1 @@
+Jaromir Hradilek <jhradilek@gmail.com>

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright (C) 2024, 2025 Jaromir Hradilek
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

data/README.adoc

@@ -0,0 +1,180 @@
+= 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 link:https://github.com/jhradilek/dita-custom-xslt[dita_convert Python package].
+
+[#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]
+----
+<p outputclass="title"><b>Floating title</b></p>
+----
+
+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**
+....
+
+[#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.
+
+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.
+
+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.
+
+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 `<!-- break -\->` comment in the output file to mark its place.
+
+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
+
+Copyright (C) 2024, 2025 Jaromir Hradilek
+
+This program is free software, released under the terms of the link:LICENSE[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.

data/lib/dita-topic.rb

@@ -1,5 +1,5 @@
 # A custom AsciiDoc converter that generates individual DITA topics
-# Copyright (C) 2024 Jaromir Hradilek
+# Copyright (C) 2024, 2025 Jaromir Hradilek
 
 # MIT License
 #
@@ -33,34 +33,70 @@ class DitaTopic < Asciidoctor::Converter::Base
     super
     outfilesuffix '.dita'
 
-    # Enable floating and block titles by default:
-    @titles_allowed = true
+    # Disable the author line by default:
+    @authors_allowed = false
 
     # Enable callouts by default:
     @callouts_allowed = true
+
+    # Enable floating and block titles by default:
+    @titles_allowed = true
   end
 
   def convert_document node
-    # Check if floating and block titles are enabled:
-    @titles_allowed = false if (node.attr 'dita-topic-titles') == 'off'
+    # Check if the author line is enabled:
+    @authors_allowed = true if (node.attr 'dita-topic-authors') == 'on'
 
     # Check if callouts are enabled:
     @callouts_allowed = false if (node.attr 'dita-topic-callouts') == 'off'
 
+    # Check if floating and block titles are enabled:
+    @titles_allowed = false if (node.attr 'dita-topic-titles') == 'off'
+
     # Check if the modular documentation content type is specified:
-    outputclass = (node.attr? '_mod-docs-content-type') ? %( outputclass="#{(node.attr '_mod-docs-content-type').downcase}") : ''
+    outputclass = ''
+    outputclass = %( outputclass="#{(node.attr '_content-type').downcase}") if node.attr? '_content-type'
+    outputclass = %( outputclass="#{(node.attr '_mod-docs-content-type').downcase}") if node.attr? '_mod-docs-content-type'
+
+    # Open the document:
+    result = ["<?xml version='1.0' encoding='utf-8' ?>"]
+    result << %(<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">)
+    result << %(<topic#{compose_id (node.id or node.attributes['docname'])}#{outputclass}>)
+    result << %(<title>#{node.doctitle}</title>)
+
+    # Check if the author line is enabled and defined:
+    if @authors_allowed && !node.authors.empty?
+      # Open the prolog:
+      result << %(<prolog>)
+
+      # Process individual author names:
+      node.authors.each do |author|
+        result << %(<author>#{compose_author author, node}</author>)
+      end
+
+      # Close the prolog:
+      result << %(</prolog>)
+    end
+
+    # Open the document body:
+    result << %(<body>)
+
+    # Check if the author line defined while disabled:
+    if !@authors_allowed && !node.authors.empty?
+      # Issue a warning as inline content is not going to be processed:
+      logger.warn "#{NAME}: Author lines not enabled for topics"
+
+      # Process the author line as a plain paragraph:
+      result << %(<p>#{node.authors.map {|author| compose_author author, node}.join('; ')}</p>)
+    end
+
+    # Close the document body:
+    result << node.content
+    result << %(</body>)
+    result << %(</topic>)
 
     # Return the XML output:
-    <<~EOF.chomp
-    <?xml version='1.0' encoding='utf-8' ?>
-    <!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
-    <topic#{compose_id (node.id or node.attributes['docname'])}#{outputclass}>
-    <title>#{node.doctitle}</title>
-    <body>
-    #{node.content}
-    </body>
-    </topic>
-    EOF
+    result.join LF
   end
 
   def convert_admonition node
@@ -319,9 +355,23 @@ class DitaTopic < Asciidoctor::Converter::Base
   end
 
   def convert_inline_indexterm node
-    # Issue a warning if an inline index term is present:
-    logger.warn "#{NAME}: Inline index terms not implemented"
-    return ''
+    # Check if the index term appears in the flow of the text:
+    if node.type == :visible
+      return %(<indexterm>#{node.text}</indexterm>#{node.text})
+    end
+
+    # Get primary, secondary, and tertiary index terms:
+    terms = node.attr 'terms'
+
+    # Determine the number of terms:
+    case terms.size
+    when 1
+      %(<indexterm>#{terms[0]}</indexterm>)
+    when 2
+      %(<indexterm>#{terms[0]}<indexterm>#{terms[1]}</indexterm></indexterm>)
+    else
+      %(<indexterm>#{terms[0]}<indexterm>#{terms[1]}<indexterm>#{terms[2]}</indexterm></indexterm></indexterm>)
+    end
   end
 
   def convert_inline_kbd node
@@ -420,9 +470,24 @@ class DitaTopic < Asciidoctor::Converter::Base
     add_block_title (result.join LF), node.title
   end
 
-  # FIXME: This is not the top priority.
   def convert_open node
-    ''
+    # NOTE: Although DITA provides an <abstract> element that is intended
+    # for this purpose, it is placed alongside the <body> element and not
+    # inside of ot. As there is no clean way to place it there, I use
+    # a workaround.
+
+    # Determine the node type:
+    if node.style == 'partintro'
+      node.content
+    elsif node.content_model == :compound
+      <<~EOF.chomp
+      <div#{(node.style == 'abstract') ? ' outputclass="abstract"' : ''}>
+      #{compose_floating_title node.title}#{node.content}
+      </div>
+      EOF
+    else
+      %(#{compose_floating_title node.title}<p#{(node.style == 'abstract') ? ' outputclass="abstract"' : ''}>#{node.content}</p>)
+    end
   end
 
   def convert_page_break node
@@ -773,6 +838,12 @@ class DitaTopic < Asciidoctor::Converter::Base
     EOF
   end
 
+  def compose_author author, node
+    name = node.sub_replacements author.name
+    mail = %( &lt;#{node.sub_replacements author.email}&gt;) if author.email
+    return %(#{name}#{mail})
+  end
+
   def compose_floating_title title
     # NOTE: Unlike AsciiDoc, DITA does not support floating titles or
     # titles assigned to certain block elements. As a workaround, I decided

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-dita-topic
 version: !ruby/object:Gem::Version
-  version: 1.0.8
+  version: 1.1.0
 platform: ruby
 authors:
 - Jaromir Hradilek
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-13 00:00:00.000000000 Z
+date: 2025-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -79,6 +79,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- AUTHORS
+- LICENSE
+- README.adoc
 - lib/dita-topic.rb
 homepage: https://github.com/jhradilek/asciidoctor-dita-topic
 licenses:
@@ -102,7 +105,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: A custom AsciiDoc converter that generates individual DITA topics