asciidoctor-dita-topic 1.1.8 → 1.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 555374cce6e4fb24f49f9c756f93c5198dad77e11ca2b936e74d785cd0dfdc46
-  data.tar.gz: 5b58e29874ab9a538f78450ac7c705f074ac5edc2bb32755d98f94c691950821
+  metadata.gz: 38849b62e13e55fe22459cab2c4a7aab8d47286e94cb5d573eeed98c175381ce
+  data.tar.gz: 440406834354a1a70c87be6026b763f95c920de0d924d5f9a2cdb2aee5842a1f
 SHA512:
-  metadata.gz: 5877a348c87c911a141d66a6dd83879b3fdd2e614d5d106d1d30bfe75dcb685bdcc1ad641bb3e62151ea4e93e20dfbfad693fed011c4720c1f72bfb4f1d7fbd1
-  data.tar.gz: e03de5af2e3ef13a6364cca3a3f00b257eabc542403cf422a30178049269031873c6c88e95b3f32b72bf57e15b745f5e7d683311d7da334bba95ecbf4c77a317
+  metadata.gz: cb1ee4720a5c4580557cf96bba10e93aa70e3ea1d3c976e0a2968f329a4e9eab7c04f3a60b8c791fa524089f0096c07e6624d170ffe8acc987f56add7992cab3
+  data.tar.gz: 26fe19f12366806c508b6c11218c6a78aa3d522032260d135e5b344bad150c91cdbe159d75b81b6ff1adcf0f58a3e52e440bee41c0563f785f4be70e0a92671a

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
 

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'
 
@@ -450,7 +444,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 +570,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

metadata

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