RubyGems - asciidoctor-dita-topic - Versions diffs - 1.0.1 - Mend

asciidoctor-dita-topic 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

checksums.yaml ADDED Viewed

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a78953056690681fd5bd90e2ddc9bf86fc58a97e13ef88e3493aaccfd841af38
+  data.tar.gz: a6f0615ccc0706a2c70411596d7d6bf535530643548b45ca3647b9763e75c289
+SHA512:
+  metadata.gz: e4844fa7069d23b72d084a398a1d9895e1ce34c8a2a888508d9b83aefefa36cf4c56d681a6b6ffdd5f5891f7223128f5806e73fdb94624228399726d085a9253
+  data.tar.gz: 47bf20454de4e0b2c4ad8386ac6a4f81d5d792c3ee7ff0b73b2b2fe1cba700a3cd93f65edce4ecf082f3ea2d0954aeada3a685213005de3e49bf95dc9920736c

data/lib/dita-topic.rb ADDED Viewed

@@ -0,0 +1,704 @@
+# A custom AsciiDoc converter that generates individual DITA topics
+# Copyright (C) 2024 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 "Soft-
+# ware"),  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 condi-
+# tions:
+#
+# 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 MERCHANTABI-
+# LITY,  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.
+# frozen_string_literal: true
+module Asciidoctor
+class DitaConverter < Asciidoctor::Converter::Base
+  NAME = 'dita-topic'
+  register_for NAME
+  def initialize *args
+    super
+    outfilesuffix '.dita'
+  end
+  def convert_document node
+    # Check if the modular documentation content type is specified:
+    content_type = (node.attr? '_mod-docs-content-type') ? %( outputclass="#{(node.attr '_mod-docs-content-type').downcase}") : ''
+    # 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'])}#{content_type}>
+    <title>#{node.doctitle}</title>
+    <body>
+    #{node.content}
+    </body>
+    </topic>
+    EOF
+  end
+  def convert_admonition node
+    # NOTE: Unlike admonitions in AsciiDoc, the <note> element in DITA
+    # cannot have its own <title>. Admonition titles are therefore not
+    # preserved.
+    # Issue a warning if the admonition has a title:
+    if node.title?
+      logger.warn "#{NAME}: Admonition title not supported in DITA: #{node.title}"
+    end
+    # Return the XML output:
+    <<~EOF.chomp
+    <note type="#{node.attr 'name'}">
+    #{node.content}
+    </note>
+    EOF
+  end
+  def convert_audio node
+    # Issue a warning if audio content is present:
+    logger.warn "#{NAME}: Audio macro not supported"
+    return ''
+  end
+  # FIXME: Figure out how to handle this along with convert_inline_callout.
+  # A definition list looks like a reasonable option.
+  def convert_colist node
+    # Issue a warning if a callout list is present:
+    logger.warn "#{NAME}: Callout list support not implemented"
+    return ''
+  end
+  # FIXME: Add support for a title.
+  def convert_dlist node
+    # Check if a different list style is set:
+    return compose_horizontal_dlist node if node.style == 'horizontal'
+    return compose_qanda_dlist node if node.style == 'qanda'
+    # Open the definition list:
+    result = ['<dl>']
+    # Process individual list items:
+    node.items.each do |terms, description|
+      # Open the definition entry:
+      result << %(<dlentry>)
+      # Process individual terms:
+      terms.each do |item|
+        result << %(<dt>#{item.text}</dt>)
+      end
+      # Check if the term description is specified:
+      if description
+        # Check if the description contains multiple block elements:
+        if description.blocks?
+          result << %(<dd>)
+          result << %(<p>#{description.text}</p>) if description.text?
+          result << description.content
+          result << %(</dd>)
+        else
+          result << %(<dd>#{description.text}</dd>)
+        end
+      end
+      # Close the definition entry:
+      result << %(</dlentry>)
+    end
+    # Close the definition list:
+    result << '</dl>'
+    # Return the XML output:
+    result.join LF
+  end
+  def convert_example node
+    <<~EOF.chomp
+    <example#{compose_id node.id}>
+    #{compose_title node.title}#{node.content}
+    </example>
+    EOF
+  end
+  def convert_floating_title node
+    compose_floating_title node.title, node.level
+  end
+  # FIXME: Add support for additional attributes.
+  def convert_image node
+    # Check if the image has a title specified:
+    if node.title?
+      <<~EOF.chomp
+      <fig>
+      <title>#{node.title}</title>
+      <image href="#{node.image_uri(node.attr 'target')}" placement="break">
+      <alt>#{node.alt}</alt>
+      </image>
+      </fig>
+      EOF
+    else
+      <<~EOF.chomp
+      <image href="#{node.image_uri(node.attr 'target')}" placement="break">
+      <alt>#{node.alt}</alt>
+      </image>
+      EOF
+    end
+  end
+  def convert_inline_anchor node
+    # Determine the type of the anchor:
+    case node.type
+    when :link
+      # Compose an external link:
+      %(<xref href="#{node.target}" scope="external">#{node.text}</xref>)
+    when :xref
+      # NOTE: While AsciiDoc is happy to reference an ID that is not
+      # defined in the same AsciiDoc file, DITA requires the topic ID as
+      # part of the reference. As this script does not have direct access
+      # to the topic IDs of external files and to avoid performance issues
+      # I do not want to process them from this script, I choose to issue a
+      # warning so that the user can resolve the problem.
+      # Determine whether the cross reference links to a file path or an ID:
+      if (path = node.attributes['path'])
+        # Issue a warning if the cross reference includes an ID:
+        logger.warn "#{NAME}: Possible invalid reference: #{node.target}" if node.target.include? '#'
+        # Compose a cross reference:
+        %(<xref href="#{node.target}">#{node.text || path}</xref>)
+      else
+        # Issue a warning as the cross reference is unlikely to work:
+        logger.warn "#{NAME}: Possible invalid reference: #{node.target}"
+        # Compose the cross reference:
+        node.text ? %(<xref href="#{node.target}">#{node.text}</xref>) : %(<xref href="#{node.target}" />)
+      end
+    when :ref
+      # NOTE: DITA does not have a dedicated element for inline anchors or
+      # a direct equivalent of the <span> element from HTML. The solution
+      # below is the least invasive way I could find to achieve the
+      # equivalent behavior.
+      # Compose an inline anchor:
+      %(<i id="#{node.id}" />)
+    when :bibref
+      # NOTE: DITA does not have a dedicated element for inline anchors or
+      # a direct equivalent of the <span> element from HTML. The solution
+      # below is the least invasive way I could find to achieve the
+      # equivalent behavior.
+      # Compose a bibliographic reference:
+      %(<i id="#{node.id}" />[#{node.reftext || node.id}])
+    else
+      # Issue a warning if an unknown anchor type is present:
+      logger.warn "#{NAME}: Unknown anchor type: #{node.type}"
+      ''
+    end
+  end
+  def convert_inline_break node
+    # NOTE: Unlike AsciiDoc, DITA does not support inline line breaks.
+    # Issue a warning if an inline line break is present:
+    logger.warn "#{NAME}: Inline breaks not supported in DITA"
+    # Return the XML output:
+    %(#{node.text}<!-- break -->)
+  end
+  def convert_inline_button node
+    %(<uicontrol outputclass="button">#{node.text}</uicontrol>)
+  end
+  def convert_inline_callout node
+    # Issue a warning if an inline callout is present:
+    logger.warn "#{NAME}: Inline callout support not implemented"
+    return ''
+  end
+  # FIXME: Add support for footnoteref equivalent.
+  def convert_inline_footnote node
+    %(<fn>#{node.text}</fn>)
+  end
+  # FIXME: Add support for additional attributes.
+  def convert_inline_image node
+    %(<image href="#{node.image_uri node.target}" placement="inline"><alt>#{node.alt}</alt></image>)
+  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 ''
+  end
+  # FIXME: Investigate if there is an equivalent of <span> in DITA that
+  # would group individual <uicontrol> elements together.
+  def convert_inline_kbd node
+    # Check if there is more than one key:
+    if (keys = node.attr 'keys').size == 1
+      %(<uicontrol outputclass="key">#{keys[0]}</uicontrol>)
+    else
+      %(<uicontrol outputclass="key">#{keys.join '</uicontrol>+<uicontrol outputclass="key">'}</uicontrol>)
+    end
+  end
+  def convert_inline_menu node
+    # Compose the markup for the menu:
+    menu = %(<uicontrol>#{node.attr 'menu'}</uicontrol>)
+    # Compose the markup for possible submenus:
+    submenus = (not (node.attr 'submenus').empty?) ? %(<uicontrol>#{(node.attr 'submenus').join '</uicontrol><uicontrol>'}</uicontrol>) : ''
+    # Compose the markup for the menu item:
+    menuitem = (node.attr 'menuitem') ? %(<uicontrol>#{node.attr 'menuitem'}</uicontrol>) : ''
+    # Return the XML output:
+    %(<menucascade>#{menu}#{submenus}#{menuitem}</menucascade>)
+  end
+  def convert_inline_quoted node
+    # Determine the inline markup type:
+    case node.type
+    when :emphasis
+      %(<i>#{node.text}</i>)
+    when :strong
+      %(<b>#{node.text}</b>)
+    when :monospaced
+      %(<tt>#{node.text}</tt>)
+    when :superscript
+      %(<sup>#{node.text}</sup>)
+    when :subscript
+      %(<sub>#{node.text}</sub>)
+    when :double
+      %(&#8220;#{node.text}&#8221;)
+    when :single
+      %(&#8216;#{node.text}&#8217;)
+    else
+      node.text
+    end
+  end
+  def convert_listing node
+    # Check the listing style:
+    if node.style == 'source'
+      # Check whether the source language is defined:
+      language = (node.attributes.key? 'language') ? %( outputclass="language-#{node.attributes['language']}") : ''
+      # Return the XML output:
+      <<~EOF.chomp
+      <codeblock#{language}>
+      #{node.content}
+      </codeblock>
+      EOF
+    else
+      # Return the XML output:
+      <<~EOF.chomp
+      <screen>
+      #{node.content}
+      </screen>
+      EOF
+    end
+  end
+  def convert_literal node
+    <<~EOF.chomp
+    <pre>
+    #{node.content}
+    </pre>
+    EOF
+  end
+  # FIXME: Add support for titles.
+  def convert_olist node
+    # Open the ordered list:
+    result = ['<ol>']
+    # Process individual list items:
+    node.items.each do |item|
+      # Check if the list item contains multiple block elements:
+      if item.blocks?
+        result << %(<li>)
+        result << %(<p>#{item.text}</p>)
+        result << item.content
+        result << %(</li>)
+      else
+        result << %(<li>#{item.text}</li>)
+      end
+    end
+    # Close the ordered list:
+    result << '</ol>'
+    # Return the XML output:
+    result.join LF
+  end
+  # FIXME: This is not the top priority.
+  def convert_open node
+    ''
+  end
+  def convert_page_break node
+    # NOTE: Unlike AsciiDoc, DITA does not support page breaks.
+    # Issue a warning if a page break is present:
+    logger.warn "#{NAME}: Page breaks not supported in DITA"
+    # Return the XML output:
+    %(<p outputclass="page-break"></p>)
+  end
+  def convert_paragraph node
+    # Check if the paragraph has a title assigned:
+    if node.title?
+      <<~EOF.chomp
+      <div outputclass="paragraph">
+      #{compose_floating_title node.title}<p>#{node.content}</p>
+      </div>
+      EOF
+    else
+      %(<p>#{node.content}</p>)
+    end
+  end
+  def convert_preamble node
+    node.content
+  end
+  def convert_quote node
+    # Check if the author is defined:
+    author = (node.attr? 'attribution') ? %(\n<p>&#8212; #{node.attr 'attribution'}</p>) : ''
+    # Check if the citation source is defined:
+    source = (node.attr? 'citetitle') ? %(\n<cite>#{node.attr 'citetitle'}</cite>) : ''
+    # Check if the content contains multiple block elements:
+    if node.content_model == :compound
+      <<~EOF.chomp
+      <lq>
+      #{compose_floating_title node.title}#{node.content}#{author}#{source}
+      </lq>
+      EOF
+    else
+      <<~EOF.chomp
+      <lq>
+      #{compose_floating_title node.title}<p>#{node.content}</p>#{author}#{source}
+      </lq>
+      EOF
+    end
+  end
+  def convert_section node
+    # NOTE: Unlike sections in AsciiDoc, the <section> element in DITA
+    # cannot be nested. Consequently, converting AsciiDoc files that do
+    # contain nested subsections will result in invalid markup.
+    #
+    # I explored the possibility to use the <topic> element instead as it
+    # can be nested, but that presents a problem with closing the <body>
+    # element of the parent <topic>. As only a very small number of
+    # AsciiDoc modules contain nested subsections, I chose the simple
+    # markup.
+    # Issue a warning if there are nested sections:
+    logger.warn "#{NAME}: Nesting of sections not supported in DITA" if node.level > 1
+    # Return the XML output:
+    <<~EOF.chomp
+    <section#{compose_id node.id}>
+    <title>#{node.title}</title>
+    #{node.content}
+    </section>
+    EOF
+  end
+  def convert_sidebar node
+    # NOTE: Unlike AsciiDoc, DITA does not provide markup for a sidebar. As
+    # a workaround, I decided to use a div with the outputclass attribute.
+    # Check if the content contains multiple block elements:
+    if node.content_model == :compound
+      <<~EOF.chomp
+      <div outputclass="sidebar">
+      #{compose_floating_title node.title}#{node.content}
+      </div>
+      EOF
+    else
+      <<~EOF.chomp
+      <div outputclass="sidebar">
+      #{compose_floating_title node.title}<p>#{node.content}</p>
+      </div>
+      EOF
+    end
+  end
+  def convert_stem node
+    # Issue a warning if a STEM content is present:
+    logger.warn "#{NAME}: STEM support not implemented"
+    return ''
+  end
+  def convert_table node
+    # Open the table:
+    result = ['<table>']
+    # Check if the title is specified:
+    result << %(<title>#{node.title}</title>) if node.title?
+    # Define the table properties and open the tgroup:
+    result << %(<tgroup cols="#{node.attr 'colcount'}">)
+    # Define column properties:
+    node.columns.each do |column|
+      result << %(<colspec colname="col_#{column.attr 'colnumber'}" colwidth="#{column.attr ((node.attr? 'width') ? 'colabswidth' : 'colpcwidth')}*"/>)
+    end
+    # Process each table section (header, body, and footer):
+    node.rows.to_h.each do |type, rows|
+      # Skip empty sections:
+      next if rows.empty?
+      # Issue a warning if a table footer is present:
+      if type == :foot
+        logger.warn "#{NAME}: Table footers not supported in DITA"
+        next
+      end
+      # Open the section:
+      result << %(<t#{type}>)
+      # Process each row:
+      rows.each do |row|
+        # Open the row:
+        result <<%(<row>)
+        # Process each cell:
+        row.each do |cell|
+          # Check if the cell spans multiple columns:
+          colspan = cell.colspan ? %( namest="col_#{colnum = cell.column.attr 'colnumber'}" nameend="col_#{column + cell.colspan - 1}") : ''
+          # Check if the cell spans multiple rows:
+          rowspan = cell.rowspan ? %( morerows="#{cell.rowspan - 1}") : ''
+          # Compose the entry tag:
+          entry_tag = %(entry#{colspan}#{rowspan})
+          # Determine the formatting of the entry:
+          if type == :head
+            result << %(<#{entry_tag}>#{cell.text}</entry>)
+            next
+          end
+          case cell.style
+          when :asciidoc
+            result << %(<#{entry_tag}>#{cell.content}</entry>)
+          when :literal
+            result << %(<#{entry_tag}><pre>#{cell.text}</pre></entry>)
+          else
+            result << %(<#{entry_tag}>)
+            cell.content.each do |line|
+              result << %(<p>#{line}</p>)
+            end
+            result << %(</entry>)
+          end
+        end
+        # Close the row:
+        result <<%(</row>)
+      end
+      # Close the section:
+      result << %(</t#{type}>)
+    end
+    # Close the table:
+    result << %(</tgroup>)
+    result << %(</table>)
+    # Return the XML output:
+    result.join LF
+  end
+  def convert_thematic_break node
+    # NOTE: Unlike AsciiDoc, DITA does not support thematic breaks.
+    # Issue a warning if a thematic break is present:
+    logger.warn "#{NAME}: Thematic breaks not supported in DITA"
+    # Return the XML output:
+    %(<p outputclass="thematic-break"></p>)
+  end
+  # FIXME: Add support for titles.
+  def convert_ulist node
+    # Open the unordered list:
+    result = ['<ul>']
+    # Process individual list items:
+    node.items.each do |item|
+      # Check if the list item is part of a checklist:
+      unless item.attr? 'checkbox'
+        check_box = ''
+      else
+        check_box = (item.attr? 'checked') ? '&#10003; ' : '&#10063; '
+      end
+      # Check if the list item contains multiple block elements:
+      if item.blocks?
+        result << %(<li>)
+        result << %(<p>#{check_box}#{item.text}</p>)
+        result << item.content
+        result << %(</li>)
+      else
+        result << %(<li>#{check_box}#{item.text}</li>)
+      end
+    end
+    # Close the unordered list:
+    result << '</ul>'
+    # Returned the XML output:
+    result.join LF
+  end
+  def convert_verse node
+    # Check if the author is defined:
+    author = (node.attr? 'attribution') ? %(\n&#8212; #{node.attr 'attribution'}) : ''
+    # Check if the citation source is defined:
+    source = (node.attr? 'citetitle') ? %(\n<cite>#{node.attr 'citetitle'}</cite>) : ''
+    # Return the XML output:
+    <<~EOF.chomp
+    <lines>
+    #{node.content}#{author}#{source}
+    </lines>
+    EOF
+  end
+  def convert_video node
+    # Issue a warning if video content is present:
+    logger.warn "#{NAME}: Video macro not supported"
+    return ''
+  end
+  def compose_qanda_dlist node
+    # Open the ordered list:
+    result = ['<ol>']
+    # Process individual list items:
+    node.items.each do |terms, description|
+      # Open the list item:
+      result << %(<li>)
+      # Process individual terms:
+      terms.each do |item|
+        result << %(<p outputclass="question"><i>#{item.text}</i></p>)
+      end
+      # Check if the term description is specified:
+      if description
+        result << %(<p>#{description.text}</p>)
+        result << description.content if description.blocks?
+      end
+      # Close the list item:
+      result << %(</li>)
+    end
+    # Close the ordered list:
+    result << '</ol>'
+    # Return the XML output:
+    result.join LF
+  end
+  def compose_horizontal_dlist node
+    # Open the table:
+    result = ['<table>']
+    # Define the table properties and open the tgroup:
+    result << %(<tgroup cols="2">)
+    result << %(<colspec colwidth="#{node.attr 'labelwidth', 15}*" />)
+    result << %(<colspec colwidth="#{node.attr 'itemwidth', 85}*" />)
+    # Open the table body:
+    result << %(<tbody>)
+    # Process individual list items:
+    node.items.each do |terms, description|
+      # Open the table row:
+      result << %(<row>)
+      # Check the number of terms to process:
+      if terms.count == 1
+        result << %(<entry><b>#{terms[0].text}</b></entry>)
+      else
+        # Process individual terms:
+        result << %(<entry>)
+        terms.each do |item|
+          result << %(<p><b>#{item.text}</b></p>)
+        end
+        result << %(</entry>)
+      end
+      # Check if the term description is specified:
+      if description
+        # Check if the description contains multiple block elements:
+        if description.blocks?
+          result << %(<entry>)
+          result << %(<p>#{description.text}</p>) if description.text?
+          result << description.content
+          result << %(</entry>)
+        else
+          result << %(<entry>#{description.text}</entry>) if description.text?
+        end
+      end
+      # Close the table row:
+      result << %(</row>)
+    end
+    # Close the table:
+    result << %(</tbody>)
+    result << %(</tgroup>)
+    result << %(</table>)
+    # Return the XML output:
+    result.join LF
+  end
+  def compose_floating_title title, section_level=false
+    # NOTE: Unlike AsciiDoc, DITA does not support floating titles or
+    # titles assigned to certain block elements. As a workaround, I decided
+    # to use a paragraph with the outputclass attribute.
+    # Check whether the section level is defined:
+    level = section_level ? %( sect#{section_level}) : ''
+    # Return the XML output:
+    title ? %(<p outputclass="title#{level}"><b>#{title}</b></p>\n) : ''
+  end
+  def compose_id id
+    id ? %( id="#{id}") : ''
+  end
+  def compose_title title
+    title ? %(<title>#{title}</title>\n) : ''
+  end
+end
+end

metadata ADDED Viewed

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: asciidoctor-dita-topic
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Jaromir Hradilek
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-06-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: asciidoctor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+description: An extension for AsciiDoctor that converts a single AsciiDoc file to
+  a DITA topic.
+email: jhradilek@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/dita-topic.rb
+homepage: https://github.com/jhradilek/asciidoctor-dita-topic
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jhradilek/asciidoctor-dita-topic
+  bug_tracker_uri: https://github.com/jhradilek/asciidoctor-dita-topic/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: A custom AsciiDoc converter that generates individual DITA topics
+test_files: []