asciidoctor-diagram 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 429a698716d0d5cbdd6c579abe0b4b17294fa556
-  data.tar.gz: 410fa9e1683434a389503f90bfc251fff713bb7a
+  metadata.gz: 53e5f49e32e9d7eb46c59351821d534c1c445d2a
+  data.tar.gz: 68d55cdeaf3c3cd604f05d4a01dae3493eed442a
 SHA512:
-  metadata.gz: 811c4850dd0328025f961fac469ee7e9ae78635dae58a127884e3110bac4d6a031996ba9a7c77a44f592b4088152658f0cbcf257e921e7b78e629dc8cc5511e4
-  data.tar.gz: e8b358410c6107145a70edd1e819595a46283fa6d177a8534ec65946ce1476217bd49894a169bd56d8967ae1227b2731cf84164fc64bf0467f7020a3a2c35006
+  metadata.gz: a285a19658bd2c38b7dbbb52b481cc447de29793ac3ac488db9c9e0d1fbbb46730009806ba7325f4b7463b9b3e125ca682742fbdc4130e42fac09fa59ab1310d
+  data.tar.gz: 8dd9dc235bd58831981752976f04f86e902372efd90afc6b8ce5ff815d9c31711587860b9e2498677b8b8490aa0cf2371a8d97c29d745ec60c287a6915a4ce03

data/CHANGELOG.adoc

@@ -0,0 +1,22 @@
+= Asciidoctor-diagram Changelog
+
+== 1.1.0
+
+Enhancements::
+
+  * Add support for `graphviz` blocks which may contain diagrams specified using the Graphviz DOT language
+  * The location of the Graphviz `dot` executable can now be specified using the `graphvizdot` document attribute
+  * Add support for `ditaa`, `graphivz` and `plantuml` block macros
+
+== 1.0.1
+
+Bug Fixes::
+
+  * Corrections to gemspec
+
+== 1.0.0
+
+Initial release::
+
+  * Provides Asciidoctor extension for `ditaa` and `plantuml` blocks
+  * PlantUML skin parameters can be injected from an external file using the `plantumlconfig` document attribute

data/README.adoc

@@ -33,17 +33,18 @@ In your script you can then either require one or more of the following files:
 
 . `asciidoctor-diagram`: to enable all the diagramming extensions
 . `asciidoctor-diagram/ditaa`: to enable the ditaa extension
+. `asciidoctor-diagram/graphviz`: to enable the graphviz extension
 . `asciidoctor-diagram/plantuml`: to enable the plantuml extension
 
-Requiring one or more of these files will automatically register the extensions for all processed documents. If you need
-more fine grained control over when the extensions are enabled or not, `asciidoctor-diagram/ditaa/extension` and `asciidoctor-diagram/plantuml/extension` can be used instead.
-This loads the extensions themselves but does not register them.
+Requiring one or more of these files will automatically register the extensions for all processed documents.
+If you need more fine grained control over when the extensions are enabled or not, `asciidoctor-diagram/ditaa/extension`, `asciidoctor-diagram/graphviz/extension` and `asciidoctor-diagram/plantuml/extension` can be used instead.
+These load the extensions themselves but do not register them.
 You should then register the extensions yourself at the appropriate time using the `Asciidoctor::Extensions` API.
 
 === Using the extensions
 
-Once the extensions are enabled support for `plantuml` and/or `ditaa` blocks becomes available for your documents.
-Detailed descriptions of the supported syntax inside these blocks is available on the http://plantuml.sourceforge.net/[PlantUML] and http://ditaa.sourceforge.net/[ditaa] websites.
+Once the extensions are enabled support for `ditaa`, `graphviz` and `plantuml` blocks becomes available for your documents.
+Detailed descriptions of the supported syntax inside these blocks is available on the http://plantuml.sourceforge.net/[PlantUML], http://www.graphviz.org/content/dot-language[Graphviz] and http://ditaa.sourceforge.net/[ditaa] websites.
 
 At this point you can start adding diagrams to your application, like the following example:
 
@@ -64,7 +65,7 @@ DiagramBlock <|-- PlantUmlBlock
 The diagram blocks support the following attributes:
 
 . `target` (or 2nd position): the basename of the file to generate. If not specified an auto-generated name will be used.
-. `format` (or 3rd position): the output format. PlantUML blocks support `png`, `svg` and `txt`. Ditaa only supports `png`.
+. `format` (or 3rd position): the output format. PlantUML blocks support `png`, `svg` and `txt`. Graphviz supports `png` and `svg`. Ditaa only supports `png`.
 
 == Contributing
 

data/examples/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gem "asciidoctor-diagram", :path => ".."

data/examples/README.adoc

@@ -0,0 +1,6 @@
+= Asciidoctor-diagram Examples
+
+This directory contains a number of example files that illustrate how to use the asciidoctor-diagram extension.
+Asciidoctor 0.1.4 does not support loading extensions via the command line.
+In order to process the examples correctly you should use the `build-example.rb` script.
+This wraps the regular `asciidoctor` command line tool and automatically loads the asciidoctor-diagram extension.

data/examples/build_example.rb

@@ -0,0 +1,9 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'asciidoctor'
+require 'asciidoctor/cli/options'
+require 'asciidoctor/cli/invoker'
+require 'asciidoctor-diagram'
+
+Asciidoctor::Cli::Invoker.new(*ARGV).invoke!

data/examples/design.adoc

@@ -0,0 +1,78 @@
+= The design of Asciidoctor-diagram
+
+This document explains the design of Asciidoctor-diagram using PlantUML syntax.
+A detailed explanation of the PlantUML syntax is out scope for this document.
+This can be found on the http://www.plantuml.com[PlantUML web site].
+
+Asciidoctor-diagram is a simple Asciidoctor extension that enables embedding of diagrams inside asciidoc documents using various plain text diagram syntaxes.
+The current version of Asciidoctor-diagram support the Ditaa, Graphviz DOT and PlantUML syntax.
+
+Asciidoctor-diagram enables a number of new block types using the Asciidoctor `BlockProcessor` extension API.
+
+The main logic of the diagram generation is provided by the `DiagramBlock` module.
+This includes the shared options for the various blocks, checksum calculation of the diagram source code, cache validation and attribute generation for the generated output blocks.
+The DiagramBlock module also provides a means to register diagram output formats.
+
+When registering an output format, the registering code must specify a number of control parameters.
+The first parameter is the format name which controls when the generator is activated.
+The generator that is registered first determines the default format for the block.
+The second parameter is the output type of the generator.
+This is either `:image` or `:literal`.
+This parameter controls what type of block the `DiagramBlock` code will generate.
+Finally, a block should be provided that generates the diagram and returns it as a String.
+When called these blocks will receive the diagram source code and the parent Block as arguments.
+
+The actual `BlockProcessor` implementations include the `DiagramBlock` module and the appropriate generator module.
+The remainder of the implementation consists of registering format.
+
+The diagram below illustrates the relationship between the various classes and modules.
+
+.Asciidoctor-diagram class diagram
+[plantuml, "classes", align="center"]
+----
+namespace asciidoctor.extensions {
+  class BlockProcessor
+}
+
+namespace asciidoctor.diagram {
+  asciidoctor.extensions.BlockProcessor <|-- DitaaBlock
+  class DitaaGenerator << (M,#FF7700) >>
+
+  asciidoctor.extensions.BlockProcessor <|-- GraphvizBlock
+  asciidoctor.extensions.BlockProcessor <|-- PlantUmlBlock
+  class PlantUmlGenerator << (M,#FF7700) >>
+
+  class DiagramBlock << (M,#FF7700) >>
+
+  DitaaBlock --|> DitaaGenerator
+  DitaaBlock --|> DiagramBlock
+  GraphvizBlock --|> PlantUmlGenerator
+  GraphvizBlock --|> DiagramBlock
+  PlantUmlBlock --|> PlantUmlGenerator
+  PlantUmlBlock --|> DiagramBlock
+}
+----
+
+When Asciidoctor process a document it will invoke the block processors at the appropriate moment.
+The sequence of method calls for a Ditaa block is shown below.
+
+.Processing a Ditaa block
+[plantuml, "processing", align="center"]
+----
+Lexer->DiagramBlock : process
+activate DiagramBlock #FFBBBB
+
+DiagramBlock -> DiagramBlock: create_image_block
+activate DiagramBlock #DarkSalmon
+
+DiagramBlock -> DiagramBlock: code_checksum
+
+DiagramBlock -> DitaaGenerator: ditaa
+activate DitaaGenerator
+DiagramBlock <-- DitaaGenerator: image as String
+deactivate DitaaGenerator
+deactivate DiagramBlock
+
+Lexer <-- DiagramBlock: generated Block
+deactivate DiagramBlock
+----

data/examples/features.adoc

@@ -0,0 +1,164 @@
+= Asciidoctor-diagram features
+
+This document explains the various features of asciidoctor-diagram blocks using ditaa diagrams as an example.
+
+== Simple diagrams
+
+To mark a block as a diagram the appropriate style should be applied. This can be either `ditaa`, `graphviz` or `plantuml`.
+These styles can be applied to literal, listing or open blocks.
+
+A basic ditaa listing can be written as follows:
+
+---------
+[ditaa]
+----
+                   +-------------+
+                   | asciidoctor |-------+
+                   |  diagram    |       |
+                   +-------------+       | png out
+                       ^                 |
+                       | ditaa in        |
+                       |                 v
+ +--------+   +--------+----+    /---------------\
+ |        | --+ asciidoctor +--> |               |
+ |  Text  |   +-------------+    |Beatiful output|
+ |Document|   |   !magic!   |    |               |
+ |     {d}|   |             |    |               |
+ +---+----+   +-------------+    \---------------/
+     :                                   ^
+     |          Lots of work             |
+     +-----------------------------------+
+----
+---------
+
+results in the following image.
+
+[ditaa]
+----
+                   +-------------+
+                   | asciidoctor |-------+
+                   |  diagram    |       |
+                   +-------------+       | png out
+                       ^                 |
+                       | ditaa in        |
+                       |                 v
+ +--------+   +--------+----+    /---------------\
+ |        | --+ asciidoctor +--> |               |
+ |  Text  |   +-------------+    |Beatiful output|
+ |Document|   |   !magic!   |    |               |
+ |     {d}|   |             |    |               |
+ +---+----+   +-------------+    \---------------/
+     :                                   ^
+     |          Lots of work             |
+     +-----------------------------------+
+----
+
+== Controlling the file name
+
+The image above gets the file name `58372f7d2ceffae9e91fd0a7cbb080b6.png`.
+That long number is the checksum of the source code that was calculated by asciidoctor-diagram.
+If you want to give your generated files a more meaningful name, simply fill in the `target` attribute.
+
+This can be done by either specifying it as the first positional attribute or as a named attribute.
+Both examples below would result in a file called `ditaa-diagram.png`.
+
+---------
+[ditaa, "ditaa-diagram"]
+----
+<snip>
+----
+
+[ditaa, target="ditaa-diagram"]
+----
+<snip>
+----
+---------
+
+== Choosing an output format
+
+By default images are generated in `PNG` format.
+This can be overridden by defining the `format` (or 2nd positional) attribute.
+The set of supported formats is diagram type dependent.
+`ditaa` only supports the `png` format.
+`graphviz` supports `png` and `svg`.
+`plantuml` supports `png`, `svg` and `txt`.
+
+The `txt` format is perhaps a bit non-obvious.
+This generates an ascii art version of the UML diagrams.
+
+The following Graphviz DOT script
+
+---------
+[graphviz, "dot_example", "svg"]
+----
+graph ethane {
+     C_0 -- H_0 [type=s];
+     C_0 -- H_1 [type=s];
+     C_0 -- H_2 [type=s];
+     C_0 -- C_1 [type=s];
+     C_1 -- H_3 [type=s];
+     C_1 -- H_4 [type=s];
+     C_1 -- H_5 [type=s];
+}
+----
+---------
+
+generates an SVG representation of an ethane molecule footnote:[From http://en.wikipedia.org/wiki/DOT_(graph_description_language)#A_simple_example]
+
+[graphviz, "dot_example", "svg"]
+----
+graph ethane {
+     C_0 -- H_0 [type=s];
+     C_0 -- H_1 [type=s];
+     C_0 -- H_2 [type=s];
+     C_0 -- C_1 [type=s];
+     C_1 -- H_3 [type=s];
+     C_1 -- H_4 [type=s];
+     C_1 -- H_5 [type=s];
+}
+----
+
+== Using standard asciidoc features
+
+Any remaining other attributes that are specified on a diagram block are copied over to the generated block.
+This means you can use the regular http://asciidoctor.org/docs/user-manual/#put-images-in-their-place[asciidoc positioning attributes] to place the diagrams where you want to.
+
+Block titles and block ids can also be applied in the same way to diagram blocks.
+
+As an example, the following block
+
+--------
+[[plan]]
+.My plan to conquer the world
+[plantuml, align="center"]
+--------
+
+results in a block with the correct caption and id applied to it.
+
+[[plan]]
+.My plan to conquer the world
+[plantuml, "activity_diagram", "svg", align="center"]
+----
+(*) --> "Create an Asciidoctor extension"
+"Create an Asciidoctor extension" --> " ? "
+" ? " --> "Profits!"
+"Profits!" --> (*)
+----
+
+== Loading diagrams from external files
+
+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`
+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.
+The only difference is that the `target` attribute is not supported.
+Instead the name of the generated image is derived from the target propery of the macro.
+
+The previous example in block macro form would look something like this with the text from the block located in a file called `activity_diagram.txt` instead of inline in the document.
+
+----
+plantuml:activity_diagram.txt[format="svg", align="center"]
+----

data/lib/asciidoctor-diagram.rb

@@ -1,2 +1,3 @@
 require 'asciidoctor-diagram/ditaa'
+require 'asciidoctor-diagram/graphviz'
 require 'asciidoctor-diagram/plantuml'

data/lib/asciidoctor-diagram/ditaa.rb

@@ -4,4 +4,5 @@ require_relative 'version'
 Asciidoctor::Extensions.register do
   require_relative 'ditaa/extension'
   block :ditaa, Asciidoctor::Diagram::DitaaBlock
+  block_macro :ditaa, Asciidoctor::Diagram::DitaaBlockMacro
 end

data/lib/asciidoctor-diagram/ditaa/extension.rb

@@ -1,64 +1,37 @@
-require_relative '../diagram'
-require_relative '../java'
-require_relative '../png'
-require_relative '../svg'
+require_relative '../util/diagram'
+require_relative 'generator'
 
 module Asciidoctor
   module Diagram
-    DITAA_JAR_PATH = File.expand_path File.join('../..', 'ditaamini0_9.jar'), File.dirname(__FILE__)
-
-    class DitaaBlock < DiagramBlock
-      option :contexts, [:listing, :literal, :open]
-      option :content_model, :simple
-      option :pos_attrs, ['target', 'format']
-      option :default_attrs, {'format' => 'png'}
-
-      def name
-        "Ditaa"
-      end
-
-      def allowed_formats
-        @allowed_formats ||= [:png]
-      end
-
-      def generate_image(parent, diagram_code, format)
-        ditaa(diagram_code)
-      end
+    module DitaaBase
+      include DitaaGenerator
 
       private
 
-      Java.classpath << DITAA_JAR_PATH
-
-      def ditaa(code, *flags)
-        Java.load
-
-        cmd = ['-e', 'UTF-8']
-        cmd += flags if flags
-
-        bytes = code.encode(Encoding::UTF_8).bytes.to_a
-        bis = Java.java.io.ByteArrayInputStream.new(Java.array_to_java_array(bytes, :byte))
-        bos = Java.java.io.ByteArrayOutputStream.new
-        result_code = Java.org.stathissideris.ascii2image.core.CommandLineConverter.convert(Java.array_to_java_array(cmd, :string), bis, bos)
-        bis.close
-        bos.close
-
-        result = Java.string_from_java_bytes(bos.toByteArray)
+      def register_formats
+        register_format(:png, :image) do |c|
+          ditaa(c)
+        end
+      end
+    end
 
-        raise "Ditaa image generation failed: #{result}" unless result_code == 0
+    class DitaaBlock < Asciidoctor::Extensions::BlockProcessor
+      include DiagramProcessorBase
+      include DitaaBase
 
-        result
+      def initialize(context, document, opts = {})
+        super
+        register_formats()
       end
+    end
 
-      def get_default_flags(parent)
-        flags = []
-
-        document = parent.document
-        config = document.attributes['plantumlconfig']
-        if config
-          flags += ['-config', File.expand_path(config, document.attributes['docdir'])]
-        end
+    class DitaaBlockMacro < Asciidoctor::Extensions::BlockMacroProcessor
+      include DiagramProcessorBase
+      include DitaaBase
 
-        flags
+      def initialize(context, document, opts = {})
+        super
+        register_formats()
       end
     end
   end

data/lib/asciidoctor-diagram/ditaa/generator.rb

@@ -0,0 +1,31 @@
+require_relative '../util/java'
+
+module Asciidoctor
+  module Diagram
+    module DitaaGenerator
+      private
+
+      DITAA_JAR_PATH = File.expand_path File.join('../..', 'ditaamini0_9.jar'), File.dirname(__FILE__)
+      Java.classpath << DITAA_JAR_PATH
+
+      def ditaa(code)
+        Java.load
+
+        args = ['-e', 'UTF-8']
+
+        bytes = code.encode(Encoding::UTF_8).bytes.to_a
+        bis = Java.java.io.ByteArrayInputStream.new(Java.array_to_java_array(bytes, :byte))
+        bos = Java.java.io.ByteArrayOutputStream.new
+        result_code = Java.org.stathissideris.ascii2image.core.CommandLineConverter.convert(Java.array_to_java_array(args, :string), bis, bos)
+        bis.close
+        bos.close
+
+        result = Java.string_from_java_bytes(bos.toByteArray)
+
+        raise "Ditaa image generation failed: #{result}" unless result_code == 0
+
+        result
+      end
+    end
+  end
+end