<link>http://people.skolelinux.org/pere/blog/</link>
+ <item>
+ <title>PlantUML for text based UML diagram modelling - nice free software</title>
+ <link>http://people.skolelinux.org/pere/blog/PlantUML_for_text_based_UML_diagram_modelling___nice_free_software.html</link>
+ <guid isPermaLink="true">http://people.skolelinux.org/pere/blog/PlantUML_for_text_based_UML_diagram_modelling___nice_free_software.html</guid>
+ <pubDate>Mon, 25 Mar 2019 09:35:00 +0100</pubDate>
+ <description><p>As part of my involvement with the
+<a href="https://gitlab.com/OsloMet-ABI/nikita-noark5-core/">Nikita
+Noark 5 core project</a>, I have been proposing improvements to the
+API specification created by <a href="https://www.arkivverket.no/">The
+National Archives of Norway</a> 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.</p>
+
+<p>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.</p>
+
+<p>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
+<a href="https://modeling-languages.com/text-uml-tools-complete-list/">list
+of text mode uml tools</a>, and tested out a few of the tools listed
+there. <a href="http://plantuml.com/">The PlantUML tool</a> seemed
+most promising. After verifying that the packages
+<a href="https://tracker.debian.org/pkg/plantuml">is available in
+Debian</a> and found <a href="https://github.com/plantuml/plantuml">its
+Java source</a> under a GPL license on github, I set out to test if it
+could represent the diagrams we needed, ie the ones currently in
+<a href="https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/">the
+Noark 5 Tjenestegrensesnitt specification</a>. I am happy to report
+that it could represent them, even thought it have a few warts here
+and there.</p>
+
+<p>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
+<a href="https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/issues/76">the
+github issue discussing the need for a text based UML format</a>, 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.</p>
+
+<p>Here is an example UML diagram, showing the core classes for
+keeping metadata about archived documents:</p>
+
+<pre>
+@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
+</pre>
+
+<p><a href="http://plantuml.com/class-diagram">The format</a> 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
+<tt>media/uml-class-arkivskaper.iuml<tt>:</p>
+
+<pre>
+@startuml
+class Arkivstruktur.Arkivskaper <Arkivenhet> {
+ +arkivskaperID : string
+ +arkivskaperNavn : string
+ +beskrivelse : string [0..1]
+}
+@enduml
+</pre>
+
+<p>This is what the complete diagram for the PlantUML notation above
+look like:</p>
+
+<p><img width="80%" src="http://people.skolelinux.org/pere/blog/images/2019-03-25-noark5-plantuml-diagrameksempel.png"></p>
+
+<p>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
+<tt>exiftool</tt>. 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.</p>
+
+<p>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.</p>
+
+<p>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. :)</p>
+
+<p>As usual, if you use Bitcoin and want to show your support of my
+activities, please send Bitcoin donations to my address
+<b><a href="bitcoin:15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b">15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b</a></b>.</p>
+</description>
+ </item>
+
<item>
<title>Release 0.3 of free software archive API system Nikita announced</title>
<link>http://people.skolelinux.org/pere/blog/Release_0_3_of_free_software_archive_API_system_Nikita_announced.html</link>
projects / homepage.git / blobdiff