1. Standard Library - What We Have And What We Want

1.1. Observations on Standard Library


This page is superseded by an RFC: https://github.com/plantuml/rfc-for-standard-plantuml-stdlib to solicit user input, but I’ll leave it here for reference/context.


The Observations, Requirements, and User Stories here allow us to create a new PlantUML Stdlib to empower the user per todoref

Observations on Standard Library




Macros use define and definelong which are deprecated per below


DRY (Don’t Repeat Yourself). The macros are repeated

within a file -repeat the macro to add each new parameter

across files - the macro content is largely the same - but the macro name changes to specify the icon to use


Macros are defined in the icon file for each icon

the parameters, and order of parameters, is fixed


icon sizes

some have multiple sizes

for those that have one size, it is not standard/common with the other stdlib libraries

icon files

some break up the icons into categories sub-directories, some don’t some have an `all.puml` file that includes all sprite content per category, some don’target


There’s no way to scale the icons from the macros (the !define statements) except for Material.

Plantuml does support scaling per https://forum.plantuml.net/4267/scaling-of-the-sprites-or-images.

Support for scaling stereotypes is available since March 2019.


There’s no way to change the size, colour etc… of the text description, label, technology fields


At least 3 parameters are required and are rendered in the diagams

`!define Batch(e\_alias, e\_label, e\_techn)`.

In other words, the macros force a user to specify things they may not care about e.g. to specify color in this macro, the user needs to specify the preceeding parameters also

!define WHATEVER(_alias, _label, _shape, _color) ENTITY(_shape,_color,whatever,_label, _alias,WHATEVER)

So if we wanted a colored or scaled icon only (with no label or technology), we have to implement it ourselves.


Some libaries have an `all.puml` that includes all icons and their macros for a given category/subset of icons.

This allows including all icons by including one file - rather than an include per icon.


The following software principles should apply

  • Loose Coupling, High Cohesion (Consistency)

  • DRY (Don’t Repeat Yourself)

  • Open/Closed Principle (OCP) “open for extension” but “closed to modification” i.e. not have to change old macros to implement new behavior. New Macros are defined instead, that don’t break existing user code (SOLID).

1.2. Macro Definitions

Macros define the following

  1. The superset of parameters

    1. sprite

    2. color

    3. scale (material library only)

    4. shape (Type 1 (e_type), 4 (_shape))

    5. technology

    6. description

    7. label

  2. Fixed

    1. Text Size

    2. Text Order

1.3. What a User Wants In A Standard Library

What a User Wants In A Standard Library




Consistency of macros, files, sizes


Specify the things they care about

Default values specified when the icons are built, but the ones the user cares about can be overridden by the user in their diagram file (at runtime)


Decoupling of the sprite (the image), from the decoration (text, shape, color, scale etc…)

To benefit from other people’s work e.g. if a new parameter or decoration/theme is added they like, they want to use it in their diagrams

Future Proofing with backwards compatibility: new functionality can be added to the sprite library, but the user’s existing code will still work with this new library


Grouping of icons into categories.

A user can include a file for that category that incldues all the icons (and not have to include a file for every icon)


To be able to easily share / contribute

their icon set

their theme or style or layout

1.4. User Stories

User Stories


As a User, I want X, so I am empowered to do Y


To highlight certain parts of a diagram

so I can show the relevant or important parts in the context of an overall diagram

e.g. a diagram may have 10 icons/components, but I want to highlight the ones being discussed or changed in my current system


To use, or create, a theme,

so I can create diagams consistent with my other (personal, organisation, company) documentation.


To use, or create and contribute, an icon set easily

so I have all the icons I need for my diagrams