Metanorma: Aequitate Verum

Author's documentation

Diagrams

General

Diagrams are useful to visualize the structure of a system or processes.

Metanorma supports the LutaML and PlantUML diagramming tools, for creation of different kinds of diagrams directly in a Metanorma document.

LutaML

Please refer to documentation for the LutaML UML plugin.

PlantUML

Prerequisites

If you are using Metanorma installed through one of the supported installation mechanisms (e.g. Homebrew, Snap, Chocolatey, Docker), this feature is by default available.

If you are using the development install (e.g. via Ruby gems), you need to have PlantUML installed in order to use this feature. Specifically, you must have an accessible executable called plantuml in your terminal path.

Please refer to the official PlantUML site for installation instructions.

The recommended manner to install PlantUML on macOS is through Homebrew, and on Windows via Chocolatey.

Adding a diagram

To add one or more diagrams in a Metanorma document:

  1. Begin a new literal block (delimited by …​.) and use the attribute [plantuml].

    The compiler now knows that PlantUML syntax follows.

  2. Begin the diagram with @startuml.

  3. Enter your diagram using the PlantUML notation.

  4. End the diagram with @enduml.

Example:

[plantuml]
....
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
@enduml
....

The [plantuml] block is automatically processed by PlantUML to transform its text input into a target image that is embedded in place of the block.

By default, the PNG format is used. To change the output format for PlantUML to SVG, use the document attribute :plantuml-image-format: svg [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.0.9]

The images are stored in a _plantuml_images directory relative to the current path [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.0.9].

Note
 Releases prior to 3.0.9 had images stored in either a plantuml directory, or in the directory specified by the :imagesdir: document attribute.

  • Visit the PlantUML website to learn more about PlantUML and what kinds of diagrams it supports.