asciidoctor-diagram 2.2.11 → 2.2.12.next1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (99) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.adoc +7 -0
  3. data/lib/asciidoctor-diagram/plantuml/converter.rb +1 -0
  4. data/lib/asciidoctor-diagram/structurizr/renderers.rb +5 -0
  5. data/lib/asciidoctor-diagram/version.rb +1 -1
  6. metadata +5 -132
  7. data/Rakefile +0 -9
  8. data/docs/antora.yml +0 -5
  9. data/docs/modules/ROOT/images/a2s.svg +0 -44
  10. data/docs/modules/ROOT/images/actdiag.png +0 -0
  11. data/docs/modules/ROOT/images/asciidoctor-diagram-classes.png +0 -0
  12. data/docs/modules/ROOT/images/asciidoctor-diagram-process.png +0 -0
  13. data/docs/modules/ROOT/images/barcode.png +0 -0
  14. data/docs/modules/ROOT/images/barcode2.png +0 -0
  15. data/docs/modules/ROOT/images/blockdiag.png +0 -0
  16. data/docs/modules/ROOT/images/d2.png +0 -0
  17. data/docs/modules/ROOT/images/lilypond.png +0 -0
  18. data/docs/modules/ROOT/images/penrose.png +0 -0
  19. data/docs/modules/ROOT/nav.adoc +0 -41
  20. data/docs/modules/ROOT/pages/blocks.adoc +0 -140
  21. data/docs/modules/ROOT/pages/diagram_types/a2s.adoc +0 -47
  22. data/docs/modules/ROOT/pages/diagram_types/actdiag.adoc +0 -46
  23. data/docs/modules/ROOT/pages/diagram_types/barcode.adoc +0 -72
  24. data/docs/modules/ROOT/pages/diagram_types/blockdiag.adoc +0 -38
  25. data/docs/modules/ROOT/pages/diagram_types/bpmn.adoc +0 -21
  26. data/docs/modules/ROOT/pages/diagram_types/bytefield.adoc +0 -16
  27. data/docs/modules/ROOT/pages/diagram_types/d2.adoc +0 -43
  28. data/docs/modules/ROOT/pages/diagram_types/dbml.adoc +0 -16
  29. data/docs/modules/ROOT/pages/diagram_types/diagrams.adoc +0 -20
  30. data/docs/modules/ROOT/pages/diagram_types/ditaa.adoc +0 -31
  31. data/docs/modules/ROOT/pages/diagram_types/dpic.adoc +0 -16
  32. data/docs/modules/ROOT/pages/diagram_types/erd.adoc +0 -17
  33. data/docs/modules/ROOT/pages/diagram_types/gnuplot.adoc +0 -27
  34. data/docs/modules/ROOT/pages/diagram_types/graphviz.adoc +0 -21
  35. data/docs/modules/ROOT/pages/diagram_types/lilypond.adoc +0 -27
  36. data/docs/modules/ROOT/pages/diagram_types/meme.adoc +0 -34
  37. data/docs/modules/ROOT/pages/diagram_types/mermaid.adoc +0 -28
  38. data/docs/modules/ROOT/pages/diagram_types/msc.adoc +0 -23
  39. data/docs/modules/ROOT/pages/diagram_types/nomnoml.adoc +0 -16
  40. data/docs/modules/ROOT/pages/diagram_types/nwdiag.adoc +0 -22
  41. data/docs/modules/ROOT/pages/diagram_types/penrose.adoc +0 -50
  42. data/docs/modules/ROOT/pages/diagram_types/pikchr.adoc +0 -16
  43. data/docs/modules/ROOT/pages/diagram_types/plantuml.adoc +0 -24
  44. data/docs/modules/ROOT/pages/diagram_types/seqdiag.adoc +0 -18
  45. data/docs/modules/ROOT/pages/diagram_types/shaape.adoc +0 -18
  46. data/docs/modules/ROOT/pages/diagram_types/smcat.adoc +0 -18
  47. data/docs/modules/ROOT/pages/diagram_types/structurizr.adoc +0 -29
  48. data/docs/modules/ROOT/pages/diagram_types/svgbob.adoc +0 -21
  49. data/docs/modules/ROOT/pages/diagram_types/symbolator.adoc +0 -19
  50. data/docs/modules/ROOT/pages/diagram_types/syntrax.adoc +0 -28
  51. data/docs/modules/ROOT/pages/diagram_types/tikz.adoc +0 -21
  52. data/docs/modules/ROOT/pages/diagram_types/umlet.adoc +0 -19
  53. data/docs/modules/ROOT/pages/diagram_types/vega.adoc +0 -28
  54. data/docs/modules/ROOT/pages/diagram_types/wavedrom.adoc +0 -17
  55. data/docs/modules/ROOT/pages/enabling.adoc +0 -25
  56. data/docs/modules/ROOT/pages/generate.adoc +0 -15
  57. data/docs/modules/ROOT/pages/index.adoc +0 -12
  58. data/docs/modules/ROOT/pages/installation.adoc +0 -32
  59. data/docs/modules/ROOT/pages/output.adoc +0 -19
  60. data/docs/modules/ROOT/partials/shared-attrs.adoc +0 -12
  61. data/docs/modules/ROOT/partials/uris.adoc +0 -48
  62. data/examples/Gemfile +0 -3
  63. data/examples/README.adoc +0 -18
  64. data/examples/design.adoc +0 -78
  65. data/examples/features.adoc +0 -189
  66. data/spec/a2s_spec.rb +0 -33
  67. data/spec/barcode_spec.rb +0 -176
  68. data/spec/blockdiag_spec.rb +0 -20
  69. data/spec/bpmn_spec.rb +0 -60
  70. data/spec/bytefield_spec.rb +0 -96
  71. data/spec/d2_spec.rb +0 -87
  72. data/spec/dbml_spec.rb +0 -32
  73. data/spec/diagrams_spec.rb +0 -27
  74. data/spec/ditaa_spec.rb +0 -191
  75. data/spec/dpic_spec.rb +0 -23
  76. data/spec/erd_spec.rb +0 -96
  77. data/spec/gnuplot_spec.rb +0 -229
  78. data/spec/graphviz_py_spec.rb +0 -33
  79. data/spec/graphviz_spec.rb +0 -24
  80. data/spec/lilypond_spec.rb +0 -17
  81. data/spec/man.jpg +0 -0
  82. data/spec/meme_spec.rb +0 -67
  83. data/spec/mermaid_spec.rb +0 -161
  84. data/spec/msc_spec.rb +0 -37
  85. data/spec/nomnoml_spec.rb +0 -36
  86. data/spec/pikchr_spec.rb +0 -73
  87. data/spec/plantuml_spec.rb +0 -800
  88. data/spec/shaape_spec.rb +0 -20
  89. data/spec/shared_examples.rb +0 -766
  90. data/spec/smcat_spec.rb +0 -30
  91. data/spec/structurizr_spec.rb +0 -41
  92. data/spec/svgbob_spec.rb +0 -33
  93. data/spec/symbolator_spec.rb +0 -27
  94. data/spec/syntrax_spec.rb +0 -22
  95. data/spec/test_helper_methods.rb +0 -118
  96. data/spec/tikz_spec.rb +0 -181
  97. data/spec/umlet_spec.rb +0 -32
  98. data/spec/vega_spec.rb +0 -133
  99. data/spec/wavedrom_spec.rb +0 -21
@@ -1,28 +0,0 @@
1
- = Syntrax / JSyntrax
2
- include::partial$uris.adoc[]
3
-
4
- {uri-syntrax}[Syntrax] is a railroad diagram generator.
5
- It creates a visual illustration of the grammar used for programming languages.
6
- A specification file describes the syntax as a hierarchy of basic elements.
7
- This is processed into an image representing the same syntax with interconnected nodes.
8
-
9
- {uri-jsyntrax}[JSyntrax] is a reimplementation of Syntrax in Java in order to simplify installation, get rid of required libraries and make it easily portable to any operating system.
10
-
11
- == Supported Image Formats
12
-
13
- - PDF
14
- - PNG
15
- - SVG
16
-
17
- == Attributes
18
-
19
- [cols=">,<,<",options="header"]
20
- |===
21
- |Name |Default value |Description
22
- |syntrax |syntrax |The path to the `syntrax` executable. This attribute is used for the {uri-syntrax}[Syntrax] implementation.
23
- |java |java |The path to the `java` executable. This attribute is used for the {uri-jsyntrax}[JSyntrax] implementation. The `DIAGRAM_JSYNTRAX_HOME` environment variable should then also be defined and point to the JSyntrax installation directory. The installation directory can also be specified using the `diagram.jsyntrax.home` Java system property.
24
- |heading |unspecified |Diagram title
25
- |scale |1 |A scale factor that is applied to the image.
26
- |style-file |unspecified |Path to a style config file to pass to Syntrax.
27
- |transparent |false |Makes the background of the image transparent instead of opaque white.
28
- |===
@@ -1,21 +0,0 @@
1
- = TikZ
2
- include::partial$uris.adoc[]
3
-
4
- {uri-tikz}[TikZ] is a graphics drawing environment for TeX.
5
-
6
- TikZ requires a TeX distribution that supports the {uri-tikz}[TikZ] package.
7
-
8
- == Supported Image Formats
9
-
10
- - PDF
11
- - SVG
12
-
13
- == Attributes
14
-
15
- [cols=">,<,<",options="header"]
16
- |===
17
- |Name |Default value |Description
18
- |pdflatex |pdflatex |The path to the `pdflatex` executable
19
- |pdf2svg |pdf2svg |The path to the `pdf2svg` executable
20
- |preamble |unspecified |Code definitions to pass to TikZ.
21
- |===
@@ -1,19 +0,0 @@
1
- = UMLet
2
- include::partial$uris.adoc[]
3
-
4
- {uri-umlet}[UMLet] is a free, open-source UML tool with a simple user interface: draw UML diagrams fast, create sequence and activity diagrams from plain text, share via exports to eps, pdf, jpg, svg, and clipboard, and develop new, custom UML elements.
5
-
6
- == Supported Image Formats
7
-
8
- - GIF
9
- - PDF
10
- - PNG
11
- - SVG
12
-
13
- == Attributes
14
-
15
- [cols=">,<,<",options="header"]
16
- |===
17
- |Name |Default value |Description
18
- |umlet |umlet |The path to the `umlet` executable
19
- |===
@@ -1,28 +0,0 @@
1
- = Vega / Vega-Lite
2
- include::partial$uris.adoc[]
3
-
4
- {uri-vega}[Vega] and {uri-vegalite}[Vega-Lite] are declarative language for creating, saving, and sharing interactive visualization designs.
5
-
6
- Vega provides basic building blocks for a wide variety of visualization designs: data loading and transformation, scales, map projections, axes, legends, and graphical marks such as rectangles, lines, plotting symbols, etc.
7
-
8
- Vega-Lite provides a more concise and convenient form to author common visualizations. As Vega-Lite can compile its specifications to Vega specifications, users may use Vega-Lite as the primary visualization tool and, if needed, transition to use the lower-level Vega for advanced use cases.
9
-
10
- == Supported Image Formats
11
-
12
- - PNG
13
- - SVG
14
-
15
- == Attributes
16
-
17
- |vega |{uri-vega}[vg2png] and/or {uri-vega}[vg2png] |`vg2png` and `vg2svg`
18
- |vegalite |{uri-vegalite}[vl2vg] and {uri-vega}[vg2png] and/or {uri-vega}[vg2svg]|`vl2vg`, `vg2png` and `vg2svg`
19
-
20
- [cols=">,<,<",options="header"]
21
- |===
22
- |Name |Default value |Description
23
- |vg2png |vg2png |The path to the `vg2png` executable. This attribute is used for PNG output.
24
- |vg2svg |vg2svg |The path to the `vg2svg` executable This attribute is used for SVG output.
25
- |vl2vg |vl2vg |The path to the `vl2vg` executable. This attribute is used for Vega-Lite diagrams.
26
- |===
27
-
28
- None
@@ -1,17 +0,0 @@
1
- = WaveDrom
2
- include::partial$uris.adoc[]
3
-
4
- {uri-wavedrom}[WaveDrom] draws your Timing Diagram or Waveform from simple textual description.
5
-
6
- == Supported Image Formats
7
-
8
- - PNG
9
- - SVG
10
-
11
- == Attributes
12
-
13
- [cols=">,<,<",options="header"]
14
- |===
15
- |Name |Default value |Description
16
- |wavedrom |wavedrom |The path to the `wavedrom` executable
17
- |===
@@ -1,25 +0,0 @@
1
- = Enabling Extensions
2
-
3
- In your program, you can either load and register the entire set of diagram extensions
4
-
5
- [source,ruby]
6
- ----
7
- require 'asciidoctor-diagram'
8
- ----
9
-
10
- or load and register each extension individually.
11
-
12
- [source,ruby]
13
- ----
14
- require 'asciidoctor-diagram/<extension_name>'
15
- ----
16
-
17
- `<extension_name>` can be one of `a2s`, `blockdiag`, `bytefield`, `diagrams`, `ditaa`, `dpic`, `erd`, `gnuplot`, `graphviz`, `meme`, `mermaid`, `msc`, `pikchr`, `plantuml`, `shaape`, `smcat`, `svgbob`, `syntrax`, `umlet`, `vega` or `wavedrom`.
18
-
19
- Requiring one or more of these files will automatically register the extensions for all processed documents.
20
-
21
- If you need more fine-grained control over when the extensions are enabled, `asciidoctor-diagram/<extension_name>/extension` can be used instead.
22
- This loads the extensions but does not register it in the Asciidoctor extension registry.
23
- You can then manually register the extensions at the appropriate times using the `Asciidoctor::Extensions` API.
24
-
25
- This document explains the various features of asciidoctor-diagram blocks using ditaa diagrams as an example.
@@ -1,15 +0,0 @@
1
- = Rendering Diagrams
2
-
3
- You can load Asciidoctor diagram in a terminal using the `-r` flag.
4
-
5
- $ asciidoctor -r asciidoctor-diagram sample.adoc
6
-
7
- You can also use Asciidoctor diagram with other converters, such as Asciidoctor EPUB.
8
- Asciidoctor-epub3 is also loaded with the `-r` flag.
9
-
10
- $ asciidoctor -r asciidoctor-diagram -r asciidoctor-epub3 -b epub3 sample.adoc
11
-
12
- Or, you can invoke Asciidoctor and the EPUB converter with the `asciidoctor-epub3` command.
13
- The command implicitly sets the `-r` and `-b` flags for EPUB3 output.
14
-
15
- $ asciidoctor-epub3 -r asciidoctor-diagram sample.adoc
@@ -1,12 +0,0 @@
1
- = Overview
2
- Pepijn Van_Eeckhoudt <https://github.com/pepijnve[@pepijnve]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
3
- :description: README for the Asciidoctor Diagram extension for Asciidoctor.
4
- include::partial$uris.adoc[]
5
-
6
- Asciidoctor Diagram is a set of Asciidoctor extensions that enable rendering of plain text diagrams that are embedded in your AsciiDoc document as part of the Asciidoctor conversion process.
7
-
8
- Each extensions will invoke the necessary external diagram rendering tools to produce an image file which is inserted into your converted document.
9
-
10
- The extensions support the xref:diagram_types/a2s.adoc[], BlockDiag (xref:diagram_types/blockdiag.adoc[], xref:diagram_types/seqdiag.adoc[], xref:diagram_types/actdiag.adoc[], xref:diagram_types/nwdiag.adoc[]), xref:diagram_types/bytefield.adoc[], xref:diagram_types/dbml.adoc[], xref:diagram_types/ditaa.adoc[], xref:diagram_types/dpic.adoc[], xref:diagram_types/erd.adoc[Erd], xref:diagram_types/gnuplot.adoc[], xref:diagram_types/graphviz.adoc[], xref:diagram_types/lilypond.adoc[], xref:diagram_types/mermaid.adoc[], xref:diagram_types/msc.adoc[], xref:diagram_types/nomnoml.adoc[], xref:diagram_types/penrose.adoc[], xref:diagram_types/pikchr.adoc[], xref:diagram_types/plantuml.adoc[], xref:diagram_types/shaape.adoc[], xref:diagram_types/smcat.adoc[], xref:diagram_types/structurizr.adoc[], xref:diagram_types/svgbob.adoc[], xref:diagram_types/symbolator.adoc[], xref:diagram_types/syntrax.adoc[], xref:diagram_types/umlet.adoc[], xref:diagram_types/vega.adoc[], and xref:diagram_types/wavedrom.adoc[] syntax.
11
-
12
- Asciidoctor Diagram was inspired by the {uri-py-plantuml}[AsciiDoc PlantUML filter].
@@ -1,32 +0,0 @@
1
- = Installation
2
- include::partial$uris.adoc[]
3
-
4
- Asciidoctor Diagram is a RubyGem, which can be installed using the `gem` or `bundle` commands.
5
-
6
- You can install the Asciidoctor Diagram gem by typing `gem install` in the CLI.
7
-
8
- $ gem install asciidoctor-diagram
9
-
10
- To install the gem using Bundler, first add the following entry to your project's [.path]_Gemfile_.
11
-
12
- .Gemfile
13
- [source,ruby]
14
- ----
15
- gem 'asciidoctor-diagram'
16
- ----
17
-
18
- Then execute `bundle` in the CLI.
19
-
20
- $ bundle
21
-
22
- == Diagram Renderer Installation Paths
23
-
24
- Asciidoctor Diagram depends on external tools to generate images.
25
- In most cases it will locate these tools automatically for you by looking for specific executables in each directory in the `PATH` environment variable.
26
-
27
- 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.
28
- If, for instance, you installed `diag_tool` in `/home/me/diag_tool/bin` and this path is not included in the `PATH` you can specify its location on the command line
29
-
30
- $ asciidoctor -a diag_tool=/home/me/actdiag/bin/diag_tool -r asciidoctor-diagram sample.adoc
31
-
32
- The exact document attributes to use are described in the documentation of each diagram type.
@@ -1,19 +0,0 @@
1
- = Output Directories
2
-
3
- == Image Output Directory
4
-
5
- When Asciidoctor Diagram writes images to disk it will go over the following options in order to determine where to write the files.
6
-
7
- . `\{imagesoutdir\}` if the `imagesoutdir` attribute has been specified
8
- . `\{outdir\}/\{imagesdir\}` if the `outdir` attribute has been specified
9
- . `\{to_dir\}/\{imagesdir\}` if the `to_dir` attribute has been specified
10
- . `\{base_dir\}/\{imagesdir\}`
11
-
12
- == Image Cache Directory
13
-
14
- The image generation also outputs metadata files that by default are located in `.asciidoctor/diagram`.
15
- To place them in different location, Asciidoctor Diagram checks for (in this order).
16
-
17
- . `\{cachedir\}` attribute is specified in the block header (i.e. `[plantuml, png, cachedir=my-cache]`)
18
- . `\{diagram-cachedir\}` if the `diagram-cachedir` attribute has been specified
19
- . `\{outdir\}/\{imagesdir\}`
@@ -1,12 +0,0 @@
1
- [cols=">,<,<",options="header"]
2
- |===
3
- |Name |Default value |Description
4
- |svg-type |unspecified |One of `static`, `inline` or `interactive`.
5
- This determines the style of SVG embedding that's used in certain backends.
6
- The xref:asciidoc:macros:image-svg.adoc[asciidoc spec] describes this in more detail.
7
- |server-url |unspecified |External service to render diagram.
8
- Usage removes the need to depend on external tools to be installed locally.
9
- |server-type |unspecified |One of `plantuml` or `kroki_io`
10
- |max-get-size |1024 |The maximum size of the URI path for HTTP GET requests.
11
- If the maximum size is exceeded, POST requests are used instead
12
- |===
@@ -1,48 +0,0 @@
1
- :uri-a2s: https://github.com/asciitosvg/asciitosvg
2
- :uri-actdiag: http://blockdiag.com/en/actdiag/index.html
3
- :uri-asciidoctor-api: http://asciidoctor.org/docs/user-manual/#api
4
- :uri-asciidoctor-extensions: http://asciidoctor.org/docs/user-manual/#extension-points
5
- :uri-blockdiag: http://blockdiag.com
6
- :uri-bpmn: https://github.com/gtudan/bpmn-js-cmd
7
- :uri-bytefield: https://github.com/Deep-Symmetry/bytefield-svg
8
- :uri-d2: https://d2lang.com
9
- :uri-dbml: https://github.com/softwaretechnik-berlin/dbml-renderer
10
- :uri-diagrams: https://diagrams.mingrammer.com
11
- :uri-ditaa: http://ditaa.sourceforge.net/
12
- :uri-dpic: https://gitlab.com/aplevich/dpic
13
- :uri-dot: https://graphviz.gitlab.io/_pages/doc/info/lang.html
14
- :uri-erd: https://github.com/BurntSushi/erd
15
- :uri-erd-go: https://github.com/kaishuu0123/erd-go
16
- :uri-gnuplot: http://gnuplot.info
17
- :uri-graphviz: https://graphviz.gitlab.io
18
- :uri-imagemagick: http://www.imagemagick.org
19
- :uri-java: http://java.sun.com
20
- :uri-jsyntrax: https://atp-mipt.github.io/jsyntrax/
21
- :uri-lilypond: https://lilypond.org
22
- :uri-mermaid: https://github.com/mermaid-js/mermaid-cli
23
- :uri-mscgen: http://www.mcternan.me.uk/mscgen/
24
- :uri-mscgen-js: https://github.com/mscgenjs/mscgenjs-cli
25
- :uri-nomnoml: http://nomnoml.com
26
- :uri-nwdiag: http://blockdiag.com/en/nwdiag/index.html
27
- :uri-packetdiag: http://blockdiag.com/en/nwdiag/index.html
28
- :uri-penrose: https://penrose.cs.cmu.edu
29
- :uri-phantomjs: http://phantomjs.org
30
- :uri-pikchr: https://pikchr.org
31
- :uri-plantuml: http://plantuml.sourceforge.net
32
- :uri-py-plantuml: https://code.google.com/p/asciidoc-plantuml/
33
- :uri-python: https://www.python.org
34
- :uri-rackdiag: http://blockdiag.com/en/nwdiag/index.html
35
- :uri-seqdiag: http://blockdiag.com/en/seqdiag/index.html
36
- :uri-shaape: https://github.com/christiangoltz/shaape
37
- :uri-smcat: https://github.com/sverweij/state-machine-cat
38
- :uri-structurizr: https://structurizr.com
39
- :uri-svgbob: https://github.com/ivanceras/svgbobrus
40
- :uri-symbolator: https://github.com/kevinpt/symbolator
41
- :uri-syntrax: https://kevinpt.github.io/syntrax/
42
- :uri-tikz: https://github.com/pgf-tikz/pgf
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
data/examples/Gemfile DELETED
@@ -1,3 +0,0 @@
1
- source 'https://rubygems.org'
2
-
3
- gem "asciidoctor-diagram", :path => ".."
data/examples/README.adoc DELETED
@@ -1,18 +0,0 @@
1
- = Asciidoctor-diagram Examples
2
-
3
- This directory contains a number of example files that illustrate how to use the asciidoctor-diagram extension.
4
-
5
- In order to build the examples correctly the asciidoctor-diagram extension should be loaded.
6
- This can be done using bundler by running
7
-
8
- ----
9
- bundle exec asciidoctor -r asciidoctor-diagram <asciidoc file>
10
- ----
11
-
12
- If you do not want to use bundler you can alternatively run
13
-
14
- ----
15
- asciidoctor -r asciidoctor-diagram -I ../lib <asciidoc file>
16
- ----
17
-
18
- This variant requires you to explicitly specify the load path from which asciidoctor-diagram can be loaded.
data/examples/design.adoc DELETED
@@ -1,78 +0,0 @@
1
- = The design of Asciidoctor-diagram
2
-
3
- This document explains the design of Asciidoctor-diagram using PlantUML syntax.
4
- A detailed explanation of the PlantUML syntax is out scope for this document.
5
- This can be found on the http://www.plantuml.com[PlantUML web site].
6
-
7
- Asciidoctor-diagram is a simple Asciidoctor extension that enables embedding of diagrams inside asciidoc documents using various plain text diagram syntaxes.
8
- The current version of Asciidoctor-diagram support the Ditaa, Graphviz DOT and PlantUML syntax.
9
-
10
- Asciidoctor-diagram enables a number of new block types using the Asciidoctor `BlockProcessor` extension API.
11
-
12
- The main logic of the diagram generation is provided by the `DiagramBlock` module.
13
- 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.
14
- The DiagramBlock module also provides a means to register diagram output formats.
15
-
16
- When registering an output format, the registering code must specify a number of control parameters.
17
- The first parameter is the format name which controls when the generator is activated.
18
- The generator that is registered first determines the default format for the block.
19
- The second parameter is the output type of the generator.
20
- This is either `:image` or `:literal`.
21
- This parameter controls what type of block the `DiagramBlock` code will generate.
22
- Finally, a block should be provided that generates the diagram and returns it as a String.
23
- When called these blocks will receive the diagram source code and the parent Block as arguments.
24
-
25
- The actual `BlockProcessor` implementations include the `DiagramBlock` module and the appropriate generator module.
26
- The remainder of the implementation consists of registering format.
27
-
28
- The diagram below illustrates the relationship between the various classes and modules.
29
-
30
- .Asciidoctor-diagram class diagram
31
- [plantuml, "classes", align="center"]
32
- ----
33
- namespace asciidoctor.extensions {
34
- class BlockProcessor
35
- }
36
-
37
- namespace asciidoctor.diagram {
38
- asciidoctor.extensions.BlockProcessor <|-- DitaaBlock
39
- class DitaaGenerator << (M,#FF7700) >>
40
-
41
- asciidoctor.extensions.BlockProcessor <|-- GraphvizBlock
42
- asciidoctor.extensions.BlockProcessor <|-- PlantUmlBlock
43
- class PlantUmlGenerator << (M,#FF7700) >>
44
-
45
- class DiagramBlock << (M,#FF7700) >>
46
-
47
- DitaaBlock --|> DitaaGenerator
48
- DitaaBlock --|> DiagramBlock
49
- GraphvizBlock --|> PlantUmlGenerator
50
- GraphvizBlock --|> DiagramBlock
51
- PlantUmlBlock --|> PlantUmlGenerator
52
- PlantUmlBlock --|> DiagramBlock
53
- }
54
- ----
55
-
56
- When Asciidoctor process a document it will invoke the block processors at the appropriate moment.
57
- The sequence of method calls for a Ditaa block is shown below.
58
-
59
- .Processing a Ditaa block
60
- [plantuml, "processing", align="center"]
61
- ----
62
- Lexer->DiagramBlock : process
63
- activate DiagramBlock #FFBBBB
64
-
65
- DiagramBlock -> DiagramBlock: create_image_block
66
- activate DiagramBlock #DarkSalmon
67
-
68
- DiagramBlock -> DiagramBlock: code_checksum
69
-
70
- DiagramBlock -> DitaaGenerator: ditaa
71
- activate DitaaGenerator
72
- DiagramBlock <-- DitaaGenerator: image as String
73
- deactivate DitaaGenerator
74
- deactivate DiagramBlock
75
-
76
- Lexer <-- DiagramBlock: generated Block
77
- deactivate DiagramBlock
78
- ----
@@ -1,189 +0,0 @@
1
- = Asciidoctor-diagram features
2
-
3
- This document explains the various features of asciidoctor-diagram blocks using ditaa diagrams as an example.
4
-
5
- == Simple diagrams
6
-
7
- To mark a block as a diagram the appropriate style should be applied. This can be either `ditaa`, `graphviz` or `plantuml`.
8
- These styles can be applied to literal, listing or open blocks.
9
-
10
- A basic ditaa listing can be written as follows:
11
-
12
- ---------
13
- [ditaa]
14
- ----
15
- +-------------+
16
- | asciidoctor |-------+
17
- | diagram | |
18
- +-------------+ | png out
19
- ^ |
20
- | ditaa in |
21
- | v
22
- +--------+ +--------+----+ /---------------\
23
- | | --+ asciidoctor +--> | |
24
- | Text | +-------------+ |Beatiful output|
25
- |Document| | !magic! | | |
26
- | {d}| | | | |
27
- +---+----+ +-------------+ \---------------/
28
- : ^
29
- | Lots of work |
30
- +-----------------------------------+
31
- ----
32
- ---------
33
-
34
- results in the following image.
35
-
36
- [ditaa]
37
- ----
38
- +-------------+
39
- | asciidoctor |-------+
40
- | diagram | |
41
- +-------------+ | png out
42
- ^ |
43
- | ditaa in |
44
- | v
45
- +--------+ +--------+----+ /---------------\
46
- | | --+ asciidoctor +--> | |
47
- | Text | +-------------+ |Beatiful output|
48
- |Document| | !magic! | | |
49
- | {d}| | | | |
50
- +---+----+ +-------------+ \---------------/
51
- : ^
52
- | Lots of work |
53
- +-----------------------------------+
54
- ----
55
-
56
- == Controlling the file name
57
-
58
- The image above gets the file name `58372f7d2ceffae9e91fd0a7cbb080b6.png`.
59
- That long number is the checksum of the source code that was calculated by asciidoctor-diagram.
60
- If you want to give your generated files a more meaningful name, simply fill in the `target` attribute.
61
-
62
- This can be done by either specifying it as the first positional attribute or as a named attribute.
63
- Both examples below would result in a file called `ditaa-diagram.png`.
64
-
65
- ---------
66
- [ditaa, "ditaa-diagram"]
67
- ----
68
- <snip>
69
- ----
70
-
71
- [ditaa, target="ditaa-diagram"]
72
- ----
73
- <snip>
74
- ----
75
- ---------
76
-
77
- == Choosing an output format
78
-
79
- By default images are generated in `PNG` format.
80
- This can be overridden by defining the `format` (or 2nd positional) attribute.
81
- The set of supported formats is diagram type dependent.
82
- `ditaa` only supports the `png` format.
83
- `graphviz` supports `png` and `svg`.
84
- `plantuml` supports `png`, `svg` and `txt`.
85
-
86
- The `txt` format is perhaps a bit non-obvious.
87
- This generates an ascii art version of the UML diagrams.
88
-
89
- The following Graphviz DOT script
90
-
91
- ---------
92
- [graphviz, "dot_example", "svg"]
93
- ----
94
- graph ethane {
95
- C_0 -- H_0 [type=s];
96
- C_0 -- H_1 [type=s];
97
- C_0 -- H_2 [type=s];
98
- C_0 -- C_1 [type=s];
99
- C_1 -- H_3 [type=s];
100
- C_1 -- H_4 [type=s];
101
- C_1 -- H_5 [type=s];
102
- }
103
- ----
104
- ---------
105
-
106
- generates an SVG representation of an ethane molecule footnote:[From http://en.wikipedia.org/wiki/DOT_(graph_description_language)#A_simple_example]
107
-
108
- [graphviz, "dot_example", "svg"]
109
- ----
110
- graph ethane {
111
- C_0 -- H_0 [type=s];
112
- C_0 -- H_1 [type=s];
113
- C_0 -- H_2 [type=s];
114
- C_0 -- C_1 [type=s];
115
- C_1 -- H_3 [type=s];
116
- C_1 -- H_4 [type=s];
117
- C_1 -- H_5 [type=s];
118
- }
119
- ----
120
-
121
- With https://github.com/Alwinator/graphviz-py[graphviz_py] you can also use variables and Python code to do calculations:
122
-
123
- [graphviz_py, "graphviz_py_example", "svg"]
124
- ----
125
- graph python_graph {
126
- {{
127
- import math
128
-
129
- value = 0.5
130
- sin = math.sin(value)
131
- cos = math.cos(value)
132
- }}
133
-
134
- A [label="{{= value }}"];
135
- B [label="{{= sin }}"];
136
- C [label="{{= cos }}"];
137
-
138
- A -- B [headlabel="sin"];
139
- A -- C [headlabel="cos"];
140
-
141
- }
142
- ----
143
-
144
- Don't forget to install graphviz-py as described https://github.com/Alwinator/graphviz-py#installation[here].
145
-
146
- == Using standard asciidoc features
147
-
148
- Any remaining other attributes that are specified on a diagram block are copied over to the generated block.
149
- 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.
150
-
151
- Block titles and block ids can also be applied in the same way to diagram blocks.
152
-
153
- As an example, the following block
154
-
155
- --------
156
- [[plan]]
157
- .My plan to conquer the world
158
- [plantuml, align="center"]
159
- --------
160
-
161
- results in a block with the correct caption and id applied to it.
162
-
163
- [[plan]]
164
- .My plan to conquer the world
165
- [plantuml, "activity_diagram", "svg", align="center"]
166
- ----
167
- (*) --> "Create an Asciidoctor extension"
168
- "Create an Asciidoctor extension" --> " ? "
169
- " ? " --> "Profits!"
170
- "Profits!" --> (*)
171
- ----
172
-
173
- == Loading diagrams from external files
174
-
175
- Asciidoctor-diagram also supports the various diagram block in block macro form.
176
- These are macros of the form `<name>::<target>[<attrlist>]`.
177
-
178
- In asciidoctor-diagram the macro names are identical to the block styles: `ditaa`, `graphviz` and `plantuml`
179
- The target is the path to the file containing the diagram source code.
180
- When the target is a relative path it is resolved with respect to the location of the document being processed.
181
- The attribute list behaves mostly the same as with the block styles.
182
- The only difference is that the `target` attribute is not supported.
183
- Instead the name of the generated image is derived from the target propery of the macro.
184
-
185
- 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.
186
-
187
- ----
188
- plantuml::activity_diagram.txt[format="svg", align="center"]
189
- ----
data/spec/a2s_spec.rb DELETED
@@ -1,33 +0,0 @@
1
- require_relative 'test_helper_methods'
2
-
3
- A2S_CODE = <<-eos
4
- .--. .---. .---. .---. .---. .---. .---.
5
- | | OS API '---' '---' '---' '---' '---' '---'
6
- v | | | | | | |
7
- .-. .-. .-. | v v | v | v
8
- .-->'-' '-' '-' | .------------. | .-----------. | .-----.
9
- | \\ | / | | Filesystem | | | Scheduler | | | MMU |
10
- | v . v | '------------' | '-----------' | '-----'
11
- '_______/ \\_____| | | | |
12
- \\ / v | | v
13
- | ____ .----. | | .---------.
14
- '--> /___/ | IO |<----' | | Network |
15
- '----' | '---------'
16
- | | |
17
- v v v
18
- .---------------------------------------.
19
- | HAL |
20
- '---------------------------------------'
21
- eos
22
-
23
- describe Asciidoctor::Diagram::AsciiToSvgInlineMacroProcessor do
24
- include_examples "inline_macro", :a2s, A2S_CODE, [:svg]
25
- end
26
-
27
- describe Asciidoctor::Diagram::AsciiToSvgBlockMacroProcessor do
28
- include_examples "block_macro", :a2s, A2S_CODE, [:svg, :txt]
29
- end
30
-
31
- describe Asciidoctor::Diagram::AsciiToSvgBlockProcessor do
32
- include_examples "block", :svgbob, A2S_CODE, [:svg, :txt]
33
- end