asciidoctor-dita-topic 1.0.9 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69250bbb61960007901efdae04ea972ce5089345d50c83ee667468c107022c5b
-  data.tar.gz: 587dc9c0bc07b4354f2c459bdd955f2b52e40c28803063d06788fa54cb2d6334
+  metadata.gz: 134df897545adafba05f060ea22079c3fa927204b47fff2eec8ffbc8ae5ef84a
+  data.tar.gz: 354b8abadd320b9a4c63b3c170a85974a2231836da07851e1cde58da06aafff3
 SHA512:
-  metadata.gz: f6e37a1231ca1c890ac761598d5ed576bf9114e83157c611ad0ffb9d585a164e9ba3c1de5138d0797ac08dcfca54f73a7c1a9280883c986be593c1665a990744
-  data.tar.gz: 4caaceb8cfed3c43d9991a51f9ec95614d22af38889521505b99527a37ae6e5e410813d268d1a2fe3ff7fef0b1cc87891dbcbaf48c8dd1d715c2367f98d847dd
+  metadata.gz: 4b7e9fcd688f450a2e05effca4c30d5969db15d7056cd23b6c1829d6f65de79cc95e0208f5dc543b5bd2f87117aa972f49dcff76963ef8b67879f5a40a97af6f
+  data.tar.gz: 05122aac651d614082cc4cb350197bdbb897d2b7436189eb225a230ffc3f8ad2f3ee5d66f1b882f78bab39d4fd38d18caaeba0d1b5dd965c98ccd7f52a530f97

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (C) 2024 Jaromir Hradilek
+Copyright (C) 2024, 2025 Jaromir Hradilek
 
 MIT License
 

data/README.adoc

@@ -80,10 +80,22 @@ $ **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 the conversion, as a workaround, the `dita-topic` converter uses the following markup by default:
+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]
 ----
@@ -100,7 +112,7 @@ $ **asciidoctor -r dita-topic -b dita-topic -a dita-topic-titles=off _your_file_
 [#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 the conversion, as a workaround, the `dita-topic` converter uses XML entities for circled numbers.
+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`:
 
@@ -136,6 +148,8 @@ Admonition titles not supported in DITA:: AsciiDoc allows you to add a custom ti
 
 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.
@@ -161,6 +175,6 @@ Video macro not supported:: AsciiDoc allows you to embed video content in your d
 [#copyright]
 == Copyright
 
-Copyright (C) 2024 Jaromir Hradilek
+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
@@ -434,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
@@ -787,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.9
+  version: 1.1.0
 platform: ruby
 authors:
 - Jaromir Hradilek
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-29 00:00:00.000000000 Z
+date: 2025-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor