blog/data/2019-03-25-noark5-plantuml.txt

   1 Title: PlantUML for text based UML diagram modelling - nice free software
   2 Tags: english, standard, nuug, noark5, nice free software
   3 Date: 2019-03-25 09:35
   4
   5 <p>As part of my involvement with the
   6 <a href="https://gitlab.com/OsloMet-ABI/nikita-noark5-core/">Nikita
   7 Noark 5 core project</a>, I have been proposing improvements to the
   8 API specification created by <a href="https://www.arkivverket.no/">The
   9 National Archives of Norway</a> and helped migrating the text from a
  10 version control system unfriendly binary format (docx) to Markdown in
  11 git.  Combined with the migration to a public git repository (on
  12 github), this has made it possible for anyone to suggest improvement
  13 to the text.</p>
  14
  15 <p>The specification is filled with UML diagrams.  I believe the
  16 original diagrams were modelled using Sparx Systems Enterprise
  17 Architect, and exported as EMF files for import into docx.  This
  18 approach make it very hard to track changes using a version control
  19 system.  To improve the situation I have been looking for a good text
  20 based UML format with associated command line free software tools on
  21 Linux and Windows, to allow anyone to send in corrections to the UML
  22 diagrams in the specification.  The tool must be text based to work
  23 with git, and command line to be able to run it automatically to
  24 generate the diagram images.  Finally, it must be free software to
  25 allow anyone, even those that can not accept a non-free software
  26 license, to contribute.</p>
  27
  28 <p>I did not know much about free software UML modelling tools when I
  29 started.  I have used dia and inkscape for simple modelling in the
  30 past, but neither are available on Windows, as far as I could tell.  I
  31 came across a nice
  32 <a href="https://modeling-languages.com/text-uml-tools-complete-list/">list
  33 of text mode uml tools</a>, and tested out a few of the tools listed
  34 there.  <a href="http://plantuml.com/">The PlantUML tool</a> seemed
  35 most promising.  After verifying that the packages
  36 <a href="https://tracker.debian.org/pkg/plantuml">is available in
  37 Debian</a> and found <a href="https://github.com/plantuml/plantuml">its
  38 Java source</a> under a GPL license on github, I set out to test if it
  39 could represent the diagrams we needed, ie the ones currently in
  40 <a href="https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/">the
  41 Noark 5 Tjenestegrensesnitt specification</a>.  I am happy to report
  42 that it could represent them, even thought it have a few warts here
  43 and there.</p>
  44
  45 <p>After a few days of modelling I completed the task this weekend.  A
  46 temporary link to the complete set of diagrams (original and from
  47 PlantUML) is available in
  48 <a href="https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/issues/76">the
  49 github issue discussing the need for a text based UML format</a>, but
  50 please note I lack a sensible tool to convert EMF files to PNGs, so
  51 the "original" rendering is not as good as the original was in the
  52 publised PDF.</p>
  53
  54 <p>Here is an example UML diagram, showing the core classes for
  55 keeping metadata about archived documents:</p>
  56
  57 <pre>
  58 @startuml
  59 skinparam classAttributeIconSize 0
  60
  61 !include media/uml-class-arkivskaper.iuml
  62 !include media/uml-class-arkiv.iuml
  63 !include media/uml-class-klassifikasjonssystem.iuml
  64 !include media/uml-class-klasse.iuml
  65 !include media/uml-class-arkivdel.iuml
  66 !include media/uml-class-mappe.iuml
  67 !include media/uml-class-merknad.iuml
  68 !include media/uml-class-registrering.iuml
  69 !include media/uml-class-basisregistrering.iuml
  70 !include media/uml-class-dokumentbeskrivelse.iuml
  71 !include media/uml-class-dokumentobjekt.iuml
  72 !include media/uml-class-konvertering.iuml
  73 !include media/uml-datatype-elektronisksignatur.iuml
  74
  75 Arkivstruktur.Arkivskaper "+arkivskaper 1..*" <-o "+arkiv 0..*" Arkivstruktur.Arkiv
  76 Arkivstruktur.Arkiv o--> "+underarkiv 0..*" Arkivstruktur.Arkiv
  77 Arkivstruktur.Arkiv "+arkiv 1" o--> "+arkivdel 0..*" Arkivstruktur.Arkivdel
  78 Arkivstruktur.Klassifikasjonssystem "+klassifikasjonssystem [0..1]" <--o "+arkivdel 1..*" Arkivstruktur.Arkivdel
  79 Arkivstruktur.Klassifikasjonssystem "+klassifikasjonssystem [0..1]" o--> "+klasse 0..*" Arkivstruktur.Klasse
  80 Arkivstruktur.Arkivdel "+arkivdel 0..1" o--> "+mappe 0..*" Arkivstruktur.Mappe
  81 Arkivstruktur.Arkivdel "+arkivdel 0..1" o--> "+registrering 0..*" Arkivstruktur.Registrering
  82 Arkivstruktur.Klasse "+klasse 0..1" o--> "+mappe 0..*" Arkivstruktur.Mappe
  83 Arkivstruktur.Klasse "+klasse 0..1" o--> "+registrering 0..*" Arkivstruktur.Registrering
  84 Arkivstruktur.Mappe --> "+undermappe 0..*" Arkivstruktur.Mappe
  85 Arkivstruktur.Mappe "+mappe 0..1" o--> "+registrering 0..*" Arkivstruktur.Registrering
  86 Arkivstruktur.Merknad "+merknad 0..*" <--* Arkivstruktur.Mappe
  87 Arkivstruktur.Merknad "+merknad 0..*" <--* Arkivstruktur.Dokumentbeskrivelse
  88 Arkivstruktur.Basisregistrering -|> Arkivstruktur.Registrering
  89 Arkivstruktur.Merknad "+merknad 0..*" <--* Arkivstruktur.Basisregistrering
  90 Arkivstruktur.Registrering "+registrering 1..*" o--> "+dokumentbeskrivelse 0..*" Arkivstruktur.Dokumentbeskrivelse
  91 Arkivstruktur.Dokumentbeskrivelse "+dokumentbeskrivelse 1" o-> "+dokumentobjekt 0..*" Arkivstruktur.Dokumentobjekt
  92 Arkivstruktur.Dokumentobjekt *-> "+konvertering 0..*" Arkivstruktur.Konvertering
  93 Arkivstruktur.ElektroniskSignatur -[hidden]-> Arkivstruktur.Dokumentobjekt
  94 @enduml
  95 </pre>
  96
  97 <p><a href="http://plantuml.com/class-diagram">The format</a> is quite
  98 compact, with little redundant information.  The text expresses
  99 entities and relations, and there is little layout related fluff.  One
 100 can reuse content by using include files, allowing for consistent
 101 naming across several diagrams.  The include files can be standalone
 102 PlantUML too.  Here is the content of
 103 <tt>media/uml-class-arkivskaper.iuml<tt>:</p>
 104
 105 <pre>
 106 @startuml
 107 class Arkivstruktur.Arkivskaper <Arkivenhet> {
 108   +arkivskaperID : string
 109   +arkivskaperNavn : string
 110   +beskrivelse : string [0..1]
 111 }
 112 @enduml
 113 </pre>
 114
 115 <p>This is what the complete diagram for the PlantUML notation above
 116 look like:</p>
 117
 118 <p><img width="80%" src="http://people.skolelinux.org/pere/blog/images/2019-03-25-noark5-plantuml-diagrameksempel.png"></p>
 119
 120 <p>A cool feature of PlantUML is that the generated PNG files include
 121 the entire original source diagram as text.  The source (with include
 122 statements expanded) can be extracted using for example
 123 <tt>exiftool</tt>.  Another cool feature is that parts of the entities
 124 can be hidden after inclusion.  This allow to use include files with
 125 all attributes listed, even for UML diagrams that should not list any
 126 attributes.</p>
 127
 128 <p>The diagram also show some of the warts.  Some times the layout
 129 engine place text labels on top of each other, and some times it place
 130 the class boxes too close to each other, not leaving room for the
 131 labels on the relationship arrows.  The former can be worked around by
 132 placing extra newlines in the labes (ie "\n").  I did not do it here
 133 to be able to demonstrate the issue.  I have not found a good way
 134 around the latter, so I normally try to reduce the problem by changing
 135 from vertical to horizontal links to improve the layout.</p>
 136
 137 <p>All in all, I am quite happy with PlantUML, and very impressed with
 138 how quickly its lead developer responds to questions.  So far I got an
 139 answer to my questions in a few hours when I send an email.  I
 140 definitely recommend looking at PlantUML if you need to make UML
 141 diagrams.  Note, PlantUML can draw a lot more than class relations.
 142 Check out the documention for a complete list. :)</p>
 143
 144 <p>As usual, if you use Bitcoin and want to show your support of my
 145 activities, please send Bitcoin donations to my address
 146 <b><a href="bitcoin:15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b">15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b</a></b>.</p>