asciidoctor-diagram 2.0.1 → 2.1.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (103) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.adoc +84 -1
  3. data/README.adoc +25 -493
  4. data/Rakefile +1 -1
  5. data/docs/antora.yml +3 -0
  6. data/{images → docs/modules/ROOT/images}/asciidoctor-diagram-classes.png +0 -0
  7. data/docs/modules/ROOT/images/asciidoctor-diagram-process.png +0 -0
  8. data/docs/modules/ROOT/pages/index.adoc +21 -0
  9. data/docs/modules/ROOT/partials/advanced.adoc +311 -0
  10. data/docs/modules/ROOT/partials/create_diagram.adoc +132 -0
  11. data/docs/modules/ROOT/partials/generate.adoc +15 -0
  12. data/docs/modules/ROOT/partials/installation.adoc +19 -0
  13. data/docs/modules/ROOT/partials/uris.adoc +40 -0
  14. data/examples/features.adoc +1 -1
  15. data/lib/asciidoctor-diagram.rb +5 -0
  16. data/lib/asciidoctor-diagram/a2s/converter.rb +10 -6
  17. data/lib/asciidoctor-diagram/blockdiag/converter.rb +1 -1
  18. data/lib/asciidoctor-diagram/bpmn/converter.rb +4 -4
  19. data/lib/asciidoctor-diagram/bytefield.rb +7 -0
  20. data/lib/asciidoctor-diagram/bytefield/converter.rb +26 -0
  21. data/lib/asciidoctor-diagram/bytefield/extension.rb +14 -0
  22. data/lib/asciidoctor-diagram/diagram_converter.rb +9 -1
  23. data/lib/asciidoctor-diagram/diagram_processor.rb +99 -53
  24. data/lib/asciidoctor-diagram/diagram_source.rb +73 -26
  25. data/lib/asciidoctor-diagram/diagrams.rb +7 -0
  26. data/lib/asciidoctor-diagram/diagrams/converter.rb +49 -0
  27. data/lib/asciidoctor-diagram/diagrams/extension.rb +14 -0
  28. data/lib/asciidoctor-diagram/ditaa/converter.rb +20 -7
  29. data/lib/asciidoctor-diagram/ditaa/ditaa-1.3.20.jar +0 -0
  30. data/lib/asciidoctor-diagram/dpic.rb +7 -0
  31. data/lib/asciidoctor-diagram/dpic/converter.rb +30 -0
  32. data/lib/asciidoctor-diagram/dpic/extension.rb +14 -0
  33. data/lib/asciidoctor-diagram/gnuplot/converter.rb +8 -8
  34. data/lib/asciidoctor-diagram/graphviz/converter.rb +2 -2
  35. data/lib/asciidoctor-diagram/http/converter.rb +26 -12
  36. data/lib/asciidoctor-diagram/http/server.rb +11 -6
  37. data/lib/asciidoctor-diagram/lilypond/converter.rb +13 -3
  38. data/lib/asciidoctor-diagram/meme/converter.rb +24 -18
  39. data/lib/asciidoctor-diagram/mermaid/converter.rb +45 -14
  40. data/lib/asciidoctor-diagram/msc/converter.rb +2 -2
  41. data/lib/asciidoctor-diagram/pikchr.rb +7 -0
  42. data/lib/asciidoctor-diagram/pikchr/converter.rb +33 -0
  43. data/lib/asciidoctor-diagram/pikchr/extension.rb +14 -0
  44. data/lib/asciidoctor-diagram/plantuml/converter.rb +69 -44
  45. data/lib/asciidoctor-diagram/plantuml/plantuml-1.3.20.jar +0 -0
  46. data/lib/asciidoctor-diagram/smcat/converter.rb +3 -3
  47. data/lib/asciidoctor-diagram/svgbob/converter.rb +29 -1
  48. data/lib/asciidoctor-diagram/symbolator.rb +7 -0
  49. data/lib/asciidoctor-diagram/symbolator/converter.rb +23 -0
  50. data/lib/asciidoctor-diagram/symbolator/extension.rb +14 -0
  51. data/lib/asciidoctor-diagram/syntrax/converter.rb +9 -6
  52. data/lib/asciidoctor-diagram/tikz/converter.rb +20 -1
  53. data/lib/asciidoctor-diagram/umlet/converter.rb +11 -2
  54. data/lib/asciidoctor-diagram/util/cli.rb +29 -3
  55. data/lib/asciidoctor-diagram/util/cli_generator.rb +31 -9
  56. data/lib/asciidoctor-diagram/util/gif.rb +2 -2
  57. data/lib/asciidoctor-diagram/util/java.rb +118 -3
  58. data/lib/asciidoctor-diagram/util/java_jruby.rb +4 -1
  59. data/lib/asciidoctor-diagram/util/java_socket.rb +8 -109
  60. data/lib/asciidoctor-diagram/util/pdf.rb +2 -2
  61. data/lib/asciidoctor-diagram/util/png.rb +2 -2
  62. data/lib/asciidoctor-diagram/util/server-1.3.20.jar +0 -0
  63. data/lib/asciidoctor-diagram/util/svg.rb +66 -18
  64. data/lib/asciidoctor-diagram/vega/converter.rb +2 -2
  65. data/lib/asciidoctor-diagram/version.rb +1 -1
  66. data/spec/a2s_spec.rb +5 -143
  67. data/spec/blockdiag_spec.rb +5 -203
  68. data/spec/bpmn_spec.rb +52 -92
  69. data/spec/bytefield_spec.rb +92 -0
  70. data/spec/diagrams_spec.rb +23 -0
  71. data/spec/ditaa_spec.rb +37 -143
  72. data/spec/dpic_spec.rb +19 -0
  73. data/spec/erd_spec.rb +5 -202
  74. data/spec/gnuplot_spec.rb +2 -255
  75. data/spec/graphviz_spec.rb +6 -145
  76. data/spec/lilypond_spec.rb +5 -143
  77. data/spec/mermaid_spec.rb +68 -210
  78. data/spec/msc_spec.rb +5 -202
  79. data/spec/nomnoml_spec.rb +6 -144
  80. data/spec/pikchr_spec.rb +69 -0
  81. data/spec/plantuml_spec.rb +151 -673
  82. data/spec/shaape_spec.rb +12 -224
  83. data/spec/shared_examples.rb +603 -0
  84. data/spec/smcat_spec.rb +5 -143
  85. data/spec/svgbob_spec.rb +5 -143
  86. data/spec/symbolator_spec.rb +23 -0
  87. data/spec/syntrax_spec.rb +7 -217
  88. data/spec/test_helper.rb +4 -28
  89. data/spec/tikz_spec.rb +68 -18
  90. data/spec/umlet_spec.rb +2 -58
  91. data/spec/vega_spec.rb +4 -117
  92. data/spec/wavedrom_spec.rb +2 -199
  93. metadata +87 -18
  94. data/README_zh-CN.adoc +0 -336
  95. data/images/asciidoctor-diagram-process.png +0 -0
  96. data/lib/batik-all-1.10.jar +0 -0
  97. data/lib/ditaa-1.3.14.jar +0 -0
  98. data/lib/ditaamini-0.12.jar +0 -0
  99. data/lib/jlatexmath-minimal-1.0.5.jar +0 -0
  100. data/lib/plantuml-1.3.14.jar +0 -0
  101. data/lib/plantuml.jar +0 -0
  102. data/lib/server-1.3.14.jar +0 -0
  103. data/spec/bpmn-example.xml +0 -44
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 2c23479ec496e71fd006564fec4e1ca6cf88bd09ae730437e39e3d2dab6554c8
4
- data.tar.gz: 583614138465d13c09a0134a888ecb513b27e9040d1d946fd62038c1421cfaf3
3
+ metadata.gz: 674abb9267b7d32b26a63f665dff96822efea03927e194109c6301cd14530b51
4
+ data.tar.gz: fb94061afb3aefd801ea7c23bdd4e1306e45bffbdaeeeff34fb6f53f5a131324
5
5
  SHA512:
6
- metadata.gz: 92fdb3bcfbf238bbcfc13f2ea84b5441c9db60c98e053bef529487351c82fb07192d44304661fd1ede94fa3286923029bb3e93f72c5bb5ffd3a8f8cbeda2227e
7
- data.tar.gz: bc7a9000e2ae1beeed9e61d538938241b6401a5aa4cff8bb5b9d15f8fe8dd7c4991b58ea326677feaf9f6e72f20c72961ce1286c53ed0704e5d48af102ad99e7
6
+ metadata.gz: 46b3d4f0ff19bf97ca232f4531fa94d7a56d102de08500254a916fded1e2232c905dc540cc4b3e76279a690f105b42782211dc9f93ea13eb3dce873d54708e1a
7
+ data.tar.gz: 17891073b283b12280e2d118cd3b66a253fd8e74f30a41cae7431b47cbb663fd74cf6b80fe9d463410d991b86c0d1d55dd29bc76afd37db1653d3cccb8abe3fe
data/CHANGELOG.adoc CHANGED
@@ -1,5 +1,88 @@
1
1
  = Asciidoctor-diagram Changelog
2
2
 
3
+ == 2.1.1
4
+
5
+ Enhancements::
6
+
7
+ * Issue #335: The PlantUML preprocessor is now run locally before delegating rendering to Kroki.
8
+ This avoids file not found errors when using the PlantUML `!include` directive.
9
+ * Issue #339: Add support for a `size-limit` attribute on PlantUML blocks that controls the maximum size of PlantUML diagrams.
10
+ * Issue #341: Add support for https://diagrams.mingrammer.com[Minigrammer Diagrams].
11
+
12
+ Bug Fixes::
13
+
14
+ * Issue #343: The PlantUML preprocessor is now used to resolve `!include` statements instead of using the previous logic provided by this gem.
15
+
16
+ == 2.1.0
17
+
18
+ Enhancements::
19
+
20
+ * Issue #226: Add initial support to delegate rendering of diagrams to https://kroki.io[kroki.io]. Add `:diagram-server-url: https://kroki.io/` and `:diagram-server-type: kroki_io` to your document to enable this.
21
+ * Issue #296: Support referring to the mmdc batch script on Windows using the `mmdc` (Mermaid) document attribute.
22
+ * Issue #312: Update PlantUML to v1.2021.0. +
23
+ Starting with version 2.1.0 you can now also override the bundled version of PlantUML with a different version.
24
+ If the `DIAGRAM_PLANTUML_CLASSPATH` environment variable is set, asciidoctor-diagram will parse this value as a series of paths to JAR files separated by the native path separator (`:` or `;`) and use those JAR files instead of the bundled ones.
25
+
26
+ Bug Fixes::
27
+
28
+ * Issue #308: Avoid changing the semantics of SVG documents during post processing.
29
+ * Issue #313: Remove unneeded dependency on bigdecimal.
30
+
31
+ == 2.0.5
32
+
33
+ Enhancements::
34
+
35
+ * Improve internal target path resolution logic
36
+ * TikZ diagrams can now add content to the LaTeX preamble by setting the `preamble` block attribute to `true`.
37
+ The preamble and diagram should be separated by a line consisting of `\~~~~`. (@colbyn)
38
+ * The `scale` attribute is now passed on to Mermaid. (@gustav-b)
39
+ * Issue #271: Launch UMLet directly using `java` instead of using the UMLet wrapper scripts or executables
40
+
41
+ Bug Fixes::
42
+
43
+ * Issue #294: Treat the first positional parameter of diagram block macros as the desired output format rather than as the target.
44
+
45
+ == 2.0.4
46
+
47
+ Enhancements::
48
+
49
+ * Issue #110: Added support for an experimental attribute `diagram-autoimagesdir` that sets per image node `imagesdir` values.
50
+
51
+ Bug Fixes::
52
+
53
+ * Issue #292: A regression in 2.0.3 caused SVG diagrams to get a zero width and height when documents were regenerated.
54
+
55
+ == 2.0.3
56
+
57
+ Enhancements::
58
+
59
+ * Issue #261: Ensure generated SVG diagrams always specify a view box
60
+ * Issue #284: Add support for HTTP redirect responses when using a rendering server
61
+ * Issue #290: Add support for Pikchr
62
+ * Add support for dpic
63
+ * Add support for Symbolator (@gsmecher)
64
+
65
+ Bug Fixes::
66
+
67
+ * Issue #247: Fix `svg-type`/`diagram-svg-type`.
68
+ * Issue #257: Avoid potential hangs when generating Mermaid diagrams
69
+
70
+ == 2.0.2
71
+
72
+ Enhancements::
73
+
74
+ * #260: Update PlantUML to v1.2020.6
75
+ * #270: Add support for svgbob options (@hackingotter)
76
+ * #268: Changing diagram attribute values will now also trigger image regeneration
77
+ * #276: Add support for bytefield-svg
78
+
79
+ Bug Fixes::
80
+
81
+ * Issue #253: Add support for PlantUML `atxt` and `utxt` output formats
82
+ * Issue #266: Resolve execution issue when the path for GnuPlot or Vega contains spaces
83
+ * Issue #267: Use binary mode when reading generated images from stdout
84
+ * Issue #273: Report Ditaa syntax errors correctly
85
+
3
86
  == 2.0.1
4
87
 
5
88
  Bug Fixes::
@@ -322,7 +405,7 @@ Enhancements::
322
405
 
323
406
  * Add support for `graphviz` blocks which may contain diagrams specified using the Graphviz DOT language
324
407
  * The location of the Graphviz `dot` executable can now be specified using the `graphvizdot` document attribute
325
- * Add support for `ditaa`, `graphivz` and `plantuml` block macros
408
+ * Add support for `ditaa`, `graphviz` and `plantuml` block macros
326
409
 
327
410
  == 1.0.1
328
411
 
data/README.adoc CHANGED
@@ -1,509 +1,41 @@
1
1
  = Asciidoctor Diagram
2
2
  Pepijn Van_Eeckhoudt <https://github.com/pepijnve[@pepijnve]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
3
3
  :description: README for the Asciidoctor Diagram extension for Asciidoctor.
4
- ifdef::env-github[:toc: macro]
5
- ifndef::env-site[:toc: preamble]
6
- ifndef::imagesdir[:imagesdir: images]
7
- :icons: font
8
- :source-highlighter: coderay
9
- :source-language: asciidoc
10
- :table-caption!:
11
- :example-caption!:
12
- :figure-caption!:
13
- :check: icon:check[]
14
- ifdef::env-github[:check: :ballot_box_with_check:]
15
- ifndef::env-site[:status:]
16
- :uri-a2s: https://github.com/dhobsd/asciitosvg
17
- :uri-actdiag: http://blockdiag.com/en/actdiag/index.html
18
- :uri-asciidoctor-api: http://asciidoctor.org/docs/user-manual/#api
19
- :uri-asciidoctor-extensions: http://asciidoctor.org/docs/user-manual/#extension-points
20
- :uri-blockdiag: http://blockdiag.com
21
- :uri-bpmn: https://github.com/gtudan/bpmn-js-cmd
22
- :uri-ditaa: http://ditaa.sourceforge.net/
23
- :uri-dot: https://graphviz.gitlab.io/_pages/doc/info/lang.html
24
- :uri-erd: https://github.com/BurntSushi/erd
25
- :uri-gnuplot: http://gnuplot.info
26
- :uri-graphviz: https://graphviz.gitlab.io
27
- :uri-imagemagick: http://www.imagemagick.org
28
- :uri-java: http://java.sun.com
29
- :uri-mermaid: https://github.com/mermaidjs/mermaid.cli
30
- :uri-mscgen: http://www.mcternan.me.uk/mscgen/
31
- :uri-nomnoml: http://nomnoml.com
32
- :uri-nwdiag: http://blockdiag.com/en/nwdiag/index.html
33
- :uri-packetdiag: http://blockdiag.com/en/nwdiag/index.html
34
- :uri-phantomjs: http://phantomjs.org
35
- :uri-plantuml: http://plantuml.sourceforge.net
36
- :uri-py-plantuml: https://code.google.com/p/asciidoc-plantuml/
37
- :uri-rackdiag: http://blockdiag.com/en/nwdiag/index.html
38
- :uri-seqdiag: http://blockdiag.com/en/seqdiag/index.html
39
- :uri-shaape: https://github.com/christiangoltz/shaape
40
- :uri-smcat: https://github.com/sverweij/state-machine-cat
41
- :uri-svgbob: https://github.com/ivanceras/svgbobrus
42
- :uri-syntrax: https://kevinpt.github.io/syntrax/
43
- :uri-umlet: http://www.umlet.com/
44
- :uri-vega: https://vega.github.io/vega/
45
- :uri-vegalite: https://vega.github.io/vega-lite/
46
- :uri-wavedrom: http://wavedrom.com
47
- :uri-wavedromeditor: https://github.com/wavedrom/wavedrom.github.io/releases
48
- :uri-wavedromcli: https://github.com/wavedrom/cli
49
4
 
50
- Asciidoctor Diagram is a set of Asciidoctor extensions that enable you to add diagrams, which you describe using plain text, to your AsciiDoc document.
51
-
52
- The extensions supports the {uri-a2s}[AsciiToSVG], BlockDiag ({uri-blockdiag}[BlockDiag], {uri-seqdiag}[SeqDiag], {uri-actdiag}[ActDiag], {uri-nwdiag}[NwDiag]), {uri-ditaa}[Ditaa], {uri-erd}[Erd], {uri-gnuplot}[Gnuplot], {uri-dot}[GraphViz], {uri-mermaid}[Mermaid], {uri-mscgen}[Msc], {uri-nomnoml}[Nomnoml], {uri-plantuml}[PlantUML], {uri-shaape}[Shaape], {uri-smcat}[State Machine Cat], {uri-svgbob}[SvgBob], {uri-syntrax}[Syntrax], {uri-umlet}[UMLet], {uri-vega}[Vega], {uri-vegalite}[Vega-Lite] and {uri-wavedrom}[WaveDrom] syntax.
53
-
54
- Each extension runs the diagram processor to generate an SVG, PNG, or TXT file from the input text.
55
- The generated file is then inserted into your converted document.
56
-
57
- Asciidoctor Diagram was inspired by the {uri-py-plantuml}[AsciiDoc PlantUML filter].
58
-
59
- ifndef::env-site[]
60
- Translations of the document are available in the following languages:
61
-
62
- * link:README_zh-CN.adoc[汉语]
63
- endif::[]
64
-
65
- ifdef::status[]
66
- [discrete]
67
- == Status
68
-
69
- image:https://travis-ci.org/asciidoctor/asciidoctor-diagram.svg?branch=master["Linux Build Status", link="https://travis-ci.org/asciidoctor/asciidoctor-diagram"]
70
- 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"]
5
+ image:https://github.com/asciidoctor/asciidoctor-diagram/workflows/Linux%20unit%20tests/badge.svg?branch=master["Linux Build Status", link="https://github.com/asciidoctor/asciidoctor-diagram/actions?query=workflow%3A%22Linux+unit+tests%22"]
6
+ image:https://github.com/asciidoctor/asciidoctor-diagram/workflows/macOS%20unit%20tests/badge.svg?branch=master["macOS Build Status", link="https://github.com/asciidoctor/asciidoctor-diagram/actions?query=workflow%3A%22macOS+unit+tests%22"]
7
+ image:https://github.com/asciidoctor/asciidoctor-diagram/workflows/Windows%20unit%20tests/badge.svg?branch=master["Windows Build Status", link="https://github.com/asciidoctor/asciidoctor-diagram/actions?query=workflow%3A%22Windows+unit+tests%22"]
71
8
  image:https://badge.fury.io/rb/asciidoctor-diagram.svg[Gem Version, link=https://rubygems.org/gems/asciidoctor-diagram]
72
- endif::status[]
73
-
74
- ifeval::["{toc-placement}" == "macro"]
75
- [discrete]
76
- == Contents
77
-
78
- toc::[title={blank}]
79
- endif::[]
80
-
81
- == Installation
82
-
83
- Asciidoctor Diagram is a RubyGem, which can be installed using the `gem` or `bundle` commands.
84
-
85
- You can install the Asciidoctor Diagram gem by typing `gem install` in the CLI.
86
-
87
- $ gem install asciidoctor-diagram
88
-
89
- by first adding the following entry to your project's [.path]_Gemfile_.
90
9
 
91
- .Gemfile
92
- [source,ruby]
93
- ----
94
- gem 'asciidoctor-diagram'
95
- ----
96
-
97
- Then execute `bundle` in the CLI.
98
-
99
- $ bundle
100
-
101
- == Creating a Diagram
102
-
103
- A diagram is written inside a literal block, which can accept several attributes.
10
+ Asciidoctor Diagram is a set of Asciidoctor extensions that enable you to add diagrams, which you describe using plain text, to your AsciiDoc document.
11
+ The extension will run the appropriate diagram processor to generate an image from the input text.
12
+ The generated image is then inserted into your converted document.
104
13
 
105
- .Anatomy of a diagram
106
- ----
107
- [diagram-type, generated-file-name, generated-image-format] // <1> <2> <3>
108
- .... // <4>
109
- Diagram in appropriate syntax
110
- ....
111
- ----
112
- <1> The first positional attribute in the attribute list specifies the diagram that is being used.
113
- <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.
114
- <3> The third, optional positional attribute specifies the image format to create, specified as a three character file extension.
115
- <4> Place the attribute list directly on top of the delimited literal block (+....+). You can also use an open block as an alternative (`--`).
14
+ Detailed usage instructions can be found on the https://docs.asciidoctor.org/diagram-extension/latest/[Asciidoctor documentation site].
116
15
 
117
- The following diagram types and output formats are available:
16
+ Asciidoctor Diagram was inspired by the https://code.google.com/p/asciidoc-plantuml/[AsciiDoc PlantUML filter].
118
17
 
119
- [cols=">,5*^",options="header"]
120
- |===
121
- |Diagram Type |gif |pdf |png |svg |txt
122
- |{uri-a2s}[a2s] | | | |{check}|
123
- |{uri-actdiag}[actdiag] | |{check}|{check}|{check}|
124
- |{uri-blockdiag}[blockdiag] | |{check}|{check}|{check}|
125
- |{uri-bpmn}[bpmn] | |{check}|{check}|{check}|
126
- |{uri-ditaa}[ditaa] | | |{check}|{check}|
127
- |{uri-erd}[erd] | | |{check}|{check}|
128
- |{uri-gnuplot}[gnuplot] |{check}| |{check}|{check}|{check}
129
- |{uri-dot}[graphviz] | |{check}|{check}|{check}|
130
- |<<meme,meme>> |{check}| |{check}| |
131
- |{uri-mermaid}[mermaid] | |{check}|{check}|{check}|
132
- |{uri-mscgen}[msc] | | |{check}|{check}|
133
- |{uri-nomnoml}[nomnoml] | | | |{check}|
134
- |{uri-nwdiag}[nwdiag] | |{check}|{check}|{check}|
135
- |{uri-packetdiag}[packetdiag]| |{check}|{check}|{check}|
136
- |{uri-plantuml}[plantuml] | | |{check}|{check}|{check}
137
- |{uri-rackdiag}[rackdiag] | |{check}|{check}|{check}|
138
- |{uri-seqdiag}[seqdiag] | |{check}|{check}|{check}|
139
- |{uri-shaape}[shaape] | | |{check}|{check}|
140
- |{uri-smcat}[smcat] | | | |{check}|
141
- |{uri-svgbob}[svgbob] | | | |{check}|
142
- |{uri-syntrax}[syntrax] | |{check}|{check}|{check}|
143
- |{uri-umlet}[umlet] |{check}|{check}|{check}|{check}|
144
- |{uri-vega}[vega] | | |{check}|{check}|
145
- |{uri-vegalite}[vegalite] | | |{check}|{check}|
146
- |{uri-wavedrom}[wavedrom] | | |{check}|{check}|
147
- |===
18
+ == Example
148
19
 
149
- The example below illustrates the structure of a basic ditaa block written directly in an AsciiDoc document.
20
+ The Asciidoctor Diagram enables you to embed a plain text diagram as a block in your document.
21
+ The example below shows an embedded Ditaa diagram block.
150
22
 
151
- .Basic ditaa block
152
- [source]
153
- ----
23
+ ---------
154
24
  [ditaa]
155
- ....
156
- +-------------+
157
- | Asciidoctor |-------+
158
- | diagram | |
159
- +-------------+ | PNG out
160
- ^ |
161
- | ditaa in |
162
- | v
163
- +--------+ +--------+----+ /---------------\
164
- | | --+ Asciidoctor +--> | |
165
- | Text | +-------------+ | Beautiful |
166
- |Document| | !magic! | | Output |
167
- | {d}| | | | |
168
- +---+----+ +-------------+ \---------------/
169
- : ^
170
- | Lots of work |
171
- +-----------------------------------+
172
- ....
173
- ----
174
-
175
- The ditaa block above results in the following generated diagram.
176
-
177
- .Rendered ditaa diagram
178
- image::asciidoctor-diagram-process.png[Asciidoctor Diagram process diagram,650,319]
179
-
180
- The rendered ditaa diagram above gets the file name `58372f7d2ceffae9e91fd0a7cbb080b6.png`.
181
- That long number is the checksum of the source code calculated by asciidoctor-diagram.
182
- If you want to give your generated files a more meaningful name, fill in the `target` attribute.
183
-
184
- This can be done by either specifying it as the second positional attribute or as a named attribute.
185
- Both examples below would result in a file called `ditaa-diagram.png`.
186
-
187
- ....
188
- [ditaa, "ditaa-diagram"]
189
- ----
190
- <snip>
191
- ----
192
-
193
- [ditaa, target="ditaa-diagram"]
194
- ----
195
- <snip>
196
- ----
197
- ....
198
-
199
-
200
- The example below illustrates the structure of a basic PlantUML block written directly in an AsciiDoc document.
201
-
202
- .PlantUML Diagram Syntax
203
- [source]
204
- ----
205
- [plantuml, diagram-classes, png] // <1> <2> <3>
206
- ....
207
- class BlockProcessor
208
- class DiagramBlock
209
- class DitaaBlock
210
- class PlantUmlBlock
211
-
212
- BlockProcessor <|-- DiagramBlock
213
- DiagramBlock <|-- DitaaBlock
214
- DiagramBlock <|-- PlantUmlBlock
215
- ....
216
- ----
217
- <1> The diagram is written in PlantUML so the first positional attribute is assigned the `plantuml` diagram type.
218
- <2> The name of the generated diagram file (target) is written in the second positional attribute.
219
- <3> The output format is entered in the third positional attribute.
220
-
221
- .Rendered PlantUML diagram
222
- image::asciidoctor-diagram-classes.png[Asciidoctor Diagram classes diagram]
223
-
224
- == Generating a Diagram from a Terminal
225
-
226
- You can load Asciidoctor diagram in a terminal using the `-r` flag.
227
-
228
- $ asciidoctor -r asciidoctor-diagram sample.adoc
229
-
230
- You can also use Asciidoctor diagram with other converters, such as Asciidoctor EPUB.
231
- Asciidoctor-epub3 is also loaded with the `-r` flag.
232
-
233
- $ asciidoctor -r asciidoctor-diagram -r asciidoctor-epub3 -b epub3 sample.adoc
234
-
235
- Or, you can invoke Asciidoctor and the EPUB converter with the `asciidoctor-epub3` command.
236
- The command implicitly sets the `-r` and `-b` flags for EPUB3 output.
237
-
238
- $ asciidoctor-epub3 -r asciidoctor-diagram sample.adoc
239
-
240
- == Advanced Usage
241
-
242
- === Enabling Extensions
243
-
244
- In your program, you can either load and register the entire set of diagram extensions
245
-
246
- [source,ruby]
247
- ----
248
- require 'asciidoctor-diagram'
249
- ----
250
-
251
- or load and register each extension individually.
252
-
253
- [source,ruby]
254
25
  ----
255
- require 'asciidoctor-diagram/<extension_name>'
26
+ +-------------+
27
+ | asciidoctor |-----------+
28
+ | diagram | |
29
+ +-------------+ | image
30
+ ^ |
31
+ | diagram source |
32
+ | v
33
+ +--------+ +-----+-------+ /---------------\
34
+ | adoc |-->+ asciidoctor + | HTML + image |
35
+ +--------+ +-------------+ \---------------/
256
36
  ----
37
+ ---------
257
38
 
258
- `<extension_name>` can be one of `a2s`, `blockdiag`, `ditaa`, `erd`, `gnuplot`, `graphviz`, `meme`, `mermaid`, `msc`, `plantuml`, `shaape`, `smcat`, `svgbob`, `syntrax`, `umlet`, `vega` or `wavedrom`.
259
-
260
- Requiring one or more of these files will automatically register the extensions for all processed documents.
261
-
262
- If you need more fine grained control over when the extensions are enabled, `asciidoctor-diagram/<extension_name>/extension` can be used instead.
263
- This loads the extensions but does not register it in the Asciidoctor extension registry.
264
- You can then manually register the extensions at the appropriate times using the `Asciidoctor::Extensions` API.
265
-
266
- This document explains the various features of asciidoctor-diagram blocks using ditaa diagrams as an example.
267
-
268
- === Diagram Block Macro
269
-
270
- The diagram extensions can also be used in in block macro form.
271
-
272
- .Anatomy of a diagram block macro
273
- ----
274
- block-name::source-file-name[generated-file-extension] // <1> <2> <3>
275
- ----
276
- <1> The macro name is the same as the block name in the block form.
277
- <2> The source file name specifies the external file that contains the diagram source code.
278
- <3> The first, optional, positional attribute assigns the file extension (i.e. `format`) to the generated diagram.
279
-
280
- When the source file name is a relative path it is resolved with respect to the location of the document being processed.
281
-
282
- === Image Output Location
283
-
284
- When Asciidoctor Diagram writes images to disk it will go over the following options in order to determine where to write the files.
285
-
286
- . `\{imagesoutdir\}` if the `imagesoutdir` attribute has been specified
287
- . `\{outdir\}/\{imagesdir\}` if the `outdir` attribute has been specified
288
- . `\{to_dir\}/\{imagesdir\}` if the `to_dir` attribute has been specified
289
- . `\{base_dir\}/\{imagesdir\}`
290
-
291
- === Specifying Diagram Generator Paths
292
-
293
- Asciidoctor Diagram depends on external tools to generates images.
294
- In most cases it will locate these tools automatically for you by looking for specific executables in each directory in the `PATH` environment variable.
295
- 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.
296
- 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.
297
-
298
- [cols=">,2*<",options="header"]
299
- |===
300
- |Diagram Type |Tool |Attribute
301
- |a2s |{uri-a2s}[AsciiToSvg] |`a2s`
302
- |actdiag |{uri-actdiag}[ActDiag] |`actdiag`
303
- |blockdiag |{uri-blockdiag}[BlockDiag] |`blockdiag`
304
- |bpmn |{uri-bpmn}[bpmn-js-cmd] |`bpmn`
305
- |ditaa |{uri-java}[Java] |`java`
306
- |erd |{uri-erd}[Erd] |`erd`
307
- |gnuplot |{uri-gnuplot}[Gnuplot] |`gnuplot`
308
- |graphviz |{uri-graphviz}[GraphViz] |`dot` or `graphvizdot`
309
- |meme |{uri-imagemagick}[ImageMagick] |`convert` and `identify`
310
- |mermaid |{uri-mermaid}[Mermaid.cli] |`mermaid`
311
- |msc |{uri-mscgen}[Mscgen] |`mscgen`
312
- |nomnoml |{uri-nomnoml}[Nomnoml] |`nomnoml`
313
- |nwdiag |{uri-nwdiag}[NwDiag] |`nwdiag`
314
- |packetdiag |{uri-nwdiag}[NwDiag] |`packetdiag`
315
- |plantuml |{uri-java}[Java] |`java`
316
- |rackdiag |{uri-nwdiag}[NwDiag] |`rackdiag`
317
- |seqdiag |{uri-seqdiag}[SeqDiag] |`seqdiag`
318
- |shaape |{uri-shaape}[Shaape] |`shaape`
319
- |smcat |{uri-smcat}[State Machine Cat] |`smcat`
320
- |svgbob |{uri-svgbob}[SvgBob] |`svgbob`
321
- |syntrax |{uri-syntrax}[Syntrax] |`syntrax`
322
- |umlet |{uri-umlet}[Umlet] |`umlet`
323
- |vega |{uri-vega}[vg2png] and/or {uri-vega}[vg2png] |`vg2png` and `vg2svg`
324
- |vegalite |{uri-vegalite}[vl2vg] and {uri-vega}[vg2png] and/or {uri-vega}[vg2svg]|`vl2vg`, `vg2png` and `vg2svg`
325
- .2+|wavedrom |{uri-wavedromeditor}[WaveDrom Editor] |`wavedrom`
326
- |{uri-wavedromcli}[WaveDrom CLI] (and {uri-phantomjs}[PhantomJS] for WaveDrom CLI v1) |`wavedrom` (and `phantomjs`)
327
- |===
328
-
329
- 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
330
-
331
- $ asciidoctor -a actdiag=/home/me/actdiag/bin/actdiag -r asciidoctor-diagram sample.adoc
332
-
333
- [[meme]]
334
- === The Meme Extension
335
-
336
- The meme extension provides a basic '`Advice Animal`' style image generator.
337
- It's usage is easiest to explain with an example.
338
-
339
- ----
340
- meme::yunoguy.jpg[Doc writers,Y U NO // AsciiDoc]
341
- ----
342
-
343
- The target of the block macro tells the extension which image to use as background.
344
- The first two positional attributes are `top` and `bottom` and are used for the top and bottom label.
345
- Occurrences of `//` surrounded by whitespace are interpreted as line breaks.
346
-
347
- === Diagram Attributes
348
-
349
- Certain diagram types allow image generation to be customized using attributes.
350
- Each attribute can be specified per individual diagram block or for all blocks of a given diagram type in a document level.
351
- This is illustrated for the blockdiag `fontpath` attribute in the example below.
352
-
353
- ----
354
- = Asciidoctor Diagram
355
- :blockdiag-fontpath: /path/to/font.ttf <1>
356
-
357
- [blockdiag] <2>
358
- ....
359
- ....
360
-
361
- [blockdiag, fontpath="/path/to/otherfont.ttf"] <3>
362
- ....
363
- ....
364
- ----
365
- <1> Attributes can be specified for all diagram of a certain type at the document level by prefixing them with `<blocktype>-`.
366
- In this example, the `fontpath` attribute is specified for all diagrams of type `blockdiag`.
367
- <2> The first diagram does not specify an explicit value for `fontpath` so the global `blockdiag-fontpath` value will be used
368
- <3> The second diagram does specifie a `fontpath` value.
369
- This overrides the global `blockdiag-fontpath` value.
370
-
371
- Each attribute can either be specified at the block level or at the document level.
372
- The attribute name at the block level should be prefixed with the name of the diagram type and a dash.
373
-
374
- ==== Shared Attributes
375
-
376
- [cols=">,<,<",options="header"]
377
- |===
378
- |Name |Default value |Description
379
- |svg-type |unspecified |One of `static`, `inline` or `interactive`. This determines the style of SVG embedding that's used in certain backends. The https://asciidoctor.org/docs/user-manual/#taming-svgs[asciidoctor user guide] describes this in more detail.
380
- |===
381
-
382
- ==== AsciiToSVG
383
-
384
- [cols=">,<,<",options="header"]
385
- |===
386
- |Name |Default value |Description
387
- |fontfamily |unspecified |The font family to use in the generated SVG image
388
- |noblur |unspecified |Disable drop-shadow blurring
389
- |===
390
-
391
- ==== Blockdiag
392
-
393
- [cols=">,<,<",options="header"]
394
- |===
395
- |Name |Default value |Description
396
- |fontpath |unspecified |The path to the font that should be used by blockdiag
397
- |===
398
-
399
- ==== BPMN
400
-
401
- [cols=">,<,<",options="header"]
402
- |===
403
- |Name |Default value |Description
404
- |height |786 |The target height of the diagram. Does not apply for output type `svg`.
405
- |width |1024 |The target width of the diagram. Does not apply for output type `svg`.
406
- |===
407
-
408
- ==== Ditaa
409
-
410
- [cols=">,<,<",options="header"]
411
- |===
412
- |Name |Default value |Description
413
- |scale |1 |A scale factor that is applied to the image.
414
- |tabs |8 |An integer value that specifies the tab size as a number of spaces.
415
- |background |FFFFFF |The background colour of the image. The format should be a six-digit hexadecimal number (as in HTML, FF0000 for red). Pass an eight-digit hex to define transparency.
416
- |antialias |true |Enables or disables anti-aliasing.
417
- |separation |true |Prevents the separation of common edges of shapes.
418
- |round-corners|false |Causes all corners to be rendered as round corners.
419
- |shadows |true |Enables or disable drop shadows.
420
- |debug |false |Renders the debug grid over the resulting image.
421
- |fixed-slope |false |Makes sides of parallelograms and trapezoids fixed slope instead of fixed width.
422
- |transparent |false |Makes the background of the image transparent instead of using the background color.
423
- |===
424
-
425
- ==== Gnuplot
426
-
427
- [cols=">,<,<",options="header"]
428
- |===
429
- |Name |Default value |Description
430
- |background |unspecified |Background color, e.g. `red`, `#FF0000`. Does not work with `txt`.
431
- |height |unspecified |The height of the plot. Must be specified together with `width`.
432
- |width |unspecified |The width of the plot. Must be specified together with `height`.
433
- |crop |unspecified |Trims blank space from the edges of the completed plot (true/false). Does not work with `svg`, `pdf`.
434
- |transparent |unspecified |Generate transparent background (true/false). Does not work with `svg`, `pdf`, `txt`.
435
- |font |unspecified |The font face with optional font size to use for the text, e.g. `font="Arial"`, `font="Arial,11"`. Does not work with `txt`.
436
- |fontscale |unspecified |Scales all label for given factor. Does not work with `txt`.
437
- |===
438
-
439
- ==== GraphViz
440
-
441
- [cols=">,<,<",options="header"]
442
- |===
443
- |Name |Default value |Description
444
- |layout |unspecified |The graphviz layout engine to use (dot -K option).
445
- |===
446
-
447
- ==== Meme
448
-
449
- [cols=">,<,<",options="header"]
450
- |===
451
- |Name |Default value |Description
452
- |fill-color |white |The fill color for the text.
453
- |stroke-color |black |The outline color for the text
454
- |stroke-width |2 |The width of the text outline.
455
- |font |Impact |The font face to use for the text.
456
- |options |unspecified |a comma separate list of flags that modify the image rendering. Currently only `noupcase` is supported which disable upper casing the labels.
457
- |===
458
-
459
- ==== Mermaid
460
-
461
- [cols=">,<,<",options="header"]
462
- |===
463
- |Name |Default value |Description
464
- |background |FFFFFF |The background colour of the image. The format should be a six-digit hexadecimal number (as in HTML, FF0000 for red). Pass an eight-digit hex to define transparency.
465
- |css |unspecified |Path to a CSS file to pass to mermaid.
466
- |config |unspecified |Path to a JSON config file to pass to mermaid.
467
- |gantt-config |unspecified |Path to a gantt config file to pass to mermaid.
468
- |puppeteer-config|unspecified |Path to a puppeteer config file to pass to mermaid.
469
- |sequence-config |unspecified |Path to a sequence config file to pass to mermaid.
470
- |theme |unspecified |Theme of the chart, could be default, forest, dark or neutral.
471
- |width |unspecified |Width of the page.
472
- |height |unspecified |Height of the page.
473
- |===
474
-
475
- ==== Msc
476
-
477
- [cols=">,<,<",options="header"]
478
- |===
479
- |Name |Default value |Description
480
- |font |unspecified |The name of the font that should be used by mscgen
481
- |===
482
-
483
- ==== PlantUML
484
-
485
- [cols=">,<,<",options="header"]
486
- |===
487
- |Name |Default value |Description
488
- |config |unspecified |Path to a config file to pass to PlantUML.
489
- |===
490
-
491
- ==== State Machine Cat
492
-
493
- [cols=">,<,<",options="header"]
494
- |===
495
- |Name |Default value |Description
496
- |direction |unspecifed |The direction of the state machine diagram. One of `top-down`, `bottom-top`, `left-right` or `right-left`.
497
- |engine |unspecified |The layout engine to use. One of `dot`, `circo`, `fdp`, `neato`, `osage`, or `twopi`
498
- |===
499
-
500
- ==== Syntrax
39
+ After processing by Asciidoctor, the output file will show a rendered version of the diagram instead of the diagram source code.
501
40
 
502
- [cols=">,<,<",options="header"]
503
- |===
504
- |Name |Default value |Description
505
- |heading |unspecifed |Diagram title
506
- |scale |1 |A scale factor that is applied to the image.
507
- |style |unspecifed |Path to a style config file to pass to Syntrax.
508
- |transparent |false |Makes the background of the image transparent instead of opaque white.
509
- |===
41
+ image::docs/modules/ROOT/images/asciidoctor-diagram-process.png[]