X-Git-Url: http://pere.pagekite.me/gitweb/homepage.git/blobdiff_plain/33ec56ec6fedd516d63c03c51c3bdbb14bf1cbd5..b201eaf504c4a063f44f3eea9a6bf111d9065222:/blog/index.rss diff --git a/blog/index.rss b/blog/index.rss index 69423e0e19..4d8878cb13 100644 --- a/blog/index.rss +++ b/blog/index.rss @@ -6,6 +6,156 @@ http://people.skolelinux.org/pere/blog/ + + PlantUML for text based UML diagram modelling - nice free software + http://people.skolelinux.org/pere/blog/PlantUML_for_text_based_UML_diagram_modelling___nice_free_software.html + http://people.skolelinux.org/pere/blog/PlantUML_for_text_based_UML_diagram_modelling___nice_free_software.html + Mon, 25 Mar 2019 09:35:00 +0100 + <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> + + + Release 0.3 of free software archive API system Nikita announced http://people.skolelinux.org/pere/blog/Release_0_3_of_free_software_archive_API_system_Nikita_announced.html @@ -928,60 +1078,6 @@ remaining piece in the puzzle is Open Broadcast Encoder, but it depend on quite a lot of patched libraries which would have to be included in Debian first.</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> - - - - - Learn to program with Minetest on Debian - http://people.skolelinux.org/pere/blog/Learn_to_program_with_Minetest_on_Debian.html - http://people.skolelinux.org/pere/blog/Learn_to_program_with_Minetest_on_Debian.html - Sat, 15 Dec 2018 15:30:00 +0100 - <p>A fun way to learn how to program -<a href="https://www.python.org/">Python</a> is to follow the -instructions in the book -"<a href="https://nostarch.com/programwithminecraft">Learn to program -with Minecraft</a>", which introduces programming in Python to people -who like to play with Minecraft. The book uses a Python library to -talk to a TCP/IP socket with an API accepting build instructions and -providing information about the current players in a Minecraft world. -The TCP/IP API was first created for the Minecraft implementation for -Raspberry Pi, and has since been ported to some server versions of -Minecraft. The book contain recipes for those using Windows, MacOSX -and Raspian. But a little known fact is that you can follow the same -recipes using the free software construction game -<a href="https://minetest.net/">Minetest</a>.</p> - -<p>There is <a href="https://github.com/sprintingkiwi/pycraft_mod">a -Minetest module implementing the same API</a>, making it possible to -use the Python programs coded to talk to Minecraft with Minetest too. -I -<a href="https://ftp-master.debian.org/new/minetest-mod-pycraft_0.20%2Bgit20180331.0376a0a%2Bdfsg-1.html">uploaded -this module</a> to Debian two weeks ago, and as soon as it clears the -FTP masters NEW queue, learning to program Python with Minetest on -Debian will be a simple 'apt install' away. The Debian package is -maintained as part of the Debian Games team, and -<a href="https://salsa.debian.org/games-team/unfinished/minetest-mod-pycraft">the -packaging rules</a> are currently located under 'unfinished' on -Salsa.</p> - -<p>You will most likely need to install several of the Minetest -modules in Debian for the examples included with the library to work -well, as there are several blocks used by the example scripts that are -provided via modules in Minetest. Without the required blocks, a -simple stone block is used instead. My initial testing with a analog -clock did not get gold arms as instructed in the python library, but -instead used stone arms.</p> - -<p>I tried to find a way to add the API to the desktop version of -Minecraft, but were unable to find any working recipes. The -<a href="https://www.epiphanydigest.com/tag/minecraft-python-api/">recipes</a> -I <a href="https://github.com/kbsriram/mcpiapi">found</a> are only -working with a standalone Minecraft server setup. Are there any -options to use with the normal desktop version?</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>