asciidoctor-dita-topic 1.1.8 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 555374cce6e4fb24f49f9c756f93c5198dad77e11ca2b936e74d785cd0dfdc46
-  data.tar.gz: 5b58e29874ab9a538f78450ac7c705f074ac5edc2bb32755d98f94c691950821
+  metadata.gz: 51a2caa5d7a9ffe86c7953d7ac7b7be5b75e805e2cc26f1d5b41cfcbc82c876d
+  data.tar.gz: 37951e25ad0227c52b0d1aeb1c37c8195bcc316a7f2073e1fc3c22d7b4bb5592
 SHA512:
-  metadata.gz: 5877a348c87c911a141d66a6dd83879b3fdd2e614d5d106d1d30bfe75dcb685bdcc1ad641bb3e62151ea4e93e20dfbfad693fed011c4720c1f72bfb4f1d7fbd1
-  data.tar.gz: e03de5af2e3ef13a6364cca3a3f00b257eabc542403cf422a30178049269031873c6c88e95b3f32b72bf57e15b745f5e7d683311d7da334bba95ecbf4c77a317
+  metadata.gz: 23a3d3efe86dc34fcf92014fa9e2f3c08c8a9ac76150f22e0dea7951239170cbbcd18d0477797c0acad7464dc401ae849010c4409271d1df4d4b38deb5a04c63
+  data.tar.gz: 2bf8a48fcd886f3674f21ce2676c1de1e9e7b3564a87803500d6d4994dec573b24608e50e5caadaccc9b98e1d6baefec3c26a0690590fd384b4814faa4513fe8

data/README.adoc

@@ -144,18 +144,6 @@ 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**
 ....
 
-[#abstracts]
-=== Disable abstracts
-
-By default, the `dita-topic` converter recognizes a paragraph preceded by the `[role="_abstract"]` attribute list and preserves this information by adding the `outputclass="abstract"` attribute to it in DITA. The link:https://github.com/jhradilek/dita-custom-xslt#installation[dita-convert Python package] uses this attribute to populate the `<shortdesc>` element during conversion to a specialized DITA concept, reference, or task.
-
-To disable this behavior, set the value of the `dita-topic-abstracts` to `off`:
-
-[literal,subs="+quotes"]
-....
-$ **asciidoctor -r dita-topic -b dita-topic -a dita-topic-abstracts=off _your_file_.adoc**
-....
-
 [#includes]
 === Disabling include directives
 
@@ -166,6 +154,59 @@ By default, Asciidoctor resolves all `include` directives before converting the
 $ **asciidoctor -r dita-topic -b dita-topic -S secure _your_file_.adoc**
 ....
 
+[#abstracts]
+=== Adding short descriptions
+
+DITA provides the `<shortdesc>` 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 `<shortdesc>` 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
+| `<cmdname>`
+
+| directory
+| `<filepath>`
+
+| filename
+| `<filepath>`
+
+| option
+| `<option>`
+
+| variable
+| `<varname>`
+|===
+
+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
 
@@ -181,8 +222,6 @@ 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.
@@ -209,8 +248,6 @@ Table footers not supported in DITA:: AsciiDoc allows you to set the `footer` op
 
 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
 

data/lib/dita-topic.rb

@@ -38,9 +38,6 @@ class DitaTopic < Asciidoctor::Converter::Base
     # Disable the author line by default:
     @authors_allowed = false
 
-    # Enable abstract paragraphs by default:
-    @abstracts_allowed = true
-
     # Enable callouts by default:
     @callouts_allowed = true
 
@@ -55,9 +52,6 @@ class DitaTopic < Asciidoctor::Converter::Base
     # Check if the author line is enabled:
     @authors_allowed = true if (node.attr 'dita-topic-authors') == 'on'
 
-    # Check if abstract paragraphs are enabled:
-    @abstracts_allowed = false if (node.attr 'dita-topic-abstracts') == 'off'
-
     # Check if callouts are enabled:
     @callouts_allowed = false if (node.attr 'dita-topic-callouts') == 'off'
 
@@ -135,9 +129,16 @@ class DitaTopic < Asciidoctor::Converter::Base
   end
 
   def convert_audio node
-    # Issue a warning if audio content is present:
-    logger.warn "#{NAME}: Audio macro not supported"
-    return ''
+    # Check if the audio macro has a title specified:
+    if node.title?
+      <<~EOF.chomp
+      <object data="#{node.media_uri(node.attr 'target')}">
+        <desc>#{node.title}</desc>
+      </object>
+      EOF
+    else
+      %(<object data="#{node.media_uri(node.attr 'target')}" />)
+    end
   end
 
   def convert_colist node
@@ -450,7 +451,26 @@ class DitaTopic < Asciidoctor::Converter::Base
     when :strong
       %(<b>#{node.text}</b>)
     when :monospaced
-      %(<tt>#{node.text}</tt>)
+      # Check whether a role is provided:
+      if node.role
+        # Define supported roles:
+        semantic_markup = {
+          'command'   => 'cmdname',
+          'directory' => 'filepath',
+          'filename'  => 'filepath',
+          'option'    => 'option',
+          'variable'  => 'varname'
+        }
+
+        # Select the appropriate semantic element:
+        element = (semantic_markup.key? node.role) ? semantic_markup[node.role] : 'tt'
+      else
+        # Use the teletype element by default:
+        element = 'tt'
+      end
+
+      # Return the result:
+      %(<#{element}>#{node.text}</#{element}>)
     when :superscript
       %(<sup>#{node.text}</sup>)
     when :subscript
@@ -557,7 +577,7 @@ class DitaTopic < Asciidoctor::Converter::Base
   end
 
   def convert_paragraph node
-    if @abstracts_allowed and (node.attr 'role') == '_abstract'
+    if (node.attr 'role') == '_abstract'
       add_block_title %(<p outputclass="abstract">#{node.content}</p>), node.title
     else
       add_block_title %(<p>#{node.content}</p>), node.title
@@ -782,9 +802,41 @@ class DitaTopic < Asciidoctor::Converter::Base
   end
 
   def convert_video node
-    # Issue a warning if video content is present:
-    logger.warn "#{NAME}: Video macro not supported"
-    return ''
+    # Check if additional attributes are specified:
+    width  = (node.attr? 'width') ? %( width="#{node.attr 'width'}") : ''
+    height = (node.attr? 'height') ? %( height="#{node.attr 'height'}") : ''
+
+    # Check if the video is a Vimeo or YouTube video:
+    if (provider = (node.attr 'poster')) == 'youtube'
+      # Separate a playlist from the target:
+      target, list = (node.attr 'target').split '/', 2
+
+      # Check if the playlist is provided as an attribute:
+      if node.attr 'list' and not list
+        list = node.attr 'list'
+      end
+
+      # Compose the playlist URL fragment:
+      list = list ? %(?list=#{list}) : ''
+
+      # Compose the target URL:
+      target_url = %(https://www.youtube.com/embed/#{target}#{list})
+    elsif provider == 'vimeo'
+      target_url = %(https://player.vimeo.com/video/#{node.attr 'target'})
+    else
+      target_url = node.media_uri(node.attr 'target')
+    end
+
+    # Check if the audio macro has a title specified:
+    if node.title?
+      <<~EOF.chomp
+      <object data="#{target_url}"#{width}#{height}>
+        <desc>#{node.title}</desc>
+      </object>
+      EOF
+    else
+      %(<object data="#{target_url}"#{width}#{height} />)
+    end
   end
 
   def compose_qanda_dlist node

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-dita-topic
 version: !ruby/object:Gem::Version
-  version: 1.1.8
+  version: 1.2.0
 platform: ruby
 authors:
 - Jaromir Hradilek
 bindir: bin
 cert_chain: []
-date: 2025-05-27 00:00:00.000000000 Z
+date: 2025-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor