Specification, Documentation, and Community

Question

Hello,

First, I want to express my appreciation for the incredible tool that PlantUML is and how much I enjoy using it. However, I’ve encountered some challenges related to the documentation, which often seems outdated, incomplete, or ambiguous in certain areas. Additionally, I noticed that the Discord server appears inactive which is unfortunate but understandable.

I’m currently developing a very basic Node.js application using TypeScript aimed at generating and managing class diagrams programmatically. If successful, I plan to extend this to other diagram types as well. My goal is to create a tool that normalizes diagram generation and styling programmatically, supports type-checking and IntelliSense, and generally improves the experience of working with PlantUML.

Despite spending considerable time reading the available documentation and searching online, I’m struggling to find a consistent and explicit specification for PlantUML’s data types, structures, and command specifics. The best resource I’ve found so far is the plantuml -language command output, but I’m unsure if this output is up to date. For instance, why is diamond categorized as a shape while circle is a keyword? Is this due to an implementation detail in Java, or is there a more specific reason? If this is an implementation detail do you have any advice / resources on how to best understand this moving forward? 

Moreover, the -language output doesn’t provide sufficient information on the expected arguments for various commands. For example, does the new Style (CSS-like) syntax accept all CSS-like units (px, %, em, etc.)? And given the deprecation of skinparams, is it worthwhile to fully implement all of them and their arguments as listed in this documentation since Style is still missing features?

Thank you for your time, and I look forward to any insights you can provide.

Best regards,

NG

Answer 1

I've done similar things a few times, even have a site online that allows anyone to create these with a few clicks, for a few diagram types (with appropriate links back to this site, and it's not charging anyone anything).

This plantuml website, the awesome Hitchhikers Guide, and this forum are your tools, really. ChatGPT probably knows a lot by now too. Finally, the tool is in JAVA, so you can just read the code :)

Personally, I find manually coming up with the shape, styles and such and then just feeding whatever data structure I want in via Excel Formulas or a JSON macro is more than enough to automate the documentation for most of my needs.

Without wanting to discourage this endeavor, what's the use case? Programmatically constructing text from Typescript using reflection or something? If it's something that can already be represented in JSON (most Typescript things) then you might consider just using a Macro and then you can just swap out your data instead of writing more code :)