asciidoctor-dita-topic 1.1.4 → 1.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8500891ad21dc6be419992bbb3ce0746bfb3c5e96f4cdb5c0faea28cd00fe59
-  data.tar.gz: df920f7ae7d468b8e981a05d1a16c932e2fcd31d9e22d22b5e7406cef880ca01
+  metadata.gz: 4800181685253324c6e93aa8be4011212e700a94ef82e6489b2980f3b6361cf2
+  data.tar.gz: e3f39557c7dc47af05889e99546369448c3ef4b4af53a233c0beb3d8b5d48705
 SHA512:
-  metadata.gz: d788246489a2ce5c11b1f293401d70efbc373c4561e266a497bee45a7de82fc20cae10a3cf3dcded6635e1054279a51250405d36fb6bd219c7602636d6ed2aa9
-  data.tar.gz: 9d4a9e9638f983baf60e401d3d4477c29036d028a12c751acd9e6e88527bcb97238838cccd9234cb750b560b76b23693bfa50726b483c853355eedaee0bf5f52
+  metadata.gz: 691af18c68f264cc32b5a1a01ad3f220a0bbda0258333be153d36f2de15559da8b1bb7184a9046ef1b53c37a366f3e25fa5aecbfcba4882445c9b4238be0238b
+  data.tar.gz: f366e45753bba7d68146839ba1e55b6d480588aab356fff072cba5093b52554b4f56667e347f3497fa12683927c4c2ea6995f94695f30b9ccf46d73a5a4567ed

data/README.adoc

@@ -1,6 +1,29 @@
 = 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#installation[dita-convert Python package].
+`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
@@ -166,6 +189,8 @@ Block titles not supported in DITA:: AsciiDoc allows you to include `._Block tit
 
 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 `<!-- break -\->` comment in the output file to mark its place.
@@ -174,7 +199,9 @@ Nesting of sections not supported in DITA:: AsciiDoc allows you to nest sections
 
 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.
+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 the cross reference target is not present in the converted AsciiDoc file.
+
+Sidebars not supported in DITA:: AsciiDoc allows you to assign any block the `[sidebar]` block style or enclose it between a pair of `\****` to create a delimited sidebar block. Unlike AsciiDoc, DITA does not support sidebar blocks. `dita-topic` issues this warning when the `-a dita-topic-sidebars=off` option is specified and a sidebar block 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.
 

data/lib/dita-topic.rb

@@ -46,6 +46,9 @@ class DitaTopic < Asciidoctor::Converter::Base
 
     # Enable floating and block titles by default:
     @titles_allowed = true
+
+    # Enable sidebars by default:
+    @sidebars_allowed = true
   end
 
   def convert_document node
@@ -61,6 +64,9 @@ class DitaTopic < Asciidoctor::Converter::Base
     # Check if floating and block titles are enabled:
     @titles_allowed = false if (node.attr 'dita-topic-titles') == 'off'
 
+    # Check if sidebars are enabled:
+    @sidebars_allowed = false if (node.attr 'dita-topic-sidebars') == 'off'
+
     # Check if the modular documentation content type is specified; both
     # _module-type and _content-type are deprecated, but still present in
     # some modules:
@@ -222,6 +228,12 @@ class DitaTopic < Asciidoctor::Converter::Base
   end
 
   def convert_example node
+    # Issue a warning if the example is nested:
+    unless (parent = node.parent.context) == :document
+      logger.warn "#{NAME}: Examples not supported within #{parent} in DITA"
+    end
+
+    # Return the XML output:
     <<~EOF.chomp
     <example#{compose_id node.id}>
     #{node.title ? %(<title>#{node.title}</title>\n) : ''}#{node.content}
@@ -352,7 +364,7 @@ class DitaTopic < Asciidoctor::Converter::Base
     end
 
     # Return the XML entity:
-    compose_circled_number node.text.to_i
+    %(<b outputclass="callout">#{compose_circled_number node.text.to_i}</b>)
   end
 
   def convert_inline_footnote node
@@ -441,6 +453,18 @@ class DitaTopic < Asciidoctor::Converter::Base
       %(&#8220;#{node.text}&#8221;)
     when :single
       %(&#8216;#{node.text}&#8217;)
+    when :asciimath
+      # Issue a warning if a STEM content is present:
+      logger.warn "#{NAME}: STEM support not implemented"
+
+      # Add comments around the STEM content:
+      %(<!-- asciimath start -->#{node.text}<!-- asciimath end -->)
+    when :latexmath
+      # Issue a warning if a STEM content is present:
+      logger.warn "#{NAME}: STEM support not implemented"
+
+      # Add comments around the STEM content:
+      %(<!-- latexmath start -->#{node.text}<!-- latexmath end -->)
     else
       node.text
     end
@@ -588,6 +612,12 @@ class DitaTopic < Asciidoctor::Converter::Base
     # NOTE: Unlike AsciiDoc, DITA does not provide markup for a sidebar. As
     # a workaround, I decided to use a div with the outputclass attribute.
 
+    # Issue a warning if sidebars are disabled:
+    unless @sidebars_allowed
+      logger.warn "#{NAME}: Sidebars not supported in DITA"
+      return ''
+    end
+
     # Check if the content contains multiple block elements:
     if node.content_model == :compound
       <<~EOF.chomp

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-dita-topic
 version: !ruby/object:Gem::Version
-  version: 1.1.4
+  version: 1.1.6
 platform: ruby
 authors:
 - Jaromir Hradilek
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-02 00:00:00.000000000 Z
+date: 2025-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -90,7 +89,6 @@ metadata:
   homepage_uri: https://github.com/jhradilek/asciidoctor-dita-topic
   bug_tracker_uri: https://github.com/jhradilek/asciidoctor-dita-topic/issues
   documentation_uri: https://github.com/jhradilek/asciidoctor-dita-topic/blob/main/README.adoc
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -105,8 +103,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: A custom AsciiDoc converter that generates individual DITA topics
 test_files: []