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

1.1. Observations on Standard Library

Note

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.

Tip

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

#

Observation

OBV_DEFINE_DEPRECATED

Macros use define and definelong which are deprecated per below

OBV_DRY

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

OBV_CLOSE_COUPLING

Macros are defined in the icon file for each icon

the parameters, and order of parameters, is fixed

OBV_CONSISTENCY

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

OBV_NO_SCALE

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.

OBV_NO_TEXTATTRIB

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

OBV_3PARAMS_MIN

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.

OBV_ALL_PUML

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.

Note

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

#

Requirement

REQ_CONSISTENCY

Consistency of macros, files, sizes

REQ_ONLY_CARE

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)

REQ_DECOUPLE

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

REQ_CATEGORY

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)

REQ_CONTRIBUTE

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

US_HIGHLIGHT

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

US_THEME

To use, or create, a theme,

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

US_ICONSET

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

so I have all the icons I need for my diagrams