asciidoctor-dita-map 0.1.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 785383f1b9ac91dfff356c6ccfce6568a16af5c805715d24d294f8539d019d89
-  data.tar.gz: 0be9258a03b8cff762cd30aae0657b6d105636b1a92334ed456ae68f57eabf1b
+  metadata.gz: 11f4d701aaa5c98c2ed6d3f78393c695e60cf981b2332e65f7b6c86288cfa5aa
+  data.tar.gz: 2db0005558356a8578d9f0bf89c08140bd74becc1372eed2aa85fc78ae406438
 SHA512:
-  metadata.gz: d9dcb68378da10bd98c006524283da2741f32028988dcd2236ecaef3e5933e44a333f8502d8656e94c29dffff1373b542ed2efc75b48e6130d35cd5722395ac9
-  data.tar.gz: c550422cc1932cc96c952c26a978d48d7788a8b5c9700ad3c51c1f544f29407d780fc5c13a25b06b11e78ae4b7b0751ab26caecf01020c449d94397b10b4d6db
+  metadata.gz: f5684c9fe2027bf5b99b080feb850a0840598a55f0f8fd0dcef5281a18cbf8a895aaab00a906e94eeecdb0befa7fd600ab68f867b7edf2906128ced51078e6df
+  data.tar.gz: 38d6f1d08c260b6438535a47dc81d48e151a2997e46fc4b79b93a799a8d600b9dcb45550e702c1bf2f38cc5b2670ec8b39a2ba7a1b3fecf3f1bca5c53de25241

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,8 @@ module AsciidoctorDitaMap
         :navtitle => true,
         :output => false,
         :title => true,
-        :type => true
+        :type => true,
+        :verbose => false
       }
       @prep = []
       @name = name
@@ -86,12 +87,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
@@ -125,14 +132,13 @@ module AsciidoctorDitaMap
         document_type.sub!(/^procedure$/, 'task')
       end
 
-      unless ['concept', 'reference', 'task', 'map'].include? document_type
+      unless ['concept', 'reference', 'task', 'map', 'attributes', 'snippet'].include? document_type
         document_type = nil
       end
 
       return document_title, document_type
     end
 
-
     def parse_map input, base_dir
       Asciidoctor::Extensions.register do
         include_processor CatalogIncludeDirectives
@@ -174,30 +180,33 @@ module AsciidoctorDitaMap
         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')

data/lib/dita-map/version.rb

@@ -24,5 +24,5 @@
 # frozen_string_literal: true
 
 module AsciidoctorDitaMap
-  VERSION     = '0.1.0'
+  VERSION     = '0.9.0'
 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.0
 platform: ruby
 authors:
 - Jaromir Hradilek