Upgrade PlantUML version to 1.2023.10 (MarkBind#2311)

WillCWX · Jul 29, 2023 · ff46013 · ff46013
1 parent aeaa9f7
commit ff46013
Show file tree

Hide file tree

Showing 21 changed files with 31 additions and 10 deletions.
diff --git a/docs/_markbind/variables.md b/docs/_markbind/variables.md
@@ -15,6 +15,8 @@
 <variable name="node_dev_version_number">16.19.1</variable>
 <variable name="node_version"><tooltip content="MarkBind aims to support up to the last maintenance lts release as outlined [here](https://nodejs.org/en/about/releases/)">v{{ node_version_number }}</tooltip></variable>
 <variable name="node_dev_version"><tooltip content="MarkBind aims to support up to the last maintenance lts release as outlined [here](https://nodejs.org/en/about/releases/)">v{{ node_dev_version_number }}</tooltip></variable>
+<variable name="graphviz_version_number">2.38</variable>
+<variable name="graphviz_version"><tooltip content="Some versions are not recommended, as mentioned [here](https://plantuml.com/graphviz-dot#:~:text=Important%20note%20about%20version)">v{{ graphviz_version_number }}</tooltip></variable>
 <variable name="link_live_preview">[live preview](glossary.html#live-preview)</variable>
 
 <variable name="tooltip_root_directory"><tooltip content="The directory that contains all the project files. It is also the directory in which the `site.json` configuration file is located.">root directory</tooltip></variable>

diff --git a/docs/devGuide/development/settingUp.md b/docs/devGuide/development/settingUp.md
@@ -18,8 +18,8 @@ This page explains how to set up your development environment to start contribut
 1. **Node.js** ({{ node_dev_version }} or higher) with<br>
    **npm** v8 or higher
 
-1. **Java** 8 or later, and<br>
-   **Graphviz** v2.38 or later<br>
+1. **Java** 8 or higher, and<br>
+   **Graphviz** ({{ graphviz_version }} or higher, _installation is optional on Windows_) <br>
    %%(The above two are required for one of the third-party libraries used by MarkBind)%%
 
 1. **Python** 3 or later, and<br>
@@ -29,7 +29,7 @@ This page explains how to set up your development environment to start contribut
    * `node --version`
    * `npm --version`
    * `java --version`
-   * `dot -V` (for Graphviz)
+   * `dot -V` (for Graphviz - optional on Windows)
    * `python3 -V`
 
 <box type="tip" seamless>

diff --git a/docs/devGuide/development/workflow.md b/docs/devGuide/development/workflow.md
@@ -367,5 +367,23 @@ As the choice is highly dependent on context and details of the implementation,
 Find out more about the key external libraries used in MarkBind from the [project structure](../design/projectStructure.md) section. Also, the rationales behind most existing patches are documented in their respective files, read them (and their respective PRs/issues) for more context!
 </box>
 
+### Updating PlantUML
+
+PlantUML is a third-party library used by MarkBind to create UML diagrams. MarkBind runs the PlantUML JAR file found in `packages/core/src/plugins/default` when building the site to generate the diagrams.
+
+To update PlantUML to a newer version:
+
+1. Download the JAR file from [PlantUML's website](https://plantuml.com/download).
+1. Rename the file to `plantuml.jar` (if required), and replace the existing JAR file located in `packages/core/src/plugins/default`.
+1. Generate the image files for the `.puml` files listed in `docs/userGuide/diagrams`. 
+
+<box type="tip" seamless header="Here are the recommended steps to generate the image files:">
+
+1. Add a new `.md` file in `userGuide`, e.g. `plantuml.md`, containing `<puml>` tags of all diagrams to be generated. 
+1. Serve the documentation site using `markbind serve -d`.
+1. Access the corresponding HTML page with the generated diagrams, i.e. `/userGuide/plantuml.html`.
+1. Right-click on each image and save the image in `docs/userGuide/diagrams`.
+</box>
+
 {% from "njk/common.njk" import previous_next %}
 {{ previous_next('settingUp', 'writingComponents') }}
diff --git a/docs/images/annotateSampleObject.png b/docs/images/annotateSampleObject.png
diff --git a/docs/images/annotateSampleSequence.png b/docs/images/annotateSampleSequence.png
diff --git a/docs/userGuide/diagrams/activity.png b/docs/userGuide/diagrams/activity.png
diff --git a/docs/userGuide/diagrams/archimate.png b/docs/userGuide/diagrams/archimate.png
diff --git a/docs/userGuide/diagrams/class.png b/docs/userGuide/diagrams/class.png
diff --git a/docs/userGuide/diagrams/component.png b/docs/userGuide/diagrams/component.png
diff --git a/docs/userGuide/diagrams/ditaa.png b/docs/userGuide/diagrams/ditaa.png
diff --git a/docs/userGuide/diagrams/entityrelation.png b/docs/userGuide/diagrams/entityrelation.png
diff --git a/docs/userGuide/diagrams/gantt.png b/docs/userGuide/diagrams/gantt.png
diff --git a/docs/userGuide/diagrams/object.png b/docs/userGuide/diagrams/object.png
diff --git a/docs/userGuide/diagrams/sequence.png b/docs/userGuide/diagrams/sequence.png
diff --git a/docs/userGuide/diagrams/state.png b/docs/userGuide/diagrams/state.png
diff --git a/docs/userGuide/diagrams/state.puml b/docs/userGuide/diagrams/state.puml
@@ -16,5 +16,5 @@ state State3 {
 State3 --> State3 : Failed
 State3 --> [*] : Succeeded / Save Result
 State3 --> [*] : Aborted
- 
+
 @enduml
diff --git a/docs/userGuide/diagrams/usecase.png b/docs/userGuide/diagrams/usecase.png
diff --git a/docs/userGuide/diagrams/usecase.puml b/docs/userGuide/diagrams/usecase.puml
@@ -3,7 +3,7 @@ left to right direction
 skinparam packageStyle rectangle
 actor customer
 actor clerk
-rectangle checkout {
+rectangle shop {
   customer -- (checkout)
   (checkout) .> (payment) : include
   (help) .> (checkout) : extends

diff --git a/docs/userGuide/syntax/annotations.md b/docs/userGuide/syntax/annotations.md
@@ -92,7 +92,7 @@ Here we showcase some use cases of the Annotate feature.
 <variable name="highlightStyle">html</variable>
 <variable name="code">
 
-<annotate src="https://markbind.org/userGuide/diagrams/object.png" height="500" alt="Sample Image">
+<annotate src="../../images/annotateSampleObject.png" height="500" alt="Sample Image">
   <a-point x="6%" y="50%" content="You can use a triangle and a solid line (not to be confused with an arrow) to indicate class inheritance." label="1" header="Class inheritance" legend="both"/>
   <a-point x="25.5%" y="50%" content="UML uses a solid diamond symbol to denote composition." label="2" header="Composition" color="red"  legend="both"/>
   <a-point x="45%" y="50%" content="UML uses a hollow diamond to indicate an aggregation."  label="3" header="Aggregation" color="blue" legend="both"/>
@@ -107,7 +107,7 @@ Here we showcase some use cases of the Annotate feature.
 <variable name="highlightStyle">html</variable>
 <variable name="code">
 
-<annotate src="https://markbind.org/userGuide/diagrams/sequence.png" height="500" alt="Sample Image">
+<annotate src="../../images/annotateSampleSequence.png" height="500" alt="Sample Image">
   <a-point x="35%" y="18.5%" content="Operation is invoked" header="Operation"  opacity="0.2" size="30"/>
   <a-point x="65%" y="50%" content="This is the period during which the method is being executed" header="Activation Bar" opacity="0.3" size="50" color="yellow"/>
   <a-point x="14%" y="85%" content="Return control and possibly some return value" header="Return Value" opacity="0.2" size="30" color="blue"/>

diff --git a/docs/userGuide/syntax/diagrams.md b/docs/userGuide/syntax/diagrams.md
@@ -6,9 +6,10 @@ You can use the [PlantUML](http://plantuml.com/) syntax to add diagrams.
 
 **The following additional dependencies are involved when using this feature** *(**locally** and in your <tooltip content="E.g: Building & deploying the site via GitHub Actions">**CI/CD environment**</tooltip>)*
 
-* Java 8 or later (required - to run the PlantUML JAR executable)
-* [Graphviz](https://www.graphviz.org/download/) v2.38 or later (optional - you don't need this if you only need [sequence diagrams](https://plantuml.com/sequence-diagram) and [activity (beta) diagrams](https://plantuml.com/activity-diagram-beta))
-  * A warning will be displayed if you don't have Graphviz installed. To disable this warning, you may modify your `site.json` like <trigger for="pop:prerequisite-disable" placement="bottom" trigger="click">this</trigger>.
+* Java 8 or higher (required - to run the PlantUML JAR executable)
+* [Graphviz](https://www.graphviz.org/download/) {{ graphviz_version }} or higher (optional - you don't need this if you are on Windows, or only need [sequence diagrams](https://plantuml.com/sequence-diagram) and [activity (beta) diagrams](https://plantuml.com/activity-diagram-beta))
+  * A warning will be displayed if you don't have Graphviz installed (ignore this warning if you are on Windows). To disable this warning, you may modify your `site.json` like <trigger for="pop:prerequisite-disable" placement="bottom" trigger="click">this</trigger>.
+  * An alternative layout engine, [Smetana](https://plantuml.com/smetana02), is integrated into PlantUML and can be used to generate diagrams without a Graphviz installation. However, as the Smetana engine is a work in progress, certain layouts may not render correctly. 
 
 <modal header="Disabling PlantUML's prerequisite check in `site.json`" id="pop:prerequisite-disable" backdrop>
   <include src="{{ baseUrl }}/userGuide/siteJsonFile.md#plantuml-check"/>

diff --git a/packages/core/src/plugins/default/plantuml.jar b/packages/core/src/plugins/default/plantuml.jar