metanorma-plugin-plantuml 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b3797ddb4db236753261836d74b360e635c58ea3b0eeaa09dfc1c7192dacf78
-  data.tar.gz: 0aba3ecbbc90f15570887ea206fa0a0c19b6d3179a7d9481438fb480df305873
+  metadata.gz: c7c85595e30e3155c473b4f44936209c3f95c8ab5cf29d55a2368bad6584c136
+  data.tar.gz: d7e58a9934d9995c9b36c3b86dc543a7c633d0c31fab5dd543707b7f347207c8
 SHA512:
-  metadata.gz: ed86eced1c2c434f17ce4f3f5307c88f349c30275ad2051ea7c6063feb1d13ca6c64480ea406951221a75ceececd035ffed82519d9dfe169205f55a160996c9b
-  data.tar.gz: 2e1488a69e6c3ff71a88c17778fead0b264ed2b6c8d2a7d8803e04441d0d7f1b4b2cebdd102050e6428500a477a876d6f3cc8cdf9882da007a7bc6900a19cffa
+  metadata.gz: '05039945787b1a1d65f8a37193db39346f2d42ac820dff54d70724fbb09bdbe2808a9ca20477a78e78b1357f65de337c289a075feabf27c9e3ae92264e671865'
+  data.tar.gz: 1cff1673fbed5b3e00a6e05d7642cccce29e6d5f5d2cd62500860fddf089a8fc7046a2c49df41b422804b03eb762bd0bb6ac21d67e8763e6d38583f29df4e0ed

data/.github/workflows/rake.yml

@@ -10,6 +10,6 @@ on:
 
 jobs:
   rake:
-    uses: metanorma/ci/.github/workflows/plantuml-rake.yml@main
+    uses: metanorma/ci/.github/workflows/generic-rake.yml@main
     secrets:
       pat_token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}

data/README.adoc

@@ -4,7 +4,7 @@ image:https://github.com/metanorma/metanorma-plugin-plantuml/workflows/rake/badg
 
 == Purpose
 
-This is a Metanorma plugin to enable usage of PlantUML diagrams in Metanorma
+This Metanorma plugin enables the usage of PlantUML diagrams in Metanorma
 documents.
 
 It provides a Ruby API that wraps a bundled PlantUML JAR file.
@@ -59,47 +59,152 @@ $ gem install metanorma-plugin-plantuml
 
 == Usage
 
+=== General
+
 This plugin enables PlantUML diagram generation in Metanorma documents through
-the `plantuml` block directive.
+multiple methods, including:
+
+* Block syntax using `[plantuml]` blocks
+* Command syntax using `plantuml_image::{path}[{options}]`
+
+Both syntaxes support various diagram types, output formats, and image
+attributes, as well as PlantUML's `include!` and `includesub!` directives for
+modular diagrams.
+
+The effect of both syntaxes is the same: they generate and embed PlantUML diagrams
+as images in the output document.
+
+However, there are important differences in using them with external files, as
+it is described in the various options.
+
+The difference lies in how the PlantUML source is provided:
+
+* In the block syntax, the PlantUML source is defined directly within the
+document, and hence generated by PlantUML without a specific file context.
+
+* In the command syntax, the PlantUML source is read from an external file,
+which provides a file context for the PlantUML source.
 
+Generally, the command syntax is more suitable for referencing external PlantUML
+files.
 
-=== Basic syntax
 
-==== Block style
+=== Command syntax for external diagrams
+
+PlantUML diagrams can be directly referenced from external files using the
+`plantuml_image::{path}[{options}]` command.
+
+Syntax:
 
 [source,asciidoc]
 ----
-[plantuml]
-....
+plantuml_image::{plantuml-source.puml}[{options}]
+----
+
+Where,
+
+`{plantuml-source.puml}`:: Path to the PlantUML source file, relative to the
+path of the current file.
+
+`{options}`:: (Optional) Comma-separated list of options to customize diagram
+generation.
+
+.Specifying an external PlantUML diagram using the `plantuml_image` command without options
+[example]
+====
+[source,asciidoc]
+----
+plantuml_image::foo/bar.puml[]
+----
+
+The file `foo/bar.puml` looks like:
+
+[source,plantuml]
+----
 @startuml
 Alice -> Bob: Hello
 Bob -> Alice: Hi there
 @enduml
+----
+====
+
+.Specifying an external PlantUML diagram using the `plantuml_image` command with options
+[example]
+====
+[source,asciidoc]
+----
+plantuml_image::foo/bar.puml[format=svg]
+----
+
+The file `foo/bar.puml` is the same as above.
+The `format=svg` option specifies the output format as SVG.
+====
+
+
+
+=== Block syntax for inline diagrams
+
+PlantUML diagrams can be defined directly within your Metanorma document using
+`[plantuml]` blocks.
+
+Syntax:
+
+[source,asciidoc]
+----
+[plantuml]
+....
+{PlantUML diagram source here}
 ....
 ----
 
-==== Block macro style
+Where,
+
+`[plantuml]`:: Specifies that the block contains PlantUML source code.
+
+`....`:: Delimiters that indicate the start and end of the PlantUML source code.
+
+`{PlantUML diagram source here}`:: The actual PlantUML diagram definition using
+PlantUML syntax.
+
+
+The block can be used with or without options.
+
+Syntax with options:
 
 [source,asciidoc]
 ----
-plantuml_image::path/to/my-plantuml.puml[]
+[plantuml,{options}]
+....
+{PlantUML diagram source here}
+....
 ----
 
-The file `path/to/my-plantuml.puml` looks like:
-[source,plantuml]
+Where,
+
+`{options}`:: Comma-separated list of options to customize diagram generation.
+
+
+.Specifying a simple PlantUML diagram in the `[plantuml]` block
+[example]
+====
+[source,asciidoc]
 ----
+[plantuml]
+....
 @startuml
 Alice -> Bob: Hello
 Bob -> Alice: Hi there
 @enduml
+....
 ----
+====
+
 
-`plantuml_image` block macro performs the same function as the `plantuml` block,
-but the PlantUML diagram is defined in a separate file instead of a block.
 
 === Supported diagram types
 
-PlantUML supports various diagram types, each with its own `@start` and `@end` directives:
+PlantUML, and therefore this plugin, supports various diagram types, each with
+its own `@start` and `@end` directives:
 
 `@startuml` / `@enduml`:: UML diagrams (sequence, class, activity, etc.)
 `@startmindmap` / `@endmindmap`:: Mind map diagrams
@@ -150,12 +255,40 @@ Bob --> Alice: Authentication Response
 ----
 ====
 
+
 === Format options
 
 ==== Single format specification
 
-Specify the output format using the `format` attribute:
+The output format is specified using the `format` option, which can be applied
+in both block and command syntaxes.
+
+Block syntax:
+
+[source,adoc]
+----
+[plantuml,format={format}]
+----
+
+Command syntax:
+
+[source,adoc]
+----
+plantuml_image::{path}[format={format}]
+----
+
+Where `{format}` can be one of the following:
 
+`png`:: (default) Portable Network Graphics
+`svg`:: Scalable Vector Graphics
+`pdf`:: Portable Document Format
+`txt`:: ASCII art text output
+`eps`:: Encapsulated PostScript
+
+
+.Block syntax with format option
+[example]
+====
 [source,asciidoc]
 ----
 [plantuml,format=svg]
@@ -165,19 +298,47 @@ Alice -> Bob: Hello
 @enduml
 ....
 ----
+====
 
-Supported formats:
+.Command syntax with format option
+[example]
+====
+[source,asciidoc]
+----
+plantuml_image::path/to/my-plantuml.puml[format=svg]
+----
+====
 
-`png`:: (default) Portable Network Graphics
-`svg`:: Scalable Vector Graphics
-`pdf`:: Portable Document Format
-`txt`:: ASCII art text output
-`eps`:: Encapsulated PostScript
 
 ==== Multiple format generation
 
-Generate multiple formats simultaneously using the `formats` attribute:
+It is possible to generate multiple output formats simultaneously by specifying
+the `formats` option, which accepts a comma-separated list of formats.
+
+While Metanorma does not currently support embedding multiple images for a single
+diagram, generating multiple formats can be useful for documentation or other
+purposes.
+
+Block syntax:
+
+[source,adoc]
+----
+[plantuml,formats="{format1},{format2},..."]
+----
+
+Command syntax:
+
+[source,adoc]
+----
+plantuml_image::{path}[formats="{format1},{format2},..."]
+----
+
+Where `{format1}`, `{format2}`, etc. can be any of the supported formats listed
+above.
 
+.Block syntax with multiple formats
+[example]
+====
 [source,asciidoc]
 ----
 [plantuml,formats="png,svg,pdf"]
@@ -187,11 +348,26 @@ Alice -> Bob: Hello
 @enduml
 ....
 ----
+====
+
 
 ==== Document-level format configuration
 
-Set the default format for all PlantUML diagrams in your document:
+The default format for all PlantUML diagrams in a document can be set using the
+`plantuml-image-format` document attribute.
+
+Syntax:
 
+[source,asciidoc]
+----
+:plantuml-image-format: {format}
+----
+
+Where `{format}` can be any of the supported formats listed above.
+
+.Document with document-level format configuration
+[example]
+====
 [source,asciidoc]
 ----
 :plantuml-image-format: svg
@@ -203,14 +379,82 @@ Alice -> Bob: Hello
 @enduml
 ....
 ----
+====
+
+=== Using `!include` and `!includesub`
+
+==== General
+
+PlantUML supports modular diagram definitions using the `!include` and
+`!includesub` directives to include external PlantUML files or specific parts of
+them.
+
+PlantUML is able to resolve relative paths in these directives based on the context
+of the PlantUML source.
+
+This is where the behavior differs between the block syntax and the command
+syntax:
 
-==== Document-level includedirs configuration
+* In the block syntax, as the PlantUML source is defined inline within the
+document, there is no associated file path for the PlantUML source. The
+consequence is that PlantUML cannot resolve relative paths in `!include` or
+`!includesub` directives, as there is no associated file path. In order to
+resolve includes, you must specify the `includedirs` option to provide
+directories to search for included files.
 
-When using `!include` or `!includesub` in your PlantUML diagrams, you can set
-the default include directories (separated by semicolons) by
-`plantuml-includedirs` to search for files for all PlantUML diagrams in your
-document:
+* In the command syntax, the PlantUML source is read from an external file. This
+means that relative paths in `!include` or `!includesub` directives are resolved
+relative to the location of the PlantUML source file. The `includedirs` option
+is not needed for resolving includes, but can still be used to add additional
+directories to search.
 
+
+==== Setting `includedirs`
+
+PlantUML allows you to specify include directories using the `includedirs`
+option. This option can be set at both the document level and the block level,
+through the option of the same name.
+
+There are two ways to set `includedirs`:
+
+* Document-level configuration using the `plantuml-includedirs` document attribute
+
+* The `includedirs` option in the `[plantuml]` block or `plantuml_image` command
+
+Note that when using the `plantuml_image` command, the directory that contains
+the specified PlantUML file will be automatically added as one of the
+`includedirs` directories. This means that any relative includes in the PlantUML
+file will be resolved relative to the file's location, even if `includedirs` is
+not explicitly set.
+
+
+==== Document-level `plantuml-includedirs` attribute
+
+It is possible to set default include directories (separated by semicolons) for
+all PlantUML diagrams in a document using the `plantuml-includedirs` document
+attribute.
+
+This is useful when a document contains multiple PlantUML diagrams that share
+common include files stored in specific directories, e.g. style definitions.
+
+The directories specified in this attribute will be used as the default include
+paths for all PlantUML diagrams in the document, including for both `[plantuml]`
+blocks and `plantuml_image` commands.
+
+NOTE: When using the `plantuml_image` command, the directory that contains the
+specified PlantUML file will always be automatically added as one of the
+`includedirs` directories.
+
+Syntax:
+
+[source,asciidoc]
+----
+:plantuml-includedirs: {path1};{path2};...
+----
+
+.Resolving PlantUML includes with document-level `includedirs` attribute
+[example]
+====
 [source,asciidoc]
 ----
 :plantuml-includedirs: path/to/plantuml/include-1;path/to/plantuml/include-2
@@ -243,14 +487,19 @@ title this contains only B and D
 ....
 ----
 
-This plugin will search the include directories specified by
-`includedirs` options (i.e. `path/to/plantuml/include-1` and
-`path/to/plantuml/include-2`) for the files referenced in `!include` or
-`!includesub` directives (i.e. `sequences.puml`, `components.puml` and
-`subpart.puml`).
+These `[plantuml]` blocks use `!include` and `!includesub` directives to include
+external PlantUML files. PlantUML will search the include directories specified
+by `includedirs` options to find `sequences.puml`, `components.puml` and
+`subpart.puml`, at:
+
+* `path/to/plantuml/include-1`
+* `path/to/plantuml/include-2`
+====
 
-You can also use `plantuml_image` to include external PlantUML files as images:
 
+.Resolving PlantUML includes in `plantuml_image` command with document-level `includedirs` attribute
+[example]
+====
 [source,asciidoc]
 ----
 :plantuml-includedirs: path/to/plantuml/include-1;path/to/plantuml/include-2
@@ -260,7 +509,8 @@ plantuml_image::path/to/my-plantuml-1.puml[]
 plantuml_image::path/to/my-plantuml-2.puml[]
 ----
 
-The file `path/to/my-plantuml-1.puml` looks like:
+With `path/to/my-plantuml-1.puml` as:
+
 [source,plantuml]
 ----
 @startuml
@@ -268,7 +518,8 @@ The file `path/to/my-plantuml-1.puml` looks like:
 @enduml
 ----
 
-The file `path/to/my-plantuml-2.puml` looks like:
+With `path/to/my-plantuml-2.puml` as:
+
 [source,plantuml]
 ----
 @startuml
@@ -281,16 +532,48 @@ APIGateway --> DB
 @enduml
 ----
 
-When using `plantuml_image`, the path of the directory of the PlantUML file will
-also be added into the `includedirs`. (i.e. `path/to` will be added to
-`includedirs`)
+In using the `plantuml_image` command, the directory containing each PlantUML file
+(`path/to` in this case) is automatically added to the `includedirs`.
+
+Thus in rendering `path/to/my-plantuml-1.puml`, PlantUML will search for
+`sequences.puml` in both `path/to` and the directories specified by the
+`plantuml-includedirs` attribute.
+
+Similarly, in rendering `path/to/my-plantuml-2.puml`, PlantUML will search for
+`components.puml` in both `path/to` and the directories specified by the
+`plantuml-includedirs` attribute.
+====
+
 
-==== Block-level includedirs configuration
+==== Diagram-level `includedirs` option
 
-When using `!include` or `!includesub` in your PlantUML diagrams, you can set
-the default include directories (separated by semicolons) by `includedirs` in
-block-level to search for files for the PlantUML diagram defined in your block:
+The `includedirs` option can be used to specify include directories (separated
+by semicolons) for both `[plantuml]` blocks and the `plantuml_image` command.
 
+This option applies only to a single diagram in the document without affecting
+others.
+
+The diagram-level `includedirs` configuration can be used together with the
+document-level configuration to provide more granular control over include
+paths, where it is considered to have higher precedence than the document-level
+configuration.
+
+Syntax:
+
+[source,asciidoc]
+----
+[plantuml,includedirs="{path1};{path2};..."]
+----
+
+Where,
+
+`{path1}`, `{path2}`, etc.:: paths to directories containing PlantUML files to
+be included, delimited by semicolons.
+
+
+.Resolving PlantUML includes using diagram-level `includedirs` in `[plantuml]` blocks
+[example]
+====
 [source,asciidoc]
 ----
 [plantuml,includedirs="path/to/plantuml/include-1"]
@@ -315,25 +598,64 @@ APIGateway --> DB
 
 This plugin will search `sequences.puml` in `path/to/plantuml/include-1` and
 `components.puml` in `path/to/plantuml/include-2`.
+====
 
-The block-level `includedirs` configuration can be used together with the
-document-level configuration to provide more granular control over include
-paths.  You can set multiple paths by separating them with semicolons.
-
-You can also use `plantuml_image` to set `includedirs` option to include
-external PlantUML files:
 
+.Resolving PlantUML includes using diagram-level `includedirs` with `plantuml_image` command
+[example]
+====
 [source,asciidoc]
 ----
 plantuml_image::path/to/my-plantuml-1.puml[includedirs=path/to/plantuml/include-1]
 
 plantuml_image::path/to/my-plantuml-2.puml[includedirs=path/to/plantuml/include-2]
 ----
+====
+
 
 === Image attributes
 
-Standard AsciiDoc image attributes are supported:
+The block and command syntaxes both support standard AsciiDoc image attributes
+to customize the appearance and behavior of the generated PlantUML diagrams.
+
+Supported attributes are as follows:
+
+`id`:: Element identifier
+`title`:: Image title/caption
+`alt`:: Alternative text
+`width`:: Image width
+`height`:: Image height
+`align`:: Alignment (left, center, right)
+`float`:: Float positioning
+`role`:: CSS class/role
+
+
+Block syntax:
 
+[source,asciidoc]
+----
+[plantuml,{image-attributes}]
+....
+{PlantUML diagram source here}
+....
+----
+
+Command syntax:
+
+[source,asciidoc]
+----
+plantuml_image::{path}[{image-attributes}]
+----
+
+Where,
+
+`{image-attributes}`:: Comma-separated list of AsciiDoc image attributes in
+`key=value` format.
+
+
+.Specifying image attributes in `[plantuml]` block
+[example]
+====
 [source,asciidoc]
 ----
 [plantuml,id=my-diagram,title="My Sequence Diagram",width=600,height=400]
@@ -343,46 +665,88 @@ Alice -> Bob: Hello
 @enduml
 ....
 ----
+====
 
-Supported attributes:
-
-`id`:: Element identifier
-`title`:: Image title/caption
-`alt`:: Alternative text
-`width`:: Image width
-`height`:: Image height
-`align`:: Alignment (left, center, right)
-`float`:: Float positioning
-`role`:: CSS class/role
 
 === Filename specification
 
-Specify custom filenames within the PlantUML source:
+PlantUML supports specifying custom filenames for generated diagrams using the
+`@start{type} [filename]` directive, where `{type}` is the diagram type (e.g.,
+`uml`, `mindmap`, etc.) and `filename` is the desired name for the output
+file.
+
+This feature is not well documented in official PlantUML documentation, but is
+described at:
+
+* PlantUML Language Reference Guide, 4.7, where `@startuml PERT` is used
+* https://forum.plantuml.net/19896/name-conventions-for-%40startuml-filename[PlantUML Forum: Name conventions for @startuml filename]
+* https://forum.plantuml.net/5483/please-specify-filename-%40startuml-extension-automatically[PlantUML Forum: Please specify filename @startuml extension automatically]
+
+When a custom filename is specified, PlantUML generates the output file using
+the specified filename and the appropriate file extension based on the diagram
+type.
+
+This custom filename feature is supported in both block and command syntaxes.
+
+Syntax:
+
+[source,asciidoc]
+----
+[plantuml]
+....
+@startuml {custom-filename}
+{PlantUML diagram source here}
+@enduml
+....
+----
+
+Where,
 
+`{custom-filename}`:: Desired name for the generated diagram file, without
+file extension.
+
+.Specifying a custom filename in `[plantuml]` block
+[example]
+====
 [source,asciidoc]
 ----
 [plantuml]
 ....
-@startuml my-custom-name
+@startuml AliceToBob
 Alice -> Bob: Hello
 @enduml
 ....
 ----
 
-This generates `my-custom-name.png` (or specified format) instead of an
-auto-generated filename.
+This generates `AliceToBob.png` (which is the default format since none was
+specified) instead of an auto-generated filename. This file is then embedded in
+the output document using the specified filename.
+====
+
+
 
+=== Disable PlantUML processing
 
-=== Configuration options
+It is possible to disable PlantUML processing either document-wide or via an
+environment variable.
 
-==== Disable PlantUML processing
+When disabled, PlantUML blocks are rendered as code listings instead of
+diagrams.
 
-Disable PlantUML processing document-wide:
+The `:plantuml-disabled:` document attribute can be used to disable PlantUML
+processing for a specific document.
+
+Syntax:
 
 [source,asciidoc]
 ----
 :plantuml-disabled:
+----
 
+[example]
+====
+[source,asciidoc]
+----
 [plantuml]
 ....
 @startuml
@@ -391,22 +755,36 @@ Alice -> Bob: Hello
 ....
 ----
 
-When disabled, PlantUML blocks are rendered as code listings instead of diagrams.
+This renders the PlantUML block as a code listing instead of a diagram.
+====
 
-==== Environment variable
+The same effect can be achieved using by setting the `PLANTUML_DISABLED`
+environment variable to `true`.
 
-Disable PlantUML processing via environment variable:
+Syntax:
 
+[source,console]
+----
+$ PLANTUML_DISABLED=true metanorma ...
+----
+
+[example]
+====
 [source,console]
 ----
 $ PLANTUML_DISABLED=true metanorma document.adoc
 ----
+====
+
 
 === File organization
 
-Generated PlantUML images are stored in the `_plantuml_images/` directory
-relative to your document location. This directory is automatically created if
-it doesn't exist.
+Generated PlantUML images are stored in a `_plantuml_images/` directory
+relative to the document location (the document root, if it is made of multiple
+files).
+
+This directory is automatically created if it doesn't exist.
+
 
 == Development
 
@@ -417,21 +795,22 @@ Metanorma integration and PlantUML execution:
 
 [source]
 ----
-Metanorma Document
-      ↓
-BlockProcessor ← (processes [plantuml] blocks) or ImageBlockMacroProcessor ← (processes plantuml_image::{path}[{options}] macros)
-      ↓
-Backend ← (Metanorma integration, paths, validation)
-      ↓
-Wrapper ← (Java/JAR execution, file I/O)
-      ↓
-PlantUML JAR ← (diagram generation)
+  Metanorma Document
+          ↓
+    BlockProcessor ← (processes `[plantuml]` blocks)
+and ImageBlockMacroProcessor ← (processes `plantuml_image::` commands)
+          ↓
+      Backend ← (Metanorma integration, paths, validation)
+          ↓
+      Wrapper ← (Java/JAR execution, file I/O)
+          ↓
+    PlantUML JAR ← (diagram generation)
 ----
 
 `BlockProcessor`:: Processes `[plantuml]` blocks in Metanorma documents and
 integrates with the Metanorma rendering pipeline.
 
-`ImageBlockMacroProcessor`:: Processes `plantuml_image::{path}[{options}]` macros
+`ImageBlockMacroProcessor`:: Processes `plantuml_image::{path}[{options}]` commands
 in Metanorma documents and integrates with the Metanorma rendering pipeline.
 
 `Backend`:: Handles Metanorma-specific logic including document paths, PlantUML

data/lib/metanorma/plugin/plantuml/block_processor.rb

@@ -3,7 +3,7 @@
 module Metanorma
   module Plugin
     module Plantuml
-      # PlantUML block processor for Asciidoctor
+      # PlantUML block processor
       class BlockProcessor < ::Asciidoctor::Extensions::BlockProcessor
         include ::Metanorma::Plugin::Plantuml::BlockProcessorBase
         use_dsl
@@ -37,9 +37,8 @@ module Metanorma
           options = {}
 
           # Parse include directory
-          options[:includedirs] = parse_doc_includedirs(parent.document)
           options[:includedirs] = add_attrs_to_includedirs(
-            parent.document, attrs, options[:includedirs]
+            parent.document, attrs, parse_doc_includedirs(parent.document)
           )
 
           options

data/lib/metanorma/plugin/plantuml/image_block_macro_processor.rb

@@ -3,7 +3,7 @@
 module Metanorma
   module Plugin
     module Plantuml
-      # PlantUML block processor for Asciidoctor
+      # PlantUML block processor
       class ImageBlockMacroProcessor < ::Asciidoctor::Extensions::BlockMacroProcessor
         include ::Metanorma::Plugin::Plantuml::BlockProcessorBase
         use_dsl

data/lib/metanorma/plugin/plantuml/version.rb

@@ -1,7 +1,7 @@
 module Metanorma
   module Plugin
     module Plantuml
-      VERSION = "1.0.2".freeze
+      VERSION = "1.0.3".freeze
       PLANTUML_JAR_VERSION = "1.2025.4".freeze
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-plugin-plantuml
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Ribose Inc.