metanorma-plugin-plantuml 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 82db5cce760911ac43ad666a3d25e800341ff7b4f591d0905562f2e8bccb99e2
+  data.tar.gz: 170923ac6b7ace25020922e57904417ced9a3ef6d6f311a83be9ce0ab65b281f
+SHA512:
+  metadata.gz: 1347f4e1aab08371499c23dd2b39dfdc3aa3371f1db258ffa36ad557513a915e30b70e470df5f37d5766df38ca106dc54cbaad146f09cb135dfa1c41cab5e5f7
+  data.tar.gz: 1bb6c111325ab23cbe83f3c1903701740c31573f1baa80760c03f467559c07111b81ab80fc99afbda6de0445e5dab9e1c4cf58f96fb92e24a8552f7e1946a1d6

data/.github/workflows/plantuml-version-sync.yml

@@ -0,0 +1,113 @@
+name: PlantUML Version Sync
+
+on:
+  schedule:
+    # Check for new PlantUML releases daily at 6 AM UTC
+    - cron: '0 6 * * *'
+  workflow_dispatch:
+    # Allow manual triggering
+
+jobs:
+  check-plantuml-version:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.1'
+          bundler-cache: true
+
+      - name: Get current PlantUML version
+        id: current-version
+        run: |
+          CURRENT_VERSION=$(ruby -e "require './lib/metanorma/plugin/plantuml/version'; puts Metanorma::Plugin::Plantuml::PLANTUML_JAR_VERSION")
+          echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+
+      - name: Get latest PlantUML release
+        id: latest-version
+        run: |
+          LATEST_VERSION=$(curl -s https://api.github.com/repos/plantuml/plantuml/releases/latest | jq -r .tag_name | sed 's/^v//')
+          echo "version=$LATEST_VERSION" >> $GITHUB_OUTPUT
+
+      - name: Compare versions
+        id: compare
+        run: |
+          if [ "${{ steps.current-version.outputs.version }}" != "${{ steps.latest-version.outputs.version }}" ]; then
+            echo "needs_update=true" >> $GITHUB_OUTPUT
+            echo "Current version: ${{ steps.current-version.outputs.version }}"
+            echo "Latest version: ${{ steps.latest-version.outputs.version }}"
+          else
+            echo "needs_update=false" >> $GITHUB_OUTPUT
+            echo "PlantUML version is up to date"
+          fi
+
+      - name: Update version file
+        if: steps.compare.outputs.needs_update == 'true'
+        run: |
+          NEW_VERSION="${{ steps.latest-version.outputs.version }}"
+          sed -i "s/PLANTUML_JAR_VERSION = \".*\"/PLANTUML_JAR_VERSION = \"$NEW_VERSION\"/" lib/metanorma/plugin/plantuml/version.rb
+
+      - name: Update gem version
+        if: steps.compare.outputs.needs_update == 'true'
+        run: |
+          # Increment patch version using semantic versioning
+          CURRENT_GEM_VERSION=$(ruby -e "require './lib/metanorma/plugin/plantuml/version'; puts Metanorma::Plugin::Plantuml::VERSION")
+          NEW_GEM_VERSION=$(ruby -e "
+            require 'rubygems'
+            current_version = Gem::Version.new('$CURRENT_GEM_VERSION')
+            segments = current_version.segments
+            segments[2] = (segments[2] || 0) + 1
+            puts segments.join('.')
+          ")
+          sed -i "s/VERSION = \".*\"/VERSION = \"$NEW_GEM_VERSION\"/" lib/metanorma/plugin/plantuml/version.rb
+          echo "Updated gem version from $CURRENT_GEM_VERSION to $NEW_GEM_VERSION"
+
+      - name: Remove old JAR and download new one
+        if: steps.compare.outputs.needs_update == 'true'
+        run: |
+          rm -f data/plantuml.jar
+          bundle exec rake download_jar
+
+      - name: Verify new JAR works
+        if: steps.compare.outputs.needs_update == 'true'
+        run: |
+          if [ -f "data/plantuml.jar" ]; then
+            echo "PlantUML JAR downloaded successfully"
+            java -jar data/plantuml.jar -version || echo "Version check completed"
+          else
+            echo "Failed to download PlantUML JAR"
+            exit 1
+          fi
+
+      - name: Create Pull Request
+        if: steps.compare.outputs.needs_update == 'true'
+        uses: peter-evans/create-pull-request@v5
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: |
+            Update PlantUML to version ${{ steps.latest-version.outputs.version }}
+
+            - Updated PLANTUML_JAR_VERSION to ${{ steps.latest-version.outputs.version }}
+            - Downloaded new PlantUML JAR file
+            - Incremented gem version
+          title: "Update PlantUML to version ${{ steps.latest-version.outputs.version }}"
+          body: |
+            This PR updates PlantUML to the latest version ${{ steps.latest-version.outputs.version }}.
+
+            Changes:
+            - Updated `PLANTUML_JAR_VERSION` in `lib/metanorma/plugin/plantuml/version.rb`
+            - Downloaded new PlantUML JAR to `data/plantuml.jar`
+            - Incremented gem version
+
+            This update was created automatically by the PlantUML version sync workflow.
+          branch: update-plantuml-${{ steps.latest-version.outputs.version }}
+          base: main
+          labels: |
+            enhancement
+            automated

data/.github/workflows/rake.yml

@@ -0,0 +1,15 @@
+# Auto-generated by Cimas: Do not edit it manually!
+# See https://github.com/metanorma/cimas
+name: rake
+
+on:
+  push:
+    branches: [ master, main ]
+    tags: [ v* ]
+  pull_request:
+
+jobs:
+  rake:
+    uses: metanorma/ci/.github/workflows/plantuml-rake.yml@main
+    secrets:
+      pat_token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}

data/.github/workflows/release.yml

@@ -0,0 +1,25 @@
+# Auto-generated by Cimas: Do not edit it manually!
+# See https://github.com/metanorma/cimas
+name: release
+
+on:
+  workflow_dispatch:
+    inputs:
+      next_version:
+        description: |
+          Next release version. Possible values: x.y.z, major, minor, patch (or pre|rc|etc).
+          Also, you can pass 'skip' to skip 'git tag' and do 'gem push' for the current version
+        required: true
+        default: 'skip'
+  repository_dispatch:
+    types: [ do-release ]
+
+jobs:
+  release:
+    uses: metanorma/ci/.github/workflows/rubygems-release.yml@main
+    with:
+      next_version: ${{ github.event.inputs.next_version }}
+    secrets:
+      rubygems-api-key: ${{ secrets.METANORMA_CI_RUBYGEMS_API_KEY }}
+      pat_token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}
+

data/Gemfile

@@ -0,0 +1,28 @@
+Encoding.default_external = Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8
+
+source "https://rubygems.org"
+git_source(:github) { |repo| "https://github.com/#{repo}" }
+
+gemspec
+
+begin
+  eval_gemfile("Gemfile.devel")
+rescue StandardError
+  nil
+end
+
+gem "byebug"
+gem "debug"
+gem "metanorma"
+gem "metanorma-standoc", github: "metanorma/metanorma-standoc", branch: "feature/extract-plantuml"
+gem "rake"
+gem "rspec"
+gem "rspec-html-matchers"
+gem "rubocop"
+gem "rubocop-performance"
+gem "simplecov"
+gem "timecop"
+gem "vcr"
+gem "webmock"
+gem "canon"

data/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2025, Ribose
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -0,0 +1,374 @@
+= Metanorma PlantUML plugin (metanorma-plugin-plantuml)
+
+image:https://github.com/metanorma/metanorma-plugin-plantuml/workflows/rake/badge.svg["Build Status", link="https://github.com/metanorma/metanorma-plugin-plantuml/actions?workflow=rake"]
+
+== Purpose
+
+This is a Metanorma plugin to enable usage of PlantUML diagrams in Metanorma
+documents.
+
+It provides a Ruby API that wraps a bundled PlantUML JAR file.
+
+== PlantUML
+
+PlantUML is a popular tool that allows users to create rich diagrams from plain
+text descriptions, including:
+
+* UML diagrams
+
+** Sequence diagram
+** Usecase diagram
+** Class diagram
+** Object diagram
+** Activity diagram
+** Component diagram
+** Deployment diagram
+** State diagram
+** Timing diagram
+
+It also supports the following non-UML diagrams:
+
+* JSON Data
+* YAML Data
+* Network diagram (nwdiag)
+* Wireframe graphical interface
+* Archimate diagram
+* Specification and Description Language (SDL)
+* Ditaa diagram
+* Gantt diagram
+* MindMap diagram
+* Work Breakdown Structure diagram
+* Mathematic with AsciiMath or JLaTeXMath notation
+* Entity Relationship diagram
+
+For more details, please refer to the
+https://www.plantuml.net[official PlantUML website].
+
+The official PlantUML Language Reference Guide is available at:
+
+* https://pdf.plantuml.net/PlantUML_Language_Reference_Guide_en.pdf
+
+
+== Installation
+
+[source,console]
+----
+$ gem install metanorma-plugin-plantuml
+----
+
+
+== Usage
+
+This plugin enables PlantUML diagram generation in Metanorma documents through
+the `plantuml` block directive.
+
+
+=== Basic syntax
+
+[source,asciidoc]
+----
+[plantuml]
+....
+@startuml
+Alice -> Bob: Hello
+Bob -> Alice: Hi there
+@enduml
+....
+----
+
+=== Supported diagram types
+
+PlantUML 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
+`@startgantt` / `@endgantt`:: Gantt charts
+`@startsalt` / `@endsalt`:: Wireframe diagrams
+`@startdot` / `@enddot`:: Graphviz DOT diagrams
+`@startditaa` / `@endditaa`:: ASCII art diagrams
+`@startjson` / `@endjson`:: JSON data visualization
+`@startyaml` / `@endyaml`:: YAML data visualization
+
+.Sequence diagram
+[example]
+====
+[source,asciidoc]
+----
+[plantuml]
+....
+@startuml sequence-example
+participant Alice
+participant Bob
+
+Alice -> Bob: Authentication Request
+Bob --> Alice: Authentication Response
+@enduml
+....
+----
+====
+
+.Mind map
+[example]
+====
+[source,asciidoc]
+----
+[plantuml]
+....
+@startmindmap
+* Metanorma
+** Standards
+*** ISO
+*** IEC
+*** ITU
+** Formats
+*** PDF
+*** HTML
+*** Word
+@endmindmap
+....
+----
+====
+
+=== Format options
+
+==== Single format specification
+
+Specify the output format using the `format` attribute:
+
+[source,asciidoc]
+----
+[plantuml,format=svg]
+....
+@startuml
+Alice -> Bob: Hello
+@enduml
+....
+----
+
+Supported formats:
+
+`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:
+
+[source,asciidoc]
+----
+[plantuml,formats="png,svg,pdf"]
+....
+@startuml
+Alice -> Bob: Hello
+@enduml
+....
+----
+
+==== Document-level format configuration
+
+Set the default format for all PlantUML diagrams in your document:
+
+[source,asciidoc]
+----
+:plantuml-image-format: svg
+
+[plantuml]
+....
+@startuml
+Alice -> Bob: Hello
+@enduml
+....
+----
+
+=== Image attributes
+
+Standard AsciiDoc image attributes are supported:
+
+[source,asciidoc]
+----
+[plantuml,id=my-diagram,title="My Sequence Diagram",width=600,height=400]
+....
+@startuml
+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:
+
+[source,asciidoc]
+----
+[plantuml]
+....
+@startuml my-custom-name
+Alice -> Bob: Hello
+@enduml
+....
+----
+
+This generates `my-custom-name.png` (or specified format) instead of an
+auto-generated filename.
+
+
+=== Configuration options
+
+==== Disable PlantUML processing
+
+Disable PlantUML processing document-wide:
+
+[source,asciidoc]
+----
+:plantuml-disabled:
+
+[plantuml]
+....
+@startuml
+Alice -> Bob: Hello
+@enduml
+....
+----
+
+When disabled, PlantUML blocks are rendered as code listings instead of diagrams.
+
+==== Environment variable
+
+Disable PlantUML processing via environment variable:
+
+[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.
+
+== Development
+
+=== Architecture
+
+This plugin follows a layered architecture that separates concerns between
+Metanorma integration and PlantUML execution:
+
+[source]
+----
+Metanorma Document
+      ↓
+BlockProcessor ← (processes [plantuml] blocks)
+      ↓
+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.
+
+`Backend`:: Handles Metanorma-specific logic including document paths, PlantUML
+source validation, filename extraction, and attribute mapping.
+
+`Wrapper`:: Provides low-level PlantUML JAR execution with cross-platform Java
+handling, file I/O operations, and format conversion.
+
+
+=== Version mapping
+
+This gem uses semantic versioning independent of the PlantUML JAR version.
+
+The following table shows the relationship between gem versions and bundled
+PlantUML versions:
+
+[cols="1,1,1", options="header"]
+|===
+| Gem version | PlantUML version | Notes
+
+| 1.0.0       | 1.2025.4        | Latest release with updated architecture
+|===
+
+This approach allows the gem to follow standard semantic versioning practices
+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:
+
+. Check the latest PlantUML release at
+https://github.com/plantuml/plantuml/releases
+
+. Update the version in `lib/metanorma/plugin/plantuml/version.rb`:
++
+[source,ruby]
+----
+PLANTUML_JAR_VERSION = "1.2025.4"  # Update to latest version
+VERSION = "1.0.1"                  # Increment patch version
+----
+
+. Clean the old JAR file:
++
+[source,console]
+----
+$ bundle exec rake clean_jar
+----
+
+. Download the new JAR file:
++
+[source,console]
+----
+$ bundle exec rake download_jar
+----
+
+. Run tests to ensure everything works:
++
+[source,console]
+----
+$ bundle exec rake spec
+----
+
+. 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.
+
+=== Available rake 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
+----
+
+== Documentation
+
+Please refer to https://www.metanorma.org.
+
+== Copyright and license
+
+Copyright Ribose.
+
+PlantUML is open-sourced under multiple licenses. For more details, please refer
+to the PlantUML repository at https://github.com/plantuml/plantuml.
+
+For the purposes of this plugin, it is distributed under the MIT license.
+
+Licensed under the 2-Clause BSD License.

data/Rakefile

@@ -0,0 +1,38 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require_relative "lib/metanorma/plugin/plantuml/version"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: [
+  "data/plantuml.jar",
+  :spec,
+]
+
+def uri_open(url)
+  require 'open-uri'
+  URI.parse(url).open
+end
+
+file "data/plantuml.jar" do |file|
+  ver = Metanorma::Plugin::Plantuml::PLANTUML_JAR_VERSION
+  url = "https://github.com/plantuml/plantuml/releases/download/v#{ver}/plantuml-#{ver}.jar"
+  puts "Downloading PlantUML JAR... #{url}"
+
+  FileUtils.mkdir_p(File.dirname(file.name))
+
+  File.open(file.name, "wb") do |f|
+    f.write uri_open(url).read
+  end
+
+  puts "PlantUML JAR downloaded to #{file.name}"
+end
+
+desc "Download PlantUML JAR file"
+task :download_jar => "data/plantuml.jar"
+
+desc "Clean downloaded JAR file"
+task :clean_jar do
+  FileUtils.rm_f("data/plantuml.jar")
+  puts "Removed data/plantuml.jar"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "metanorma/plugin/plantuml"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here