Problem Statement

Software designs are commonly produced in text editors such as Microsoft Word that is supplemented through the inclusion of diagrams produced in drawing tools such as Visio or a UML modeling tool.

Tools Used

R

R is a programming language used primarliy for data analysis. It provides several excellent tools for producing data plots.

knitr

knitr is an R package that allows you to embed and evaluate R and other programing languages inside a markdown document.

knitr processes R markdown files using the R programming language to generate a markdown file. That markdown file is then run through Pandoc to generate a final report on one of many formats such as HTML, PDF, or Word.

knitr evolved mainly to support Reproducible Research - the notion that all of the steps [of a data aalysis and the code used to produce that analysis should be clearly documented so that the analysis should be reporoducible by other people.

PlantUML

In software engineering, UML is sometimes used to graphically document a software design. Most UML tools are graphical drawing tools of one kind or another. They typically store data in a proprietary data format. There has been efforts to produce XML-based formats that would allow UML models to be ported from one tool to another, but these standards have been ineffective to date. This means that the UML model may not be readible or reproducible at some future data. The graphical nature of common UML models and the complexity of theier stored data files makes it difficult to version control the modesl in a meaninful way; In a way that a human can easiliy so what changed from one version of a model to the next.

In addition, developers often spend a substantial portion of thier time, not improving the design, but making thier UML diagrams look pretty

PlantUML takes the approach of specifying the UML model in plain ASCII text. The text is then parsed and diagrams are automatically produced from the graphics utiliies provided by the Graphviz package.

Proposed Approach

This document shows an example of how to use the tools describe above to produce human readable software design documents in plain ASCII text. This approach allows for the use of text-based version control systems that are highly capable and well understood by the software development community. The proposed approach embeds the PlantUML source code for UML diagrams within the document. The knitr package of R is then used to “weave” a markdown file that is then converted to one of the many publication quality output file formats supported by Pandoc.

Demonstration.

For the puposes of this demonstration I am echoing all of the embedded source code into the generated file. For a design document to be published you may wish to hide this code using knitr’s echo=FALSE chunk option.

First we create an R variable that contains the PlantUML source code.

diagname="umlstate"
teststate="
@startuml
[*]-->STATE1
@enduml
"

Then we translate the PlantUML source code into a diagram.

# Write the PlantUML source code to a file.
write(teststate, paste0(diagname, ".uml"))
# Make a system call to generate a .png image from the PlantUML source code.
system2("java", paste0(" -jar plantuml.jar ", paste0(diagname, ".uml")))

The diagram has been generated as a local image file1. We can now include the diagram in the document.

simple state machine

Soure code

The souce code for this paper can be found here

  1. I would like to figure out how avoid generating the intermediate .uml and .png files.↩