asciidoctor-diagram 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d373774bdb564cd5b002d0c09fa3473f9e5760c3
-  data.tar.gz: 37ac247cb289425bed03821a56573d7d2b45e9c4
+  metadata.gz: ae72b79905bac3a581f14f6ddc1023cb4063186e
+  data.tar.gz: 9ea96d64e9424ad728e094d3820e560c0e520f14
 SHA512:
-  metadata.gz: 40e342aa5f7f6625d260b7de22d0bc68dbfcc859b8f5d0dc0e260be05e937f3b39ded65596aabfc09dc084103d086aa8a5e8c75c7d913ee53fa4b9ea2d876a90
-  data.tar.gz: c5355e1ad0d749eb88204ac3b824cf53e91a6fa6f286fdc92a7a6b74655a6b9a40b2e300c2b62a1f23230fa43773279524552df8bdf0b97b89b7b2c2bac97ab3
+  metadata.gz: 3a3f7185995285e5d766c140d3a280f5628b819f8c976017a54a2df97fd908a08239566cc7c4aefd96934ad569d006f32ce2fea81533a4f612fdb46101d88c19
+  data.tar.gz: c43fafdb81683e2eb63cd5f41756f1d9fe7ece075cb7b4ef9d2a2616e51db19a180f132ffc5413c0bfcb9616ea0ef081c081755a0106e799da1175aba1705706

data/CHANGELOG.adoc

@@ -1,5 +1,20 @@
 = Asciidoctor-diagram Changelog
 
+== Development
+
+== 1.5.0
+
+Enhancements::
+
+  * Issue #98: Automatically detect Actdiag, Blockdiag, Nwdiag and Seqdiag executables from Python 3.x Debian packages.
+  * Issue #100: Support specifying the layout engine for `dot` (`-K<engine>`) using the `layout` attribute on `graphviz` blocks. 
+  * Issue #102: Generate cache files in `asciidoctor/diagram` to avoid cluttering the output directory.
+  * Issue #105: Support substitutions in diagram blocks.
+  * Issue #107: Improve error reporting when Mermaid diagram generation fails.
+  * Issue #112: Update PlantUML to revision 8043 (19/06/2016)
+  * Issue #114: Asciidoctor Diagram now requires Asciidoctor if it hasn't been loaded already.
+  * Issue #116: Resolve relative paths in PlantUML !include directives
+
 == 1.4.0
 
 Enhancements::

data/README.adoc

@@ -1,101 +1,183 @@
 = Asciidoctor Diagram
-Pepijn Van_Eeckhoudt
-
-Asciidoctor Diagram is a set of extensions for http://asciidoctor.org[Asciidoctor], the Ruby-based AsciiDoc processor.
-These extensions allow you to embed plain text diagrams inside your AsciiDoc documents using one of the following syntaxes:
-
-- http://blockdiag.com[BlockDiag, SeqDiag, ActDiag, NwDiag]
-- http://ditaa.sourceforge.net[Ditaa].
-- http://www.graphviz.org/content/dot-language[GraphViz DOT]
-- http://knsv.github.io/mermaid/[Mermaid]
-- http://plantuml.sourceforge.net[PlantUML]
-- https://github.com/christiangoltz/shaape[Shaape]
-- http://wavedrom.com[WaveDrom]
-
-Additionally Asciidoctor Diagram includes a basic meme generator extension.
-
-The extension takes care of running the diagram processor to generate the images from the input text and insert them into the rendered document.
-
-This gem was inspired by the https://code.google.com/p/asciidoc-plantuml/[AsciiDoc PlantUML filter] for AsciiDoc Python.
-
+Pepijn Van_Eeckhoudt <https://github.com/pepijnve[@pepijnve]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
+:description: README for the Asciidoctor Diagram extension for Asciidoctor.
+ifdef::env-github[:toc: macro]
+ifndef::env-site[:toc: preamble]
+ifndef::imagesdir[:imagesdir: images]
+:icons: font
+:source-highlighter: coderay
+:source-language: asciidoc
+:table-caption!:
+:example-caption!:
+:figure-caption!:
+:check: icon:check[]
+ifdef::env-github[:check: :ballot_box_with_check:]
+ifndef::env-site[:status:]
+: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-ditaa: http://ditaa.sourceforge.net/
+:uri-dot: http://www.graphviz.org/content/dot-language
+:uri-graphviz: http://www.graphviz.org
+:uri-imagemagick: http://www.imagemagick.org
+:uri-java: http://java.sun.com
+:uri-mermaid: http://knsv.github.io/mermaid/
+:uri-nwdiag: http://blockdiag.com/en/nwdiag/index.html
+:uri-packetdiag: http://blockdiag.com/en/nwdiag/index.html
+:uri-phantomjs: http://phantomjs.org
+:uri-plantuml: http://plantuml.sourceforge.net
+:uri-py-plantuml: https://code.google.com/p/asciidoc-plantuml/
+: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-wavedrom: http://wavedrom.com
+:uri-wavedromeditor: https://github.com/wavedrom/wavedrom.github.io/releases
+:uri-wavedromcli: https://github.com/wavedrom/cli
+
+Asciidoctor Diagram is a set of Asciidoctor extensions that enable you to add diagrams, which you describe using plain text, to your AsciiDoc document.
+
+The extensions support BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag), Ditaa, GraphViz, Mermaid, PlantUML, Shaape and WaveDrom syntax.
+
+Each extension runs the diagram processor to generate an SVG, PNG, or TXT file from the input text.
+The generated file is then inserted into your converted document.
+
+Asciidoctor Diagram was inspired by the {uri-py-plantuml}[AsciiDoc PlantUML filter].
+
+Translations of the document are available in the following languages:
+
+* link:README_zh-CN.adoc[汉语]
+
+ifdef::status[]
+[discrete]
 == Status
 
 image:https://travis-ci.org/asciidoctor/asciidoctor-diagram.svg?branch=master["Linux Build Status", link="https://travis-ci.org/asciidoctor/asciidoctor-diagram"]
-
 image:https://ci.appveyor.com/api/projects/status/4r4gkk5gy3igs6nh/branch/master?svg=true["Windows Build Status", link="https://ci.appveyor.com/project/asciidoctor/asciidoctor-diagram"]
+image:https://img.shields.io/gem/v/asciidoctor-diagram.svg?label=gem%20version[Gem Version, link=https://rubygems.org/gems/asciidoctor-diagram]
+endif::status[]
 
-== Installation
-
-Add this line to your application's Gemfile:
+ifeval::["{toc-placement}" == "macro"]
+[discrete]
+== Contents
 
-```ruby
-gem 'asciidoctor-diagram'
-```
+toc::[title={blank}]
+endif::[]
 
-And then execute:
+== Installation
 
- $ bundle
+Asciidoctor Diagram is a RubyGem, which can be installed using the `gem` or `bundle` commands.
 
-Or install it yourself as:
+You can install the Asciidoctor Diagram gem by typing `gem install` in the CLI.
 
  $ gem install asciidoctor-diagram
 
-=== Additional Requirements
+by first adding the following entry to your project's [.path]_Gemfile_.
 
-Certain diagram types require other tools to be installed seperately.
+.Gemfile
+[source,ruby]
+----
+gem 'asciidoctor-diagram', '~> 1.4.0'
+----
 
-- Block/Seq/Act/Nw diag: the block/seq/act/nw diag Python packages
-- Graphviz: the http://www.graphviz.org[Graphviz] package
-- Meme: http://www.imagemagick.org[ImageMagick]
-- Mermaid: the http://knsv.github.io/mermaid[Mermaid] CLI and http://phantomjs.org[PhantomJS] 1.9.x
-- PlantUML: http://www.graphviz.org[Graphviz] package for certain diagram types.
-- Shaape: the Shaape Python package
-- WaveDrom: the https://github.com/wavedrom/wavedrom.github.io/releases[WaveDrom editor] application
+Then execute `bundle` in the CLI.
 
-== Usage
+ $ bundle
 
-=== Enable the extensions
+== Creating a Diagram
 
-The diagram extensions consist of a set of http://asciidoctor.org/docs/user-manual/#extension-points[block processors for Asciidoctor].
-In order to use extensions you should need to invoke Asciidoctor via the http://asciidoctor.org/docs/user-manual/#api[Ruby API].
-In your script you can then either require one or more of the following files:
+A diagram is written inside a literal block, which can accept several attributes.
 
-. `asciidoctor-diagram`: to enable all the diagramming extensions
-. `asciidoctor-diagram/blockdiag`: to enable the block/act/seq/nw diag extension
-. `asciidoctor-diagram/ditaa`: to enable the ditaa extension
-. `asciidoctor-diagram/graphviz`: to enable the graphviz extension
-. `asciidoctor-diagram/meme`: to enable the mermaid extension
-. `asciidoctor-diagram/mermaid`: to enable the mermaid extension
-. `asciidoctor-diagram/plantuml`: to enable the plantuml extension
-. `asciidoctor-diagram/shaape`: to enable the shaape extension
-. `asciidoctor-diagram/wavedrom`: to enable the wavedrom extension
+.Anatomy of a diagram
+----
+[diagram-type, generated-file-name, generated-image-format] // <1> <2> <3>
+.... // <4>
+Diagram in appropriate syntax
+....
+----
+<1> The first positional attribute in the attribute list specifies the diagram that is being used.
+<2> The second, optional positional attribute assigns a file name (i.e. `target`) to the generated diagram. If a target is not specified an auto-generated name will be used.
+<3> The third, optional positional attribute specifies the image format to create, specified as a three character file extension.
+<4> Place the attribute list directly on top of the delimited literal block (+....+). You can also use an open block as an alternative (`--`).
+
+The following diagram types and output formats are available:
+
+[cols=">,4*^",options="header"]
+|===
+|Diagram Type                |gif    |png    |svg    |txt
+|{uri-actdiag}[actdiag]      |       |{check}|{check}|
+|{uri-blockdiag}[blockdiag]  |       |{check}|{check}|
+|{uri-ditaa}[ditaa]          |       |{check}|       |
+|{uri-dot}[graphviz]         |       |{check}|{check}|
+|<<meme,meme>>               |{check}|{check}|       |
+|{uri-mermaid}[mermaid]      |       |{check}|{check}|
+|{uri-nwdiag}[nwdiag]        |       |{check}|{check}|
+|{uri-packetdiag}[packetdiag]|       |{check}|{check}|
+|{uri-plantuml}[plantuml]    |       |{check}|{check}|{check}
+|{uri-rackdiag}[rackdiag]    |       |{check}|{check}|
+|{uri-seqdiag}[seqdiag]      |       |{check}|{check}|
+|{uri-shaape}[shaape]        |       |{check}|{check}|
+|{uri-wavedrom}[wavedrom]    |       |{check}|{check}|
+|===
+
+The example below illustrates the structure of a basic ditaa block written directly in an AsciiDoc document.
+
+.Basic ditaa block
+[source]
+----
+[ditaa]
+....
+                   +-------------+
+                   | Asciidoctor |-------+
+                   |   diagram   |       |
+                   +-------------+       | PNG out
+                       ^                 |
+                       | ditaa in        |
+                       |                 v
+ +--------+   +--------+----+    /---------------\
+ |        | --+ Asciidoctor +--> |               |
+ |  Text  |   +-------------+    |   Beautiful   |
+ |Document|   |   !magic!   |    |    Output     |
+ |     {d}|   |             |    |               |
+ +---+----+   +-------------+    \---------------/
+     :                                   ^
+     |          Lots of work             |
+     +-----------------------------------+
+....
+----
 
-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.
+The ditaa block above results in the following generated diagram.
 
-=== Using the extensions
+.Rendered ditaa diagram
+image::asciidoctor-diagram-process.png[Asciidoctor Diagram process diagram,650,319]
 
-Once the extensions are enabled the following block types becomes available for your documents:
+The rendered ditaa diagram above gets the file name `58372f7d2ceffae9e91fd0a7cbb080b6.png`.
+That long number is the checksum of the source code calculated by asciidoctor-diagram.
+If you want to give your generated files a more meaningful name, fill in the `target` attribute.
 
-- `blockdiag`, `actdiag`, `seqdiag`, `nwdiag`, `rackdiag` and `packetdiag`
-- `ditaa`
-- `graphviz`
-- `meme`
-- `mermaid`
-- `plantuml`
-- `shaape`
-- `wavedrom`
+This can be done by either specifying it as the second positional attribute or as a named attribute.
+Both examples below would result in a file called `ditaa-diagram.png`.
 
-Detailed descriptions of the supported syntax inside these blocks is available on websites of the respective projects.
+....
+[ditaa, "ditaa-diagram"]
+----
+<snip>
+----
 
-At this point you can start adding diagrams to your application.
-Here's an example to get you started:
+[ditaa, target="ditaa-diagram"]
+----
+<snip>
+----
+....
+
+
+The example below illustrates the structure of a basic PlantUML block written directly in an AsciiDoc document.
 
+.PlantUML Diagram Syntax
+[source]
 ----
-["plantuml", "asciidoctor-diagram-classes", "png"]
----------------------------------------------------------------------
+[plantuml, diagram-classes, png] // <1> <2> <3>
+....
 class BlockProcessor
 class DiagramBlock
 class DitaaBlock
@@ -104,42 +186,125 @@ class PlantUmlBlock
 BlockProcessor <|-- DiagramBlock
 DiagramBlock <|-- DitaaBlock
 DiagramBlock <|-- PlantUmlBlock
----------------------------------------------------------------------
+....
 ----
+<1> The diagram is written in PlantUML so the first positional attribute is assigned the `plantuml` diagram type.
+<2> The name of the generated diagram file (target) is written in the second positional attribute.
+<3> The output format is entered in the third positional attribute.
+
+.Rendered PlantUML diagram
+image::asciidoctor-diagram-classes.png[Asciidoctor Diagram classes diagram]
+
+== 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
 
-All the diagram blocks except `meme` support the following attributes:
+== Advanced Usage
 
-. `target` (1st positional attribute): the basename of the file to generate. If not specified an auto-generated name will be used.
-. `format` (2nd positional attribute): the output format. PlantUML blocks support `png`, `svg` and `txt`. Graphviz, Shaape and BlockDiag support `png` and `svg`. Ditaa only supports `png`.
+=== Enabling Extensions
 
-Once you have all of this in place and your original AsciiDoc file contains a diagram block, it's time to build it into an HTML file with Asciidoctor Diagram magic! 
-When executing Asciidoctor, you must reference the Adciidoctor Diagram library, otherwise your diagram blocks won't be recognized as such. When executing Asciidoctor from the command line, do it using the -r parameter to reference this external library:
+In your program, you can either load and register the entire set of diagram extensions
 
+[source,ruby]
 ----
-$ asciidoctor -r asciidoctor-diagram doc.adoc
+require 'asciidoctor-diagram'
 ----
 
-If you don't want to embed your diagram code in your document then you can use the diagram extension as block macros.
-The target of diagram block macro should refer to the file containing the diagram source code.
-The attributes for the block macros are the same as for the inline blocks.
-The example above in block macro form becomes
+or load and register each extension individually.
 
+[source,ruby]
 ----
-plantuml::mydiagram.puml["asciidoctor-diagram-classes", "png"]
+require 'asciidoctor-diagram/<extension_name>'
 ----
 
-=== The meme extension
+`<extension_name>` can be one of `blockdiag`, `ditaa`, `graphviz`, `meme`, `mermaid`, `plantuml`, `shaape`, or `wavedrom`.
 
-The meme extension provides a basic 'Advice Animal' style image generator.
+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, `asciidoctor-diagram/<extension_name>/extension` can be used instead.
+This loads the extensions but does not register it in the Asciidoctor extension registry.
+You can then manually register the extensions at the appropriate times using the `Asciidoctor::Extensions` API.
+
+This document explains the various features of asciidoctor-diagram blocks using ditaa diagrams as an example.
+
+=== Diagram Block Macro
+
+The diagram extensions can also be used in in block macro form.
+
+.Anatomy of a diagram block macro
+----
+block-name::source-file-name[generated-file-extension] // <1> <2> <3>
+----
+<1> The macro name is the same as the block name in the block form.
+<2> The source file name specifies the external file that contains the diagram source code.
+<3> The first, optional, positional attribute assigns the file extension (i.e. `format`) to the generated diagram.
+
+When the source file name is a relative path it is resolved with respect to the location of the document being processed.
+
+=== Image Output Location
+
+When Asciidoctor Diagram writes images to disk it will go over the following options in order to determine where to write the files.
+
+. `\{imagesoutdir\}` if the `imagesoutdir` attribute has been specified
+. `\{outdir\}/\{imagesdir\}` if the `outdir` attribute has been specified
+. `\{to_dir\}/\{imagesdir\}` if the `to_dir` attribute has been specified
+. `\{base_dir\}/\{imagesdir\}`
+
+=== Specifying Diagram Generator Paths
+
+Asciidoctor Diagram depends on external tools to generates images.
+In most cases it will locate these tools automatically for you by looking for specific executables in each directory in the `PATH` environment variable.
+In case you've installed a tool in a way where the executable is not in the `PATH`, you can override its location manually using document attributes.
+The following table lists the tools that are required for each diagram type, the location where they can be downloaded and the document attribute you can use to override their locations.
+
+[cols=">,2*<",options="header"]
+|===
+   |Diagram Type |Tool                                                                  |Attribute
+   |actdiag      |{uri-actdiag}[ActDiag]                                                |`actdiag`
+   |blockdiag    |{uri-blockdiag}[BlockDiag]                                            |`blockdiag`
+   |ditaa        |{uri-java}[Java]                                                      |`java`
+   |graphviz     |{uri-graphviz}[GraphViz]                                              |`dot` or `graphvizdot`
+   |meme         |{uri-imagemagick}[ImageMagick]                                        |`convert` and `identify`
+   |mermaid      |{uri-mermaid}[Mermaid]                                                |`mermaid`
+   |nwdiag       |{uri-nwdiag}[NwDiag]                                                  |`nwdiag`
+   |packetdiag   |{uri-nwdiag}[NwDiag]                                                  |`packetdiag`
+   |plantuml     |{uri-java}[Java]                                                      |`java`
+   |rackdiag     |{uri-nwdiag}[NwDiag]                                                  |`rackdiag`
+   |seqdiag      |{uri-seqdiag}[SeqDiag]                                                |`seqdiag`
+   |shaape       |{uri-shaape}[Shaape]                                                  |`shaape`
+.2+|wavedrom     |{uri-wavedromeditor}[WaveDrom Editor]                                 |`wavedrom`
+                 |{uri-wavedromcli}[WaveDrom CLI] and {uri-phantomjs}[PhantomJS]        |`wavedrom` and `phantomjs`
+|===
+
+If for instance you installed `actdiag` in `/home/me/actdiag/bin` and this path is not included in the `PATH` you can specify its location on the command line
+
+ $ asciidoctor -a actdiag=/home/me/actdiag/bin/actdiag -r asciidoctor-diagram sample.adoc
+
+[[meme]]
+=== The Meme Extension
+
+The meme extension provides a basic '`Advice Animal`' style image generator.
 It's usage is easiest to explain with an example.
 
 ----
-meme::doge.jpg[Perhaps haters...,Just hate to \\ love?]
+meme::yunoguy.jpg[Doc writers,Y U NO \\ AsciiDoc]
 ----
 
 The target of the block macro tells the extension which image to use as background.
 The first two positional attributes are `top` and `bottom` and are used for the top and bottom label.
-Occurrences of ` \\ ` are interpreted as line breaks.
+Occurrences of `\\` surrounded by whitespace are interpreted as line breaks.
 
 The block macro also supports the following named attributes:
 
@@ -150,11 +315,3 @@ The block macro also supports the following named attributes:
 . `options`: a comma separate list of flags that modify the image rendering. Currently only `noupcase` is supported which disable upper casing the labels.
 . `target` (3rd positional attribute): the basename of the file to generate. If not specified an auto-generated name will be used.
 . `format` (4th positional attribute): the output image format. The meme extension supports `png` and `gif`.
-
-== Contributing
-
-. Fork it
-. Create your feature branch (`git checkout -b my-new-feature`)
-. Commit your changes (`git commit -am 'Add some feature'`)
-. Push to the branch (`git push origin my-new-feature`)
-. Create new Pull Request

data/README_zh-CN.adoc

@@ -0,0 +1,333 @@
+= Asciidoctor Diagram
+Pepijn Van_Eeckhoudt <https://github.com/pepijnve[@pepijnve]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
+:translators: D瓜哥
+ifdef::env-github[Translated by: {translators}]
+:description: Asciidoctor 的 扩展 Asciidoctor Diagram 的说明文档。
+ifdef::env-github[:toc: macro]
+ifndef::env-site[:toc: preamble]
+ifndef::imagesdir[:imagesdir: images]
+:icons: font
+:source-highlighter: coderay
+:source-language: asciidoc
+:table-caption!:
+:example-caption!:
+:figure-caption!:
+:check: icon:check[]
+ifdef::env-github[:check: :ballot_box_with_check:]
+ifndef::env-site[:status:]
+: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-ditaa: http://ditaa.sourceforge.net/
+:uri-dot: http://www.graphviz.org/content/dot-language
+:uri-graphviz: http://www.graphviz.org
+:uri-imagemagick: http://www.imagemagick.org
+:uri-java: http://java.sun.com
+:uri-mermaid: http://knsv.github.io/mermaid/
+:uri-nwdiag: http://blockdiag.com/en/nwdiag/index.html
+:uri-packetdiag: http://blockdiag.com/en/nwdiag/index.html
+:uri-phantomjs: http://phantomjs.org
+:uri-plantuml: http://plantuml.sourceforge.net
+:uri-py-plantuml: https://code.google.com/p/asciidoc-plantuml/
+: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-wavedrom: http://wavedrom.com
+:uri-wavedromeditor: https://github.com/wavedrom/wavedrom.github.io/releases
+:uri-wavedromcli: https://github.com/wavedrom/cli
+
+Asciidoctor Diagram 是一组 Asciidoctor 扩展，它可以让你向 AsciiDoc 文档中添加图表，而这些图表则是使用纯文本描述的。
+
+扩展支持 BlockDiag （BlockDiag、SeqDiag、ActDiag、NwDiag）， Ditaa、GraphViz、Mermaid、PlantUML、Shaape 和 WaveDrom 语法。
+
+每个扩展都是运行图表处理器，然后根据输入文本来生成一个 SVG、PNG 或 TXT 文件。
+生成的文件随后插入到你处理过的文档中。
+
+Asciidoctor Diagram 是受 {uri-py-plantuml}[AsciiDoc PlantUML filter] 启发而产生的项目。
+
+该文档有如下语言的翻译版：
+
+* link:README.adoc[English]
+
+TIP: 本文档是 link:README.adoc[README] 的翻译版。如果发现有什么不一致或者错误的地方，请以原文档为准。
+
+ifdef::status[]
+[discrete]
+[[status]]
+== 状态
+
+image:https://travis-ci.org/asciidoctor/asciidoctor-diagram.svg?branch=master["Linux Build Status", link="https://travis-ci.org/asciidoctor/asciidoctor-diagram"]
+image:https://ci.appveyor.com/api/projects/status/4r4gkk5gy3igs6nh/branch/master?svg=true["Windows Build Status", link="https://ci.appveyor.com/project/asciidoctor/asciidoctor-diagram"]
+image:https://img.shields.io/gem/v/asciidoctor-diagram.svg?label=gem%20version[Gem Version, link=https://rubygems.org/gems/asciidoctor-diagram]
+endif::status[]
+
+ifeval::["{toc-placement}" == "macro"]
+[discrete]
+== Contents
+
+toc::[title={blank}]
+endif::[]
+
+[[installation]]
+== 安装
+
+Asciidoctor Diagram 是一个 RubyGem ，它可以使用 `gem` 或 `bundle` 命令来安装。
+
+你可以通过在命令行中输入 `gem install` 来安装 Asciidoctor Diagram。
+
+ $ gem install asciidoctor-diagram
+
+或者，先在项目的 [.path]_Gemfile_ 文件中添加如下内容：
+
+.Gemfile
+[source,ruby]
+----
+gem 'asciidoctor-diagram', '~> 1.4.0'
+----
+
+然后在命令中执行 `bundle` 命令。
+
+ $ bundle
+
+[[creating-a-diagram]]
+== 创建图表
+
+一个图表可以直接书写在文档内部的文本块中，这个文本块还可以接受几个属性。
+
+.图表骨架
+----
+[diagram-type, generated-file-name, generated-image-format] // <1> <2> <3>
+.... // <4>
+符合相应语法的图表
+....
+----
+<1> 属性列表中第一个位置的属性指明所使用的图表类型。
+<2> 第二个位置的属性指明生成文件的文件名。如果没有指明，则默认使用原文件名来命名新生成的文件名。
+<3> 第三个位置的属性指明生成图表的格式，类似三个字符的文件扩展名。
+<4> 将属性列表直接放在文本块分隔符（ +....+ ）上面。你也可以使用开放块（ `--` ）作为另一个选择。
+
+图表类型以及可用的输出格式如下：
+
+[cols=">,4*^",options="header"]
+|===
+|图表类型                     |gif    |png    |svg    |txt
+|{uri-actdiag}[actdiag]      |       |{check}|{check}|
+|{uri-blockdiag}[blockdiag]  |       |{check}|{check}|
+|{uri-ditaa}[ditaa]          |       |{check}|       |
+|{uri-dot}[graphviz]         |       |{check}|{check}|
+|<<meme,meme>>               |{check}|{check}|       |
+|{uri-mermaid}[mermaid]      |       |{check}|{check}|
+|{uri-nwdiag}[nwdiag]        |       |{check}|{check}|
+|{uri-packetdiag}[packetdiag]|       |{check}|{check}|
+|{uri-plantuml}[plantuml]    |       |{check}|{check}|{check}
+|{uri-rackdiag}[rackdiag]    |       |{check}|{check}|
+|{uri-seqdiag}[seqdiag]      |       |{check}|{check}|
+|{uri-shaape}[shaape]        |       |{check}|{check}|
+|{uri-wavedrom}[wavedrom]    |       |{check}|{check}|
+|===
+
+下面的例子演示一个直接书写在 AsciiDoc 文档中的基本 ditaa 块的结构。
+
+.基本 ditaa 块
+[source]
+----
+[ditaa]
+....
+                   +-------------+
+                   | Asciidoctor |-------+
+                   |   diagram   |       |
+                   +-------------+       | PNG out
+                       ^                 |
+                       | ditaa in        |
+                       |                 v
+ +--------+   +--------+----+    /---------------\
+ |        | --+ Asciidoctor +--> |               |
+ |  Text  |   +-------------+    |   Beautiful   |
+ |Document|   |   !magic!   |    |    Output     |
+ |     {d}|   |             |    |               |
+ +---+----+   +-------------+    \---------------/
+     :                                   ^
+     |          Lots of work             |
+     +-----------------------------------+
+....
+----
+
+上面的 ditaa 块生成的图表如下图所示：
+
+.渲染 ditaa 图表
+image::asciidoctor-diagram-process.png[Asciidoctor Diagram 处理图表,650,319]
+
+上面渲染后的图表得到的文件名为 `58372f7d2ceffae9e91fd0a7cbb080b6.png`。
+这串长数字是源码的校验和，由 asciidoctor-diagram 计算所得。
+如果想给所生成的文件一个更具有意义的名字，请在 `target` 属性中填写。
+
+这可以很容易通过指明第二个位置的属性或者一个命名属性来指明文件名。
+下面的两个例子将生成文件名为 `ditaa-diagram.png` 的文件。
+
+....
+[ditaa, "ditaa-diagram"]
+----
+<snip>
+----
+
+[ditaa, target="ditaa-diagram"]
+----
+<snip>
+----
+....
+
+下面的例子演示一个直接书写在 AsciiDoc 文档中的基本 PlantUML 块的结构。
+
+.PlantUML 图表语法
+[source]
+----
+[plantuml, diagram-classes, png] // <1> <2> <3>
+....
+class BlockProcessor
+class DiagramBlock
+class DitaaBlock
+class PlantUmlBlock
+
+BlockProcessor <|-- DiagramBlock
+DiagramBlock <|-- DitaaBlock
+DiagramBlock <|-- PlantUmlBlock
+....
+----
+<1> 这个图表是使用 PlantUML 书写的，所以第一个位置的属性应该被指明为 `plantuml` 图表类型。
+<2> 生成的图表文件的名字被书写在第二个位置的属性。
+<3> 生成的文件格式放置在第三个属性位置。
+
+.渲染后的 PlantUML 图表
+image::asciidoctor-diagram-classes.png[Asciidoctor Diagram 类图]
+
+[[generating-a-diagram-from-a-terminal]]
+== 从终端中生成图表
+
+你可以使用 `-r` 标识在终端中加载 Asciidoctor Diagram。
+
+ $ asciidoctor -r asciidoctor-diagram sample.adoc
+
+你也可以在其他的转化器中使用 Asciidoctor Diagram，例如 Asciidoctor EPUB。
+Asciidoctor-epub3 也是通过 `-r` 标识来加载。
+
+ $ asciidoctor -r asciidoctor-diagram -r asciidoctor-epub3 -b epub3 sample.adoc
+
+或者，你也可以通过 `asciidoctor-epub3` 命令来调用 Asciidoctor 和 EPUB  转化器。
+这个命令隐式地设置 `-r` 和 `-b` 标识用于 EPUB3 输出。
+
+ $ asciidoctor-epub3 -r asciidoctor-diagram sample.adoc
+
+[[advanced-usage]]
+== 高级用法
+
+[[enabling-extensions]]
+=== 启用扩展
+
+在你的程序中，你可以加载并注册整个图表扩展集合。
+
+[source,ruby]
+----
+require 'asciidoctor-diagram'
+----
+
+或者，加载并注册每一个单独的扩展。
+
+[source,ruby]
+----
+require 'asciidoctor-diagram/<extension_name>'
+----
+
+`<extension_name>` 可以是 `blockdiag`、`ditaa`、`graphviz`、`meme`、`mermaid`、`plantuml`、`shaape` 或 `wavedrom`。
+
+加载一个或多个这些文件将为所有需要处理的文档自动注册这些扩展。
+
+如果你需要更细粒度控制扩展的可用性， 则可以使用 `asciidoctor-diagram/<extension_name>/extension`。
+它将加载扩展但是不会向 Asciidoctor 扩展注册表中注册。
+你可以在恰当的时机使用 `Asciidoctor::Extensions` API 来手动注册扩展。
+
+本文档使用 ditaa 图表作为示例，演示了 asciidoctor-diagram 块的一系列特性。
+
+[[diagram-block-macro]]
+=== 图表块宏
+
+图表扩展还可以以块宏的形式来使用。
+
+.图表块宏的骨架
+----
+宏名::原文件名[生成的文件扩展名] // <1> <2> <3>
+----
+<1> 宏名和以块形式的块名相同。
+<2> 原文件名指明包含图表源代码的外部文件。
+<3> 第一个可选的属性指明用于生成图表的文件扩展名（也就是 `format` ）
+
+源文件的名字是相对正在处理的文件的位置的相对路径。
+// When the source file name is a relative path it is resolved with respect to the location of the document being processed. 怎么翻译？
+
+[[image-output-location]]
+=== 图表输出位置
+
+当 Asciidoctor Diagram 将图片写入磁盘时，它将根据如下选项依次来决定将文件写入到何处。
+
+. `\{imagesoutdir\}` 如果 `imagesoutdir` 属性被指明
+. `\{outdir\}/\{imagesdir\}` 如果 `outdir` 属性被指明
+. `\{to_dir\}/\{imagesdir\}` 如果 `to_dir` 属性被指明
+. `\{base_dir\}/\{imagesdir\}`
+
+[[specifying-diagram-generator-paths]]
+=== 指定图表输出路径
+
+Asciidoctor Diagram 依赖外部工具来生成图片。
+大多数情况下，它会自动从 `PATH` 环境变量指定的每一个路径中查找定位有特定可执行的工具。
+// In most cases it will locate these tools automatically for you by looking for specific executables in each directory in the `PATH` environment variable.
+如果你安装的工具不在 `PATH` 指明的路径中，你可以通过手动指明相关属性来覆盖工具的定位位置。
+下面的表格指明每一个图表类型必须依赖的工具，工具被安装的位置和用于覆盖默认位置的文档属性。
+
+[cols=">,2*<",options="header"]
+|===
+   |Diagram Type |Tool                                                                  |Attribute
+   |actdiag      |{uri-actdiag}[ActDiag]                                                |`actdiag`
+   |blockdiag    |{uri-blockdiag}[BlockDiag]                                            |`blockdiag`
+   |ditaa        |{uri-java}[Java]                                                      |`java`
+   |graphviz     |{uri-graphviz}[GraphViz]                                              |`dot` 或 `graphvizdot`
+   |meme         |{uri-imagemagick}[ImageMagick]                                        |`convert` 和 `identify`
+   |mermaid      |{uri-mermaid}[Mermaid]                                                |`mermaid`
+   |nwdiag       |{uri-nwdiag}[NwDiag]                                                  |`nwdiag`
+   |packetdiag   |{uri-nwdiag}[NwDiag]                                                  |`packetdiag`
+   |plantuml     |{uri-java}[Java]                                                      |`java`
+   |rackdiag     |{uri-nwdiag}[NwDiag]                                                  |`rackdiag`
+   |seqdiag      |{uri-seqdiag}[SeqDiag]                                                |`seqdiag`
+   |shaape       |{uri-shaape}[Shaape]                                                  |`shaape`
+.2+|wavedrom     |{uri-wavedromeditor}[WaveDrom Editor]                                 |`wavedrom`
+                 |{uri-wavedromcli}[WaveDrom CLI] 和 {uri-phantomjs}[PhantomJS]        |`wavedrom` 和 `phantomjs`
+|===
+
+举例说明一下，假如你将 `actdiag` 安装在 `/home/me/actdiag/bin` 下，这路径不在 `PATH` 范围内，则你可以在命令行中指明它的位置：
+
+ $ asciidoctor -a actdiag=/home/me/actdiag/bin/actdiag -r asciidoctor-diagram sample.adoc
+
+[[meme]]
+=== Meme 扩展
+
+meme 扩展提供了一个基本的 '`Advice Animal`' 风格的图片生成器。
+使用一个例子就能非常方便地解释它的用法。
+
+----
+meme::yunoguy.jpg[Doc writers,Y U NO \\ AsciiDoc]
+----
+
+宏块的目的是告诉扩展使用哪些图像作为背景。
+// The target of the block macro tells the extension which image to use as background.
+头两个位置的属性是 `top` 和 `bottom`，用于标题的顶部和底部。
+出现在 `\\` 周围的空白符将被解释为换行符。
+
+块宏海支持如下的命名熟悉：
+
+. `fillColor`：文字的填充颜色。默认为 `white`。
+. `strokeColor`：文本的轮廓颜色。默认为 `black`。
+. `strokeWidth`：文本轮廓的宽度。默认为 `2`。
+. `font`: 文本的字体外观。默认为 `Impact`。
+. `options`：逗号分隔的标识列表，用于修改图片的渲染。目前只支持 `noupcase`， 它可以禁用大写的标签。
+// . `options`: a comma separate list of flags that modify the image rendering. Currently only `noupcase` is supported which disable upper casing the labels.
+. `target` （第三位可选参数）：生成文件的文件名。如果没有指定，则将会使用自动生成的文件名。
+. `format` （第四位可选参数）：生成图片的格式。meme 扩展支持 `png` 和 `gif`。、