metanorma-plugin-plantuml 1.0.2 → 1.0.4

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.
+
 
+=== Command syntax for external diagrams
 
-=== Basic syntax
+PlantUML diagrams can be directly referenced from external files using the
+`plantuml_image::{path}[{options}]` command.
 
-==== Block style
+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:
+
+* 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.
+
+* 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`
 
-==== Document-level includedirs configuration
+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.
 
-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:
+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.
 
-==== Block-level includedirs configuration
+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.
+====
+
+
+==== 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 my-custom-name
+@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 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.
+====
 
 
-=== Configuration options
 
-==== Disable PlantUML processing
+=== Disable PlantUML processing
 
-Disable PlantUML processing document-wide:
+It is possible to disable PlantUML processing either document-wide or via an
+environment variable.
+
+When disabled, PlantUML blocks are rendered as code listings instead of
+diagrams.
+
+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
@@ -453,6 +832,8 @@ PlantUML versions:
 | Gem version | PlantUML version | Notes
 
 | 1.0.0       | 1.2025.4        | Latest release with updated architecture
+| 1.0.4       | 1.2025.7        | Latest release
+
 |===
 
 This approach allows the gem to follow standard semantic versioning practices
@@ -460,54 +841,133 @@ while clearly documenting which PlantUML version is bundled with each release.
 
 === Updating PlantUML version
 
-This gem bundles a specific version of PlantUML JAR file. To update to a newer
-version:
+==== General
+
+This gem bundles a specific version of PlantUML JAR file.
+
+There are two ways to update to a newer version.
+
+==== Automatic update (recommended)
+
+The simplest way to update PlantUML is to use the automated update task:
+
+[source,console]
+----
+$ bundle exec rake update_plantuml
+----
+
+This task will:
+
+* Search GitHub for the latest valid PlantUML release (excluding pre-releases and native builds)
+* Compare with the current version and skip if already up to date
+* Update version files automatically (both PlantUML and gem versions)
+* Download and verify the new JAR file
+* Test the JAR functionality to ensure it works correctly
+
+The task uses exit codes to indicate the result:
+
+* Exit code 0: No update needed (already up to date)
+* Exit code 1: Update completed successfully
+* Exit code 2: Update failed due to an error
+
+==== Manual update
+
+For manual updates or to specify a particular version:
 
 . Check the latest PlantUML release at
 https://github.com/plantuml/plantuml/releases
 
-. Update the version in `lib/metanorma/plugin/plantuml/version.rb`:
+. Use the manual version update task:
 +
-[source,ruby]
+[source,console]
 ----
-PLANTUML_JAR_VERSION = "1.2025.4"  # Update to latest version
-VERSION = "1.0.1"                  # Increment patch version
+$ bundle exec rake update_plantuml_version[1.2025.7]
 ----
 
-. Clean the old JAR file:
+. Download the new JAR file:
 +
 [source,console]
 ----
-$ bundle exec rake clean_jar
+$ bundle exec rake clean_jar download_jar
 ----
 
-. Download the new JAR file:
+. Test the functionality:
 +
 [source,console]
 ----
-$ bundle exec rake download_jar
+$ bundle exec rake test_plantuml
 ----
 
-. Run tests to ensure everything works:
-+
+==== Version checking
+
+You can check the current PlantUML and gem versions:
+
 [source,console]
 ----
-$ bundle exec rake spec
+$ bundle exec rake check_plantuml_version
 ----
 
-. Update the gem version by incrementing the patch version (e.g., `1.0.0` →
-`1.0.1`) for PlantUML updates, or increment minor/major versions for gem feature
-updates.
+You can find the latest available PlantUML version:
+
+[source,console]
+----
+$ bundle exec rake find_latest_plantuml
+----
 
 === Available rake tasks
 
+==== PlantUML management tasks
+
 [source,console]
 ----
-$ bundle exec rake download_jar  # Download PlantUML JAR file
-$ bundle exec rake clean_jar     # Remove downloaded JAR file
-$ bundle exec rake spec          # Run tests
+$ bundle exec rake update_plantuml                    # Update PlantUML to latest version (automatic)
+$ bundle exec rake update_plantuml_version[VERSION]   # Update PlantUML to specific version (manual)
+$ bundle exec rake check_plantuml_version             # Check current PlantUML and gem versions
+$ bundle exec rake find_latest_plantuml               # Find latest valid PlantUML release
+$ bundle exec rake test_plantuml                      # Test PlantUML JAR functionality
 ----
 
+==== JAR file management tasks
+
+[source,console]
+----
+$ bundle exec rake download_jar    # Download PlantUML JAR file
+$ bundle exec rake clean_jar       # Remove downloaded JAR file
+----
+
+==== Development tasks
+
+[source,console]
+----
+$ bundle exec rake spec            # Run tests
+$ bundle exec rake                 # Default task: download JAR + run tests
+----
+
+==== Task descriptions
+
+`update_plantuml`:: Automatically finds the latest valid PlantUML release,
+updates version files, downloads the new JAR, and tests functionality. This is
+the recommended way to update PlantUML.
+
+`update_plantuml_version[VERSION]`:: Manually updates the PlantUML version in
+`version.rb` to the specified version and increments the gem version. Use this
+when you need to specify a particular PlantUML version.
+
+`check_plantuml_version`:: Displays the current PlantUML JAR version and gem
+version from `version.rb`.
+
+`find_latest_plantuml`:: Searches GitHub for the latest valid PlantUML release,
+filtering out pre-releases, native builds, and invalid versions. Shows the
+version and release information.
+
+`test_plantuml`:: Tests the downloaded PlantUML JAR by running version checks
+and generating a test diagram to ensure functionality.
+
+`download_jar`:: Downloads the PlantUML JAR file based on the version specified
+in `version.rb`. Creates the `data/` directory if it doesn't exist.
+
+`clean_jar`:: Removes the downloaded PlantUML JAR file from `data/plantuml.jar`.
+
 == Documentation
 
 Please refer to https://www.metanorma.org.