asciidoctor-diagram 2.0.2 → 2.1.2

data/docs/modules/ROOT/partials/generate.adoc

@@ -0,0 +1,15 @@
+== Generating a Diagram from a Terminal
+
+You can load Asciidoctor diagram in a terminal using the `-r` flag.
+
+ $ asciidoctor -r asciidoctor-diagram sample.adoc
+
+You can also use Asciidoctor diagram with other converters, such as Asciidoctor EPUB.
+Asciidoctor-epub3 is also loaded with the `-r` flag.
+
+ $ asciidoctor -r asciidoctor-diagram -r asciidoctor-epub3 -b epub3 sample.adoc
+
+Or, you can invoke Asciidoctor and the EPUB converter with the `asciidoctor-epub3` command.
+The command implicitly sets the `-r` and `-b` flags for EPUB3 output.
+
+ $ asciidoctor-epub3 -r asciidoctor-diagram sample.adoc

data/docs/modules/ROOT/partials/installation.adoc

@@ -0,0 +1,19 @@
+== Installation
+
+Asciidoctor Diagram is a RubyGem, which can be installed using the `gem` or `bundle` commands.
+
+You can install the Asciidoctor Diagram gem by typing `gem install` in the CLI.
+
+ $ gem install asciidoctor-diagram
+
+by first adding the following entry to your project's [.path]_Gemfile_.
+
+.Gemfile
+[source,ruby]
+----
+gem 'asciidoctor-diagram'
+----
+
+Then execute `bundle` in the CLI.
+
+ $ bundle

data/docs/modules/ROOT/partials/uris.adoc

@@ -0,0 +1,40 @@
+:uri-a2s: https://github.com/dhobsd/asciitosvg
+:uri-actdiag: http://blockdiag.com/en/actdiag/index.html
+:uri-asciidoctor-api: http://asciidoctor.org/docs/user-manual/#api
+:uri-asciidoctor-extensions: http://asciidoctor.org/docs/user-manual/#extension-points
+:uri-blockdiag: http://blockdiag.com
+:uri-bpmn: https://github.com/gtudan/bpmn-js-cmd
+:uri-bytefield: https://github.com/Deep-Symmetry/bytefield-svg
+:uri-diagrams: https://diagrams.mingrammer.com
+:uri-ditaa: http://ditaa.sourceforge.net/
+:uri-dpic: https://gitlab.com/aplevich/dpic
+:uri-dot: https://graphviz.gitlab.io/_pages/doc/info/lang.html
+:uri-erd: https://github.com/BurntSushi/erd
+:uri-gnuplot: http://gnuplot.info
+:uri-graphviz: https://graphviz.gitlab.io
+:uri-imagemagick: http://www.imagemagick.org
+:uri-java: http://java.sun.com
+:uri-mermaid: https://github.com/mermaid-js/mermaid-cli
+:uri-mscgen: http://www.mcternan.me.uk/mscgen/
+:uri-nomnoml: http://nomnoml.com
+:uri-nwdiag: http://blockdiag.com/en/nwdiag/index.html
+:uri-packetdiag: http://blockdiag.com/en/nwdiag/index.html
+:uri-phantomjs: http://phantomjs.org
+:uri-pikchr: https://pikchr.org
+:uri-plantuml: http://plantuml.sourceforge.net
+:uri-py-plantuml: https://code.google.com/p/asciidoc-plantuml/
+:uri-python: https://www.python.org
+:uri-rackdiag: http://blockdiag.com/en/nwdiag/index.html
+:uri-seqdiag: http://blockdiag.com/en/seqdiag/index.html
+:uri-shaape: https://github.com/christiangoltz/shaape
+:uri-smcat: https://github.com/sverweij/state-machine-cat
+:uri-svgbob: https://github.com/ivanceras/svgbobrus
+:uri-symbolator: https://github.com/kevinpt/symbolator
+:uri-syntrax: https://kevinpt.github.io/syntrax/
+:uri-tikz: https://github.com/pgf-tikz/pgf
+:uri-umlet: http://www.umlet.com/
+:uri-vega: https://vega.github.io/vega/
+:uri-vegalite: https://vega.github.io/vega-lite/
+:uri-wavedrom: http://wavedrom.com
+:uri-wavedromeditor: https://github.com/wavedrom/wavedrom.github.io/releases
+:uri-wavedromcli: https://github.com/wavedrom/cli

data/examples/features.adoc

@@ -150,7 +150,7 @@ results in a block with the correct caption and id applied to it.
 Asciidoctor-diagram also supports the various diagram block in block macro form.
 These are macros of the form `<name>::<target>[<attrlist>]`.
 
-In asciidoctor-diagram the macro names are identical to the block styles: `ditaa`, `graphivz` and `plantuml`
+In asciidoctor-diagram the macro names are identical to the block styles: `ditaa`, `graphviz` and `plantuml`
 The target is the path to the file containing the diagram source code.
 When the target is a relative path it is resolved with respect to the location of the document being processed.
 The attribute list behaves mostly the same as with the block styles.

data/lib/asciidoctor-diagram.rb

@@ -2,7 +2,9 @@ require_relative 'asciidoctor-diagram/a2s'
 require_relative 'asciidoctor-diagram/blockdiag'
 require_relative 'asciidoctor-diagram/bpmn'
 require_relative 'asciidoctor-diagram/bytefield'
+require_relative 'asciidoctor-diagram/diagrams'
 require_relative 'asciidoctor-diagram/ditaa'
+require_relative 'asciidoctor-diagram/dpic'
 require_relative 'asciidoctor-diagram/erd'
 require_relative 'asciidoctor-diagram/gnuplot'
 require_relative 'asciidoctor-diagram/graphviz'
@@ -11,11 +13,13 @@ require_relative 'asciidoctor-diagram/meme'
 require_relative 'asciidoctor-diagram/mermaid'
 require_relative 'asciidoctor-diagram/msc'
 require_relative 'asciidoctor-diagram/nomnoml'
+require_relative 'asciidoctor-diagram/pikchr'
 require_relative 'asciidoctor-diagram/plantuml'
 require_relative 'asciidoctor-diagram/salt'
 require_relative 'asciidoctor-diagram/shaape'
 require_relative 'asciidoctor-diagram/smcat'
 require_relative 'asciidoctor-diagram/svgbob'
+require_relative 'asciidoctor-diagram/symbolator'
 require_relative 'asciidoctor-diagram/syntrax'
 require_relative 'asciidoctor-diagram/tikz'
 require_relative 'asciidoctor-diagram/umlet'

data/lib/asciidoctor-diagram/a2s/converter.rb

@@ -13,13 +13,13 @@ module Asciidoctor
         [:svg]
       end
 
-      def collect_options(source, name)
+      def collect_options(source)
         options = {}
-        options[:sx] = source.attr('scalex', nil, name)
-        options[:sy] = source.attr('scaley', nil, name)
-        options[:scale] = source.attr('scale', nil, name)
-        options[:noblur] = source.attr('noblur', nil, name) == 'true'
-        options[:font] = source.attr('fontfamily', nil, name)
+        options[:sx] = source.attr('scalex')
+        options[:sy] = source.attr('scaley')
+        options[:scale] = source.attr('scale')
+        options[:noblur] = source.attr('noblur') == 'true'
+        options[:font] = source.attr('fontfamily')
         options
       end
 
@@ -50,6 +50,10 @@ module Asciidoctor
           args
         end
       end
+
+      def native_scaling?
+        true
+      end
     end
   end
 end

data/lib/asciidoctor-diagram/blockdiag/converter.rb

@@ -19,7 +19,7 @@ module Asciidoctor
           cmd_name = self.class.const_get(:TOOL)
           alt_cmd_name = "#{cmd_name}3"
 
-          font_path = source.attr('fontpath', nil, cmd_name)
+          font_path = source.attr('fontpath')
 
           generate_stdin(source.find_command(cmd_name, :alt_cmds => [alt_cmd_name]), format.to_s, source.to_s) do |tool_path, output_path|
             args = [tool_path, '-a', '-o', Platform.native_path(output_path), "-T#{format.to_s}"]

data/lib/asciidoctor-diagram/bpmn/converter.rb

@@ -15,11 +15,11 @@ module Asciidoctor
         [:png, :svg, :pdf, :jpeg]
       end
 
-      def collect_options(source, name)
+      def collect_options(source)
         options = {}
 
-        options[:width] = source.attr('width', nil, name)
-        options[:height] = source.attr('height', nil, name)
+        options[:width] = source.attr('width')
+        options[:height] = source.attr('height')
 
         options
       end

data/lib/asciidoctor-diagram/diagram_converter.rb

@@ -7,13 +7,21 @@ module Asciidoctor
         raise NotImplementedError.new
       end
 
-      def collect_options(source, name)
+      def wrap_source(source)
+        source
+      end
+
+      def collect_options(source)
         {}
       end
 
       def convert(source, format, options)
         raise NotImplementedError.new
       end
+
+      def native_scaling?
+        false
+      end
     end
   end
 end

data/lib/asciidoctor-diagram/diagram_processor.rb

@@ -3,6 +3,7 @@ require 'asciidoctor/extensions'
 require 'digest'
 require 'json'
 require 'fileutils'
+require 'pathname'
 require_relative 'diagram_source.rb'
 require_relative 'http/converter'
 require_relative 'version'
@@ -30,8 +31,6 @@ module Asciidoctor
         host_class.extend(ClassMethods)
       end
 
-      DIAGRAM_PREFIX = 'diagram'
-
       IMAGE_PARAMS = {
           :svg => {
               :encoding => Encoding::UTF_8,
@@ -62,14 +61,14 @@ module Asciidoctor
         location = parent.document.reader.cursor_at_mark
 
         normalised_attributes = attributes.inject({}) { |h, (k, v)| h[normalise_attribute_name(k)] = v; h }
-        source = create_source(parent, reader_or_target, normalised_attributes)
-
         converter = config[:converter].new
 
+        source = converter.wrap_source(create_source(parent, reader_or_target, normalised_attributes))
+
         supported_formats = converter.supported_formats
 
         begin
-          format = source.attributes.delete('format') || source.attr('format', nil, name) || source.attr('format', supported_formats[0], DIAGRAM_PREFIX)
+          format = source.attributes.delete('format') || source.global_attr('format', supported_formats[0])
           format = format.to_sym if format.respond_to?(:to_sym)
 
           raise "Format undefined" unless format
@@ -91,7 +90,7 @@ module Asciidoctor
           block.assign_caption(caption, 'figure')
           block
         rescue => e
-          case source.attr('on-error', 'log', DIAGRAM_PREFIX)
+          case source.global_attr('on-error', 'log')
           when 'abort'
             raise e
           else
@@ -145,10 +144,9 @@ module Asciidoctor
 
       def create_image_block(parent, source, format, converter)
         image_name = "#{source.image_name}.#{format}"
-        image_dir = image_output_dir(parent)
-        cache_dir = cache_dir(parent)
-        image_file = parent.normalize_system_path image_name, image_dir
-        metadata_file = parent.normalize_system_path "#{image_name}.cache", cache_dir
+
+        image_file = parent.normalize_system_path(image_name, image_output_dir(parent))
+        metadata_file = parent.normalize_system_path("#{image_name}.cache", cache_dir(source, parent))
 
         if File.exist? metadata_file
           metadata = File.open(metadata_file, 'r') {|f| JSON.load(f, nil, :symbolize_names => true, :create_additions => false) }
@@ -157,25 +155,27 @@ module Asciidoctor
         end
 
         image_attributes = source.attributes
-        options = converter.collect_options(source, name)
+        options = converter.collect_options(source)
 
         if !File.exist?(image_file) || source.should_process?(image_file, metadata) || options != metadata[:options]
           params = IMAGE_PARAMS[format]
 
-          server_url = source.attr('server-url', nil, name) || source.attr('server-url', nil, DIAGRAM_PREFIX)
+          server_url = source.global_attr('server-url')
           if server_url
-            server_type = source.attr('server-type', nil, name) || source.attr('server-type', 'plantuml', DIAGRAM_PREFIX)
+            server_type = source.global_attr('server-type')
             converter = HttpConverter.new(server_url, server_type.to_sym, converter)
           end
 
-          options = converter.collect_options(source, name)
+          options = converter.collect_options(source)
           result = converter.convert(source, format, options)
 
           result.force_encoding(params[:encoding])
 
           metadata = source.create_image_metadata
           metadata[:options] = options
-          metadata[:width], metadata[:height] = params[:decoder].get_image_size(result)
+
+          allow_image_optimisation = source.attr('optimise', 'true') == 'true'
+          result, metadata[:width], metadata[:height] = params[:decoder].post_process_image(result, allow_image_optimisation)
 
           FileUtils.mkdir_p(File.dirname(image_file)) unless Dir.exist?(File.dirname(image_file))
           File.open(image_file, 'wb') {|f| f.write result}
@@ -184,14 +184,8 @@ module Asciidoctor
           File.open(metadata_file, 'w') {|f| JSON.dump(metadata, f)}
         end
 
-        image_attributes['target'] = source.attr('data-uri', nil, true) ? image_file : image_name
-        if format == :svg
-          svg_type = source.attr('svg-type', nil, name) || source.attr('svg-type', nil, DIAGRAM_PREFIX)
-          image_attributes['opts'] = svg_type if svg_type && svg_type != 'static'
-        end
-
         scale = image_attributes['scale']
-        if scalematch = /(\d+(?:\.\d+))/.match(scale)
+        if !converter.native_scaling? && scalematch = /([0-9]+(?:\.[0-9]+)?)/.match(scale)
           scale_factor = scalematch[1].to_f
         else
           scale_factor = 1.0
@@ -207,25 +201,58 @@ module Asciidoctor
           end
         end
 
-        image_attributes['alt'] ||= if title_text = image_attributes['title']
-                                      title_text
-                                    elsif target = image_attributes['target']
-                                      (File.basename(target, File.extname(target)) || '').tr '_-', ' '
-                                    else
-                                      'Diagram'
-                                    end
+        parent.document.register(:images, image_name)
 
-        image_attributes['alt'] = parent.sub_specialchars image_attributes['alt']
+        node = Asciidoctor::Block.new parent, :image, :content_model => :empty, :attributes => image_attributes
 
-        parent.document.register(:images, image_name)
-        if (scaledwidth = image_attributes['scaledwidth'])
+        alt_text = node.attr('alt')
+        alt_text ||= if title_text = image_attributes['title']
+                       title_text
+                     elsif target = image_attributes['target']
+                       (File.basename(target, File.extname(target)) || '').tr '_-', ' '
+                     else
+                       'Diagram'
+                     end
+        alt_text = parent.sub_specialchars(alt_text)
+
+        node.set_attr('alt', alt_text)
+
+        if (scaledwidth = node.attr('scaledwidth'))
           # append % to scaledwidth if ends in number (no units present)
           if DIGIT_CHAR_RANGE.include?((scaledwidth[-1] || 0).ord)
-            image_attributes['scaledwidth'] = %(#{scaledwidth}%)
+            node.set_attr('scaledwidth', %(#{scaledwidth}%))
+          end
+        end
+
+        use_absolute_path = source.attr('data-uri', nil, true)
+
+        if format == :svg
+          svg_type = source.global_attr('svg-type')
+          case svg_type
+            when nil, 'static'
+            when 'inline', 'interactive'
+              node.set_option(svg_type)
+              use_absolute_path = true
+            else
+              raise "Unsupported SVG type: #{svg_type}"
+          end
+        end
+
+        if use_absolute_path
+          node.set_attr('target', image_file)
+        else
+          node.set_attr('target', image_name)
+
+          if source.global_attr('autoimagesdir')
+            image_path = Pathname.new(image_file)
+            output_path = Pathname.new(parent.normalize_system_path(output_dir(parent)))
+
+            imagesdir = image_path.relative_path_from(output_path).dirname.to_s
+            node.set_attr('imagesdir', imagesdir)
           end
         end
 
-        Asciidoctor::Block.new parent, :image, :content_model => :empty, :attributes => image_attributes
+        node
       end
 
       def scale(size, factor)
@@ -238,33 +265,50 @@ module Asciidoctor
         end
       end
 
+      # Returns the image output directory as an absolute path
       def image_output_dir(parent)
-        document = parent.document
-
-        images_dir = parent.attr('imagesoutdir', nil, true)
+        images_out_dir = parent.attr('imagesoutdir', nil, true)
 
-        if images_dir
-          base_dir = nil
+        if images_out_dir
+          resolve_path(parent, images_out_dir)
         else
-          base_dir = parent.attr('outdir', nil, true) || doc_option(document, :to_dir)
           images_dir = parent.attr('imagesdir', nil, true)
+          output_dir = output_dir(parent)
+          resolve_path(parent, images_dir, output_dir)
         end
+      end
+
+      # Returns the cache directory as an absolute path
+      def cache_dir(source, parent)
+        cache_dir = source.global_attr('cachedir')
+        if cache_dir
+          resolve_path(parent, cache_dir)
+        else
+          output_dir = output_dir(parent)
+          resolve_path(parent, '.asciidoctor/diagram', output_dir)
+        end
+      end
 
-        parent.normalize_system_path(images_dir, base_dir)
+      # Returns the general output directory for Asciidoctor as an absolute path
+      def output_dir(parent)
+        resolve_path(parent, parent.attr('outdir', nil, true) || doc_option(parent.document, :to_dir))
       end
 
-      def cache_dir(parent)
-        document = parent.document
-        cache_dir = '.asciidoctor/diagram'
-        base_dir = parent.attr('outdir', nil, true) || doc_option(document, :to_dir)
-        parent.normalize_system_path(cache_dir, base_dir)
+      def resolve_path(parent, path, base_dir = nil)
+        if path.nil?
+          # Resolve the base dir itself
+          parent.document.path_resolver.system_path(base_dir)
+        else
+          # Resolve the path with respect to the base dir
+          parent.document.path_resolver.system_path(path, base_dir)
+        end
       end
 
       def create_literal_block(parent, source, format, converter)
         literal_attributes = source.attributes
         literal_attributes.delete('target')
 
-        options = converter.collect_options(source, name)
+        options = converter.collect_options(source)
         result = converter.convert(source, format, options)
 
         result.force_encoding(Encoding::UTF_8)
@@ -309,7 +353,7 @@ module Asciidoctor
       include DiagramProcessor
 
       def self.inherited(subclass)
-        subclass.name_positional_attributes ['target', 'format']
+        subclass.name_positional_attributes ['format']
       end
 
       def apply_target_subs(parent, target)

data/lib/asciidoctor-diagram/diagram_source.rb

@@ -1,3 +1,4 @@
+require 'asciidoctor/logging'
 require_relative 'util/which'
 
 module Asciidoctor
@@ -5,6 +6,12 @@ module Asciidoctor
     # This module describes the duck-typed interface that diagram sources must implement. Implementations
     # may include this module but it is not required.
     module DiagramSource
+      include Asciidoctor::Logging
+
+      def diagram_type
+        raise NotImplementedError.new
+      end
+
       def image_name
         raise NotImplementedError.new
       end
@@ -12,23 +19,31 @@ module Asciidoctor
       # @return [String] the String representation of the source code for the diagram
       # @abstract
       def code
+        @code ||= load_code
+      end
+
+      def load_code
         raise NotImplementedError.new
       end
 
+      def global_attr(name, default_value = nil)
+        attr(name) || attr(name, default_value, 'diagram')
+      end
+
       # Get the value for the specified attribute. First look in the attributes on
       # this document and return the value of the attribute if found. Otherwise, if
       # this document is a child of the Document document, look in the attributes of the
       # Document document and return the value of the attribute if found. Otherwise,
       # return the default value, which defaults to nil.
       #
-      # @param name [String, Symbol] the name of the attribute to lookup
+      # @param name [String, Symbol, Array] the name(s) of the attribute to lookup
       # @param default_value [Object] the value to return if the attribute is not found
       # @inherit [Boolean, String] indicates whether to check for the attribute on the AsciiDoctor::Document if not found on this document.
       #                            When a non-nil String is given the an attribute name "#{inherit}-#{name}" is looked for on the document.
       #
       # @return the value of the attribute or the default value if the attribute is not found in the attributes of this node or the document node
       # @abstract
-      def attr(name, default_value = nil, inherit = nil)
+      def attr(name, default_value = nil, inherit = diagram_type)
         raise NotImplementedError.new
       end
 
@@ -75,14 +90,42 @@ module Asciidoctor
         if config.key? cmd_var
           cmd_path = config[cmd_var]
         else
-          cmd_path = attr_names.map { |attr_name| attr(attr_name, nil, true) }.find { |attr| !attr.nil? }
-
-          unless cmd_path && File.executable?(cmd_path)
-            cmd_paths = cmd_names.map do |c|
-              ::Asciidoctor::Diagram::Which.which(c, :path => options[:path])
-            end
-
-            cmd_path = cmd_paths.reject { |c| c.nil? }.first
+          logger.debug "Finding '#{cmd}' in attributes"
+          cmd_path = attr_names.map { |attr_name|
+                                 attr = attr(attr_name, nil, true)
+                                 if logger.debug? && attr
+                                   logger.debug "Found value '#{attr}' in attribute '#{attr_name}'" if attr
+                                 end
+                                 attr
+                               }
+                               .reject { |attr| attr.nil? }
+                               .map { |attr|
+                                 expanded = File.expand_path(attr)
+                                 if logger.debug? && attr != expanded
+                                   logger.debug "Expanded '#{attr}' to '#{expanded}'"
+                                 end
+                                 expanded
+                               }
+                               .select { |path|
+                                 executable = File.executable?(path)
+                                 if logger.debug?
+                                   logger.debug "Is '#{path}' executable? #{executable}"
+                                 end
+                                 executable
+                               }
+                               .first
+
+          unless cmd_path
+            logger.debug "Finding '#{cmd}' in environment"
+            cmd_path = cmd_names.map { |c|
+                             path = ::Asciidoctor::Diagram::Which.which(c, :path => options[:path])
+                             if logger.debug? && path
+                               logger.debug "Found '#{path}' in environment"
+                             end
+                             path
+                           }
+                           .reject { |path| path.nil? }
+                           .first
           end
 
           config[cmd_var] = cmd_path
@@ -113,6 +156,10 @@ module Asciidoctor
         @attributes = attributes
       end
 
+      def diagram_type
+        @block_processor.name.downcase
+      end
+
       def resolve_path target, start = base_dir
         @parent_block.normalize_system_path(target, start)
       end
@@ -125,18 +172,22 @@ module Asciidoctor
         attr('target', 'diag-' + checksum)
       end
 
-      def attr(name, default_value = nil, inherit = nil)
+      def attr(name, default_value = nil, inherit = diagram_type)
         name = name.to_s if ::Symbol === name
+        name = [name] unless name.is_a?(Enumerable)
 
-        value = @attributes[name]
+        value = name.lazy.map { |n| @attributes[n] }.reject { |v| v.nil? }.first
 
         if value.nil? && inherit
-          case inherit
-          when String, Symbol
-            value = @parent_block.attr("#{inherit.to_s}-#{name}", default_value, true)
-          else
-            value = @parent_block.attr(name, default_value, inherit)
+          inherited_values = name.lazy.map do |n|
+            case inherit
+            when String, Symbol
+              @parent_block.attr("#{inherit.to_s}-#{n}", default_value, true)
+            else
+              @parent_block.attr(n, default_value, inherit)
+            end
           end
+          value = inherited_values.reject { |v| v.nil? }.first
         end
 
         value || default_value
@@ -186,8 +237,8 @@ module Asciidoctor
         @reader = reader
       end
 
-      def code
-        @code ||= @parent_block.apply_subs(@reader.lines, resolve_diagram_subs).join("\n")
+      def load_code
+        @parent_block.apply_subs(@reader.lines, resolve_diagram_subs).join("\n")
       end
     end
 
@@ -220,11 +271,7 @@ module Asciidoctor
         (@file_name && File.mtime(@file_name) > File.mtime(image_file)) || super
       end
 
-      def code
-        @code ||= read_code
-      end
-
-      def read_code
+      def load_code
         if @file_name
           lines = File.readlines(@file_name)
           lines = prepare_source_array(lines)