asciidoctor-dita-map 0.1.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 785383f1b9ac91dfff356c6ccfce6568a16af5c805715d24d294f8539d019d89
-  data.tar.gz: 0be9258a03b8cff762cd30aae0657b6d105636b1a92334ed456ae68f57eabf1b
+  metadata.gz: 4eb319b4d8423d61539d7ec4816ccfac5499656cc15b739542ddb68023d210a0
+  data.tar.gz: 768371877af9214c0d80db4e19f29db88ab85c00821a5965480bd7f5304c3f2a
 SHA512:
-  metadata.gz: d9dcb68378da10bd98c006524283da2741f32028988dcd2236ecaef3e5933e44a333f8502d8656e94c29dffff1373b542ed2efc75b48e6130d35cd5722395ac9
-  data.tar.gz: c550422cc1932cc96c952c26a978d48d7788a8b5c9700ad3c51c1f544f29407d780fc5c13a25b06b11e78ae4b7b0751ab26caecf01020c449d94397b10b4d6db
+  metadata.gz: d251c66f265772f85a48aee4e8da5c4f9902870e991074dfe10c12977fcbb5921c3a6b695108bfa0025becb1d97bd8cb19bd92fbbeee958b3a5958ed8cfead5f
+  data.tar.gz: 0ed486763aa0b355ef4ec931ce87181ab2a6ca9c024e55d9ec03b2782c9ceed05f321ef396378e9421ad10a1ef13200fb05c954e30081af25397ab6905fe0846

data/README.md

@@ -1,6 +1,100 @@
 # dita-map
 
-**dita-map** is a command line utility that converts a single AsciiDoc file to a DITA map.
+**dita-map** is a command line utility that converts a single AsciiDoc file to a DITA map. It recognizes the [document title](https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/#section-level-syntax) as the map title and uses the [include directives](https://docs.asciidoctor.org/asciidoc/latest/directives/include/) and their respective [leveloffset](https://docs.asciidoctor.org/asciidoc/latest/directives/include-with-leveloffset/#manipulate-heading-levels-with-leveloffset) values to compose the tree of `<mapref>` and `<topicref>` elements.
+
+## Installation
+
+Install the `asciidoctor-dita-map` Ruby gem:
+
+```console
+gem install asciidoctor-dita-map
+```
+
+## Usage
+
+To convert a single AsciiDoc file to a DITA map, supply it as an argument to the `dita-map` command:
+
+```console
+$ dita-map your_file.adoc
+```
+
+By default, `dita-map` creates a new file, `your_file.ditamap`, in the same directory as the source file. You can supply multiple files at the same time or use wildcards:
+
+```console
+$ dita-map *.adoc
+```
+
+When you do not supply any file names or specify `-` as the first argument, `dita-map` reads from standard input and prints the result to standard output. For example:
+
+```console
+$ echo 'include::task.adoc[leveloffset=+1]' | dita-map
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
+<map>
+  <topicref href="task.dita" navtitle="A topic title" type="task" />
+</map>
+```
+
+### Changing the output file name
+
+To change the output file name or location, use the `-o` or `--out-file` command-line option:
+
+```console
+$ dita-map input_file.adoc -o output_file.ditamap
+```
+
+To print the result to standard output, use `-` as the output file name. For example:
+
+```console
+$ dita-map input_file.adoc -o -
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
+<map>
+  <title>A map title</title>
+  <mapref href="another_map.ditamap" format="ditamap" type="map" />
+  <topicref href="concept.dita" navtitle="A concept title" type="concept">
+    <topicref href="task.dita" navtitle="A task title" type="task" />
+  </topicref>
+</map>
+```
+
+### Supplying individual attribute definitions
+
+If your AsciiDoc files use custom attributes that are defined externally, you can supply the attribute definitions with the `-a` or `--attribute` command-line option:
+
+```console
+$ dita-map -a attribute_name=attribute_value your_file.adoc
+```
+
+You can supply multiple `-a`/`--attribute` options at the same time.
+
+### Supplying attribute definition files
+
+If listing individual attribute definitions is impractical, you can supply AsciiDoc files that contain the attribute definitions with the `-p` or `--prepend-file` command-line option:
+
+```console
+$ dita-map -p definition_file.adoc your_file.adoc
+```
+
+The supplied file is prepended to each AsciiDoc file during conversion. You can supply multiple `-p`/`--prepend-file` options at the same time or combine them with the `-a`/`--attribute` options to construct your attribute definitions. If you define the same attribute twice this way, the value defined by the `-a`/`--attribute` option takes precedence.
+
+## Recognized content types
+
+To correctly recognize when to use the `<topicref>` and `<mapref>` elements and what values to assign to their `type` attributes, `dita-map` recognizes the following `:_mod-docs-content-type:` attribute definition values in included AsciiDoc files:
+
+| AsciiDoc attribute | Output element | Output type value |
+| --- | --- | --- |
+| `ASSEMBLY` | `<topicref>` | `concept` |
+| `CONCEPT` | `<topicref>` | `concept` |
+| `PROCEDURE` | `<topicref>` | `task` |
+| `REFERENCE` | `<topicref>` | `reference` |
+| `MAP` | `<mapref>` | `map` |
+
+For example, to ensure an included AsciiDoc file is recognized as a DITA map, add the following line at the top of the file:
+
+```asciidoc
+:_mod-docs-content-type: MAP
+```
 
 ## Copyright
 

data/lib/dita-map/cli.rb

@@ -37,7 +37,9 @@ module AsciidoctorDitaMap
         :navtitle => true,
         :output => false,
         :title => true,
-        :type => true
+        :type => true,
+        :self => false,
+        :verbose => false
       }
       @prep = []
       @name = name
@@ -66,6 +68,10 @@ module AsciidoctorDitaMap
           @prep.append file
         end
 
+        opt.on('-i', '--include-self', 'make the supplied file the toplevel topicref') do
+          @opts[:self] = true
+        end
+
         opt.separator ''
 
         opt.on('-I', '--no-id', 'do not generate the map id attribute') do
@@ -86,12 +92,18 @@ module AsciidoctorDitaMap
 
         opt.separator ''
 
+        opt.on('-v', '--verbose', 'report additional problems in the supplied files') do
+          @opts[:verbose] = true
+        end
+
+        opt.separator ''
+
         opt.on('-h', '--help', 'display this help and exit') do
           puts opt
           exit
         end
 
-        opt.on('-v', '--version', 'display version information and exit') do
+        opt.on('-V', '--version', 'display version information and exit') do
           puts "#{@name} #{VERSION}"
           exit
         end
@@ -111,27 +123,49 @@ module AsciidoctorDitaMap
       return args
     end
 
-    def parse_topic input
-      doc = Asciidoctor.load input, safe: :secure, attributes: @attr
-      att = doc.attributes
+    def compose_mapref_attributes file_name, type
+      target_file        = file_name.sub(/\.adoc$/, '.ditamap')
+      attributes         = { 'href' => target_file, 'format' => 'ditamap' }
+      attributes['type'] = type if @opts[:type]
 
-      document_title = doc.title ? doc.title.gsub(/<[^>]*>/, '') : nil
-      document_type  = att['_mod-docs-content-type'] ? att['_mod-docs-content-type'].downcase : nil
-      document_type  = att['_content-type'] ? att['_content-type'].downcase : nil unless document_type
-      document_type  = att['_module-type'] ? att['_module-type'].downcase : nil unless document_type
+      return attributes
+    end
+
+    def compose_topicref_attributes file_name, title, type
+      target_file            = file_name.sub(/\.adoc$/, '.dita')
+
+      attributes             = { 'href' => target_file }
+      attributes['navtitle'] = title if @opts[:navtitle] and title
+      attributes['type']     = type if @opts[:type] and type and ['concept', 'reference', 'task'].include? type
+
+      return attributes
+    end
+
+    def get_content_type attributes
+      document_type  = attributes['_mod-docs-content-type'] ? attributes['_mod-docs-content-type'].downcase : nil
+      document_type  = attributes['_content-type'] ? attributes['_content-type'].downcase : nil unless document_type
+      document_type  = attributes['_module-type'] ? attributes['_module-type'].downcase : nil unless document_type
 
       if document_type
         document_type.sub!(/^assembly$/, 'concept')
         document_type.sub!(/^procedure$/, 'task')
       end
 
-      unless ['concept', 'reference', 'task', 'map'].include? document_type
-        document_type = nil
+      unless ['concept', 'reference', 'task', 'map', 'attributes', 'snippet'].include? document_type
+        return nil
       end
 
-      return document_title, document_type
+      return document_type
     end
 
+    def parse_topic input
+      doc = Asciidoctor.load input, safe: :secure, attributes: @attr
+
+      document_title = doc.title ? doc.title.gsub(/<[^>]*>/, '') : nil
+      document_type  = get_content_type doc.attributes
+
+      return document_title, document_type
+    end
 
     def parse_map input, base_dir
       Asciidoctor::Extensions.register do
@@ -141,76 +175,85 @@ module AsciidoctorDitaMap
       doc = Asciidoctor.load input, safe: :safe, catalog_assets: true, attributes: @attr, base_dir: base_dir
 
       include_files  = doc.catalog[:include_files] ? doc.catalog[:include_files] : []
-      document_title = doc.title ? doc.title.gsub(/<[^>]*>/, '') : nil
-      document_id    = doc.id ? doc.id.gsub(/["']/, '') : nil
+      map_id    = doc.id ? doc.id.gsub(/["']/, '') : nil
+      map_title = doc.title ? doc.title.gsub(/<[^>]*>/, '') : nil
+      map_type  = get_content_type doc.attributes
+
+      info = {
+        :id    => map_id,
+        :title => map_title,
+        :type  => map_type
+      }
 
-      return include_files, document_title, document_id
+      return include_files, info
     end
 
-    def convert_map input, base_dir, prepended = ''
+    def convert_map input, base_dir, prepended = '', file = nil
       result = ''
 
-      include_files, map_title, document_id = parse_map prepended + input, base_dir
+      include_files, map = parse_map prepended + input, base_dir
 
       xml = REXML::Document.new
       xml.context[:attribute_quote] = :quote
       xml << REXML::XMLDecl.new('1.0', 'utf-8')
       xml << REXML::DocType.new('map', 'PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"')
 
-      if document_id and @opts[:id]
-        xml_root  = xml.add_element('map', { 'id' => document_id })
+      if map[:id] and @opts[:id]
+        xml_root  = xml.add_element('map', { 'id' => map[:id] })
       else
         xml_root  = xml.add_element('map')
       end
 
-      if map_title and @opts[:title]
-        xml_title = xml_root.add_element('title')
-        xml_title.text = map_title
+      if map[:title] and @opts[:title]
+        xml_title      = xml_root.add_element('title')
+        xml_title.text = map[:title]
       end
 
-      stack = [{ :offset => 0, :element => xml_root }]
+      if @opts[:self] and file
+        attributes = compose_topicref_attributes file, map[:title], map[:type]
+        xml_self   = xml_root.add_element('topicref', attributes)
+        stack      = [{ :offset => 0, :element => xml_self }]
+      else
+        stack      = [{ :offset => 0, :element => xml_root }]
+      end
 
       include_files.each do |file|
         target      = file[:target]
         offset      = file[:offset]
         last_offset = stack.last[:offset]
+        full_path   = base_dir + target
+
+        if not File.exist? full_path and @opts[:verbose]
+          warn "#{@name}: warning: file not found: #{target}"
+        end
+
+        begin
+          include_title, include_type = parse_topic prepended + File.read(full_path)
+          next if ['attributes', 'snippet'].include? include_type
+        rescue
+          warn "#{@name}: warning: unable to read included file: #{target}"
+          include_title, include_type = nil, nil
+        end
 
         if offset == 0
-          warn "#{@name}: warning: Invalid leveloffset - expected 1, got 0: #{target}"
+          warn "#{@name}: warning: invalid leveloffset - expected 1, got 0: #{target}"
           offset = 1
         elsif offset > last_offset and offset - last_offset > 1
           expected_offset = last_offset + 1
-          warn "#{@name}: warning: Invalid leveloffset - expected #{expected_offset}, got #{offset}: #{target}"
-          offset = expected_offset
+          warn "#{@name}: warning: invalid leveloffset - expected #{expected_offset}, got #{offset}: #{target}"
         end
 
         while stack.last[:offset] >= offset
           stack.pop
         end
 
-        xml_parent   = stack.last[:element]
-
-        if @opts[:navtitle] or @opts[:type]
-          begin
-            include_title, include_type = parse_topic prepended + File.read(base_dir + target)
-          rescue
-            warn "#{@name}: warning: Unable to read included file: #{base_dir + target}"
-            include_title, include_type = nil, nil
-          end
-        end
+        xml_parent = stack.last[:element]
 
         if include_type == 'map'
-          file_name          = target.sub(/\.adoc$/, '.ditamap')
-          attributes         = { 'href' => file_name, 'format' => 'ditamap' }
-          attributes['type'] = include_type if @opts[:type]
-
+          attributes  = compose_mapref_attributes target, include_type
           xml_element = xml_parent.add_element('mapref', attributes)
         else
-          file_name = target.sub(/\.adoc$/, '.dita')
-          attributes             = { 'href' => file_name }
-          attributes['navtitle'] = include_title if include_title and @opts[:navtitle]
-          attributes['type']     = include_type if include_type and @opts[:type]
-
+          attributes  = compose_topicref_attributes target, include_title, include_type
           xml_element = xml_parent.add_element('topicref', attributes)
         end
 
@@ -245,7 +288,11 @@ module AsciidoctorDitaMap
           output   = @opts[:output] ? @opts[:output] : Pathname.new(file).sub_ext('.ditamap').to_s
         end
 
-        result = convert_map input, base_dir, prepended
+        if @opts[:self] and file != $stdin
+          result = convert_map input, base_dir, prepended, file
+        else
+          result = convert_map input, base_dir, prepended
+        end
 
         if output == $stdout
           $stdout.write result

data/lib/dita-map/version.rb

@@ -24,5 +24,5 @@
 # frozen_string_literal: true
 
 module AsciidoctorDitaMap
-  VERSION     = '0.1.0'
+  VERSION     = '0.9.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-dita-map
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Jaromir Hradilek
@@ -139,7 +139,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Convert an AsciiDoc file to a DITA map
 test_files: []