From: Petter Reinholdtsen Date: Mon, 25 Mar 2019 08:31:06 +0000 (+0100) Subject: New post about PlantUML. X-Git-Url: http://pere.pagekite.me/gitweb/homepage.git/commitdiff_plain/33ec56ec6fedd516d63c03c51c3bdbb14bf1cbd5?hp=90579008be6ee314ae65de711ebd8b8024509904 New post about PlantUML. --- diff --git a/blog/data/2019-03-25-noark5-plantuml.txt b/blog/data/2019-03-25-noark5-plantuml.txt new file mode 100644 index 0000000000..d6946b022b --- /dev/null +++ b/blog/data/2019-03-25-noark5-plantuml.txt @@ -0,0 +1,146 @@ +Title: PlantUML for text based UML diagram modelling - nice free software +Tags: english, standard, nuug, noark5, nice free software +Date: 2019-03-25 09:35 + +

As part of my involvement with the +Nikita +Noark 5 core project, I have been proposing improvements to the +API specification created by The +National Archives of Norway and helped migrating the text from a +version control system unfriendly binary format (docx) to Markdown in +git. Combined with the migration to a public git repository (on +github), this has made it possible for anyone to suggest improvement +to the text.

+ +

The specification is filled with UML diagrams. I believe the +original diagrams were modelled using Sparx Systems Enterprise +Architect, and exported as EMF files for import into docx. This +approach make it very hard to track changes using a version control +system. To improve the situation I have been looking for a good text +based UML format with associated command line free software tools on +Linux and Windows, to allow anyone to send in corrections to the UML +diagrams in the specification. The tool must be text based to work +with git, and command line to be able to run it automatically to +generate the diagram images. Finally, it must be free software to +allow anyone, even those that can not accept a non-free software +license, to contribute.

+ +

I did not know much about free software UML modelling tools when I +started. I have used dia and inkscape for simple modelling in the +past, but neither are available on Windows, as far as I could tell. I +came across a nice +list +of text mode uml tools, and tested out a few of the tools listed +there. The PlantUML tool seemed +most promising. After verifying that the packages +is available in +Debian and found its +Java source under a GPL license on github, I set out to test if it +could represent the diagrams we needed, ie the ones currently in +the +Noark 5 Tjenestegrensesnitt specification. I am happy to report +that it could represent them, even thought it have a few warts here +and there.

+ +

After a few days of modelling I completed the task this weekend. A +temporary link to the complete set of diagrams (original and from +PlantUML) is available in +the +github issue discussing the need for a text based UML format, but +please note I lack a sensible tool to convert EMF files to PNGs, so +the "original" rendering is not as good as the original was in the +publised PDF.

+ +

Here is an example UML diagram, showing the core classes for +keeping metadata about archived documents:

+ +
+@startuml
+skinparam classAttributeIconSize 0
+
+!include media/uml-class-arkivskaper.iuml
+!include media/uml-class-arkiv.iuml
+!include media/uml-class-klassifikasjonssystem.iuml
+!include media/uml-class-klasse.iuml
+!include media/uml-class-arkivdel.iuml
+!include media/uml-class-mappe.iuml
+!include media/uml-class-merknad.iuml
+!include media/uml-class-registrering.iuml
+!include media/uml-class-basisregistrering.iuml
+!include media/uml-class-dokumentbeskrivelse.iuml
+!include media/uml-class-dokumentobjekt.iuml
+!include media/uml-class-konvertering.iuml
+!include media/uml-datatype-elektronisksignatur.iuml
+
+Arkivstruktur.Arkivskaper "+arkivskaper 1..*" <-o "+arkiv 0..*" Arkivstruktur.Arkiv
+Arkivstruktur.Arkiv o--> "+underarkiv 0..*" Arkivstruktur.Arkiv
+Arkivstruktur.Arkiv "+arkiv 1" o--> "+arkivdel 0..*" Arkivstruktur.Arkivdel
+Arkivstruktur.Klassifikasjonssystem "+klassifikasjonssystem [0..1]" <--o "+arkivdel 1..*" Arkivstruktur.Arkivdel
+Arkivstruktur.Klassifikasjonssystem "+klassifikasjonssystem [0..1]" o--> "+klasse 0..*" Arkivstruktur.Klasse
+Arkivstruktur.Arkivdel "+arkivdel 0..1" o--> "+mappe 0..*" Arkivstruktur.Mappe
+Arkivstruktur.Arkivdel "+arkivdel 0..1" o--> "+registrering 0..*" Arkivstruktur.Registrering
+Arkivstruktur.Klasse "+klasse 0..1" o--> "+mappe 0..*" Arkivstruktur.Mappe
+Arkivstruktur.Klasse "+klasse 0..1" o--> "+registrering 0..*" Arkivstruktur.Registrering
+Arkivstruktur.Mappe --> "+undermappe 0..*" Arkivstruktur.Mappe
+Arkivstruktur.Mappe "+mappe 0..1" o--> "+registrering 0..*" Arkivstruktur.Registrering
+Arkivstruktur.Merknad "+merknad 0..*" <--* Arkivstruktur.Mappe
+Arkivstruktur.Merknad "+merknad 0..*" <--* Arkivstruktur.Dokumentbeskrivelse
+Arkivstruktur.Basisregistrering -|> Arkivstruktur.Registrering
+Arkivstruktur.Merknad "+merknad 0..*" <--* Arkivstruktur.Basisregistrering
+Arkivstruktur.Registrering "+registrering 1..*" o--> "+dokumentbeskrivelse 0..*" Arkivstruktur.Dokumentbeskrivelse
+Arkivstruktur.Dokumentbeskrivelse "+dokumentbeskrivelse 1" o-> "+dokumentobjekt 0..*" Arkivstruktur.Dokumentobjekt
+Arkivstruktur.Dokumentobjekt *-> "+konvertering 0..*" Arkivstruktur.Konvertering
+Arkivstruktur.ElektroniskSignatur -[hidden]-> Arkivstruktur.Dokumentobjekt
+@enduml
+
+ +

The format is quite +compact, with little redundant information. The text expresses +entities and relations, and there is little layout related fluff. One +can reuse content by using include files, allowing for consistent +naming across several diagrams. The include files can be standalone +PlantUML too. Here is the content of +media/uml-class-arkivskaper.iuml:

+ +
+@startuml
+class Arkivstruktur.Arkivskaper  {
+  +arkivskaperID : string
+  +arkivskaperNavn : string
+  +beskrivelse : string [0..1]
+}
+@enduml
+
+ +

This is what the complete diagram for the PlantUML notation above +look like:

+ +

+ +

A cool feature of PlantUML is that the generated PNG files include +the entire original source diagram as text. The source (with include +statements expanded) can be extracted using for example +exiftool. Another cool feature is that parts of the entities +can be hidden after inclusion. This allow to use include files with +all attributes listed, even for UML diagrams that should not list any +attributes.

+ +

The diagram also show some of the warts. Some times the layout +engine place text labels on top of each other, and some times it place +the class boxes too close to each other, not leaving room for the +labels on the relationship arrows. The former can be worked around by +placing extra newlines in the labes (ie "\n"). I did not do it here +to be able to demonstrate the issue. I have not found a good way +around the latter, so I normally try to reduce the problem by changing +from vertical to horizontal links to improve the layout.

+ +

All in all, I am quite happy with PlantUML, and very impressed with +how quickly its lead developer responds to questions. So far I got an +answer to my questions in a few hours when I send an email. I +definitely recommend looking at PlantUML if you need to make UML +diagrams. Note, PlantUML can draw a lot more than class relations. +Check out the documention for a complete list. :)

+ +

As usual, if you use Bitcoin and want to show your support of my +activities, please send Bitcoin donations to my address +15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b.