document Undocumented plantuml features

VladimirAlexiev commented 4 years ago

There are many plantuml undocumented features and settings captured in the forum (Q&A) Many of them also don't appear with java -jar plantuml.jar -language.

The list comes mostly from #7095, #7140 thanks to @Anthony-Gaudino, and was complemented, categorized, and converted to a task list by @VladimirAlexiev.

NOTE: Ashley's PlantUML Doc by Ashley Engelund is a good example how the total documentation can be structured. It's created with reStructuredText (rST) and sphinx. In particular This Site describes some advanced doc generation: "javasphinx: I’ve written some Java code to extract information directly from PlantUML code. The extracted info is then used as input to my sphinx files. I also have some python code that creates some of the .puml files and initial rST code."

Preprocessor, Includes, Sectioning

preprocessing-v2

[ ] #6577 Ability to include blocks ("subsections") of code
[ ] #7838 !pragma http.proxyHost
[ ] #6289 %filename% and %filenameNoExtension%
[ ] #6199 %PLANTUML_VERSION%
[ ] #5968 %filedate%
[ ] #5769 %filename% and %dirpath% variables
[ ] #5171 Boolean not ! and parenthesis on !ifdef
[ ] #3868 Use tilde ~ to escape @startuml
[ ] #5483 @startuml filename for automatic extensions
[ ] #4467 @startuml with identifier for includes
[ ] #1466 @startuml{OPTIONS}
[ ] #4596 \startXXX instead of @startXXX
[ ] #5769 @startdef and @enddef
[ ] #1525, #5793 @pause @unpause
[ ] #1525 @pause @unpause @continue @append and /' ... '/ multiline comments
[ ] #4266 -config parameter
[ ] #2410 Multiple include paths
[ ] #7337 Tags to include individual pieces
[ ] #7337 remove / restore
[ ] wildcards in remove / hide / restore, eg remove *

Running and Output

command-line

[x] #4752 Output Braille diagrams (-tbraille)
[x] #5037 -pipemap parameter (HTML clickable maps): command-line#standard_input_output
[x] #3562 diagram code is embedded in PNG metadata (-metadata -checkmeta)
[x] #1601 -gui parameter accepts a path
[x] #3214 -eps:text parameter
[x] File naming when multiple diagrams are used per input (added to sources and link in command-line)

AsciiArt output with -ttxt or -tutxt

[ ] #4147 skinparam maxAsciiMessageLength

latex output with -tlatex through Tikz

[ ] #1798 latex-tikz-support anything more to document?
[ ] Latex "see result online" (eg https://www.writelatex.com/read/pgkkspzgzgpb) doesn't work because need to migrate to overleaf
[ ] #6495 skinparam tikzFont
[x] #3558 Latex link [[latex://]]

SVG output with tsvg:

[ ] #5453 skinparam pathHoverColor
[ ] #7334 skinparam svgDimensionStyle

Layout

plantuml/plantuml#840, advice PlantUML GraphViz Layout by Mark George at University of Otago

[ ] #4418, #3111, #4045 !pragma svek_trace
[ ] #1343 !pragma aspect
[ ] #1226 !pragma ratio
[ ] #977 skinparam nodesep
[ ] #977 skinparam ranksep
[ ] #1608 skinparam linetype ortho (but see plantuml/backlog#11) and skinparam linetype polyline
[ ] #4387 #5007 together to keep nodes next to each other
[ ] #3188 norank arrow option
[ ] #8365 hidden and norank
[ ] #4418, #1132, #3231, #3111, #3143 !pragma horizontalLineBetweenDifferentPackageAllowed
[ ] #1296 skinparam minClassWidth and skinparam sameClassWidth
[ ] #4637 skinparam minClassWidth on sequence diagram
[ ] #2538 layout_new_line for disconnected parts
[ ] #3118 skinparam padding
[ ] #5493 skinparam ParticipantPadding and skinparam BoxPadding

Text and Links

Creole, Link, ASCII Math, JLatexMath

[ ] #3104 Use \ for multiline stuff
[ ] #3055 Align text with \l and \r
[ ] #3601 Creole on class titles with as
[ ] issues/104 skinparam wrapWidth and skinparam wrapMessageWidth
[x] #3820 skinparam tabSize
[ ] #5254 <plain>...</plain> to remove default text style (eg skinparam classFontStyle)
[ ] #5574 tooltip over link

Images, Icons, Sprites, Shapes, Embellishments

[ ] #4080 Import images from jar/zip
[ ] #3790 DATA URI as embeded image
[ ] #7485 skinparam DiagonalCorner
[ ] #2899 skinparam activityShape
[ ] #4076, #4079 Sprites on stereotypes
[X] #8084 listsprites of stdlib: alphadoc sprite#stdlib and sprite#listing-sprites
[X] Emojis in creole syntax, see https://github.com/plantuml/plantuml/discussions/820

Color

[ ] #3770 Inline set of multiple colors in various diagrams (text;line;back;header)
[ ] #1487 ##[style]color of node borders: works for class and state diagrams
[ ] #5340 inline coloring of node borders
[ ] #7287 automatic color
[ ] #3648 Transparent color
[ ] #4906 Gradient color on activity diagram partition

Arrows

[ ] #3636 Arrows from/to class members
[ ] #3621 Component diagram consumer/provider arrows
[ ] make sure all arrow params are documented: dotted|dashed|plain|bold|hidden|norank|single|thickness|left|right|up|down, color
[ ] #3816 skinparam ArrowColor, stereotyped arrows, new syntax for inline arrow style (Setting multiple arrow skinparams in one line); (componentArrowColor is deprecated)
[ ] #4949 Inline setting for edge style and thickness
[ ] #4260 bold and plain arrow styles
[ ] #4181 bold, dashed, dotted

Make sure all arrow types are documented on one page:

[ ] arrows arrows-2 at https://github.com/anoff/blog/tree/master/static/assets/plantuml/diagrams
[ ] #1736 Multiple lollipop edge styles
[ ] #5261 crows foot edge
[ ] #2259 Class diagram --( and -0)- arrows
[ ] #310 Sequence diagram ?-> and ->? arrows

Mixed and Embedded Diagrams

[ ] #2335 allow_mixing vs mix_usecase mix_actor...
[ ] #375 Embed SVG in SVG diagram
[ ] #2427 Embed SALT UI diagrams in notes and other texts ("Flowchat")

Alternative Layoters

[ ] Eclipse Layout Kernel: elk: !pragma layout elk replace graphviz with a completely different layouter
[ ] #4436, #5336, smetana02 !pragma graphviz_dot jdot: replace graphviz with Java code
[x] vizjs -graphvizdot vizjs: replace graphviz with JavaScript code
[ ] http://beta.plantuml.net/noditaa/: replace ditaa with java code

Class Diagrams

[ ] #5835 Notes on class fields
[ ] #3054 details on how the "attributes" vs "methods" boxes are formed, and what happens when you add your own divider line
[ ] #3606 {field} and {method} to override recognition of "methods" by round parentheses
[ ] #2913 Hide private / protected / package class members
[x] #3448 Tree structure inside class
[ ] #3424 Class attribute stereotype
[ ] #2259 Class diagram circle (but see https://github.com/plantuml/plantuml/issues/841)
[ ] #2239 extends and implements can reference multiple nodes
[x] #3193 skinparam groupInheritance to merge inheritance arrows going to the same parent
[x] #1638 package style card

Component Diagrams

[ ] #11052 remove @unlinked components; component tags and hide/remove/restore $tag

Sequence Diagrams

teoz, sequence-diagram#anchors_and_duration, tag/teoz: new Teoz (vs old Puma) for sequence diagrams

[ ] #4247 hide unlinked participants
[ ] #7119 %autonumber%
[ ] #8511 autonumber inc
[ ] #2794 skinparam lifelineStrategy
[ ] #2503 Secondary group label in sequence diagram
[ ] #7264 skinparam belowForResponse
[ ] #1047 skinparam style strictuml: emits triangle rather than sharp arrow heads
[ ] #3482, #206 skinparam sequenceMessageAlign

Activity Diagrams

[ ] #5201 skinparam swimlaneWidth
[ ] #2681 Swimlane alias
[ ] #4470 Label of arrows of repeat loops (repeat while)
[ ] #6105 Activity diagram break
[ ] #301 Activity Beta if (...) is/equals (...) then
[ ] #265 Activity Beta kill
[ ] #3931 !pragma useVerticalIf on: draw if/elseif/else structure vertically
[ ] #1041, #13988, #12569, #13988 switch case ...
[ ] #1626 Activity diagram GOTO
[ ] #2792 skinparam activityArrowFontSize
[ ] #3166 skinparam activityArrowFontColor
[ ] #5346 Activity diagram joinspec
[ ] #2868 Activity diagram multiple halting states
[ ] #3505 Activity diagram end
[ ] #5826 backward on loops
[ ] #2398 Note on partition
[ ] #2793 Inline coloring of partition
[ ] #1290 skinparam conditionStyle: inside (hexagon: default), foo1 (big diamond), diamond (tiny diamond)
[ ] #6010 skinparam arrowMessageAlign center
[ ] #4411 skinparam colorArrowSeparationSpace: multiple parallel arrows in activity digrams
[ ] #3770 background color of alt/group

State Diagrams

[ ] #1159 State diagram <<choice>>, <<fork>>, <<join>>, <<end>>
[ ] #3672 State Diagram <<choice>>
[ ] #10077 colored connectors in state diagrams
[ ] #1159 Choice Pseudostate in State Diagrams
[ ] #1099 State diagram hide empty description
[ ] #4309 State diagram <<expansionInput>> and <<expansionOutput>>, <<inputPin>> and <<outputPin>>, <<entrypoint>> and <<exitpoint>>
[ ] #1812 State inline color

SDL and ER/IE Diagrams

[ ] #1232 SDL shapes (some undocumented)
[x] ie-diagram, pull/31 ER (IE) diagrams

SALT (UI) Diagrams

search?q=salt, tag/salt

[ ] #5849 Salt pseudo "sprite"
[ ] #5840 Salt titled groupbox
[ ] #1265, #5400 Salt tree table (table-tree)

Timing Diagrams

[ ] #5776 Timing diagram coloring

Gantt Charts

gantt-diagram

[ ] #5782 Arrow on Gantt Diagram
[ ] #5510 Gantt diagram dates

BPMN Diagrams

[ ] #5647 BPMN (@startbpm and @endbpm)

MindMap Diagrams

mindmap-diagram

WBS Diagrams

Work Breakdown Structures, Organizational Breakdown Structures (organigrams)

wbs-diagram

Graphviz Diagrams

[ ] #4210 When using Dot, PlantUML supports strict graph and digraph
[ ] #1206 Dot graph

Potherca commented 4 years ago

THIS.IS.AMAZING!

I'm fairly certain I won't have any time to contribute (sadly), but I just wanted to say this is awesome work!

bflorat commented 4 years ago

wildcards in remove / hide / restore ex : remove *
remove @unlinked (component diagram) https://forum.plantuml.net/11052/remove-unlinked-components

VladimirAlexiev commented 3 years ago

Added sec Your Help Needed with link to this list, the forum and slack: http://alphadoc.plantuml.com/doc/markdown/en/start#yll09vktqqw4kdu256uv. Can anyone make it more sexy and attention-drawing?

@bflorat thanks for these 2 bullets, I see they were added to the main list

Potherca commented 3 years ago

@VladimirAlexiev Regarding

Can anyone make it more sexy and attention-drawing?

Maybe we should ask @arnaudroques (or other maintainers?) to pin this issue so it appears at the top of the "Issues" page?

pakluba commented 3 years ago

PlantUML supports switch-case in the new Activity Diagram, but seems like it's not mentioned anywhere. It has some rendering glitches, so that's might be the case.

VladimirAlexiev commented 2 years ago

@pakluba added switch case ... in Activity. Also together in Layout

demeesterroel commented 2 years ago

@VladimirAlexiev I'd like to help document some features as requested in this ticket, and on https://plantuml-documentation.readthedocs.io/en/latest/this_site/from_forum.html?highlight=strictuml

Can you point me to some information on how to best contribute. Thanks .

The-Lum commented 2 years ago

Hello @demeesterroel,

I'd like to help document some features...

For that, you can read:

And here is the page with the same topics as this current GH page:

http://alphadoc.plantuml.com/doc/markdown/en/undocumented

And then contribute... Thanks a lot. Regards.

VladimirAlexiev commented 2 years ago

Hi @demeesterroel ! 1.Could you merge the above list to this one? If you can't edit the issue description , add it as a comment and I'll merge

I'd guess a decent percent of the items are already documented. If you stumble upon such, please mark them as done
alphadoc does not respond for me. Furthermore, doc pages (eg. https://plantuml.com/activity-diagram-legacy) don't show edit links. @arnaudroques , what's up?
- If Arnoud does not respond soon, please open a separate issue

jhoehle commented 1 year ago

Sequence Diagrams

[ ] &-notation to draw multiple arrows on the same line / time (Teoz only feature)

Mixed and embedded

[ ] #15011 {{ nested/sub diagrams }} e.g. within note (more general than just salt within activity diagram, above #2427)

Meanwhile documented (@VladimirAlexiev please check them above)

[x] # 310 (->?) # 1047 (strictuml) # 4247 (hide unlinked)

The-Lum commented 1 year ago

Hello @jhoehle, and all,

Thanks for the remarks.

For:

[ ] &-notation to draw multiple arrows on the same line / time (Teoz only feature)

We can add a point from Sequence page to Teoz page. :+1:

For:

[ ] #15011 {{ nested/sub diagrams }} e.g. within note (more general than just salt within activity diagram, above #2427)

I started this page:

Sub-diagram on Alpha-doc

To continue to improve the doc... Regards.

xeruf commented 1 year ago

I think the mentioned Salt items are documented now: https://plantuml.com/salt

BenceSzalai commented 1 year ago

Undocumented feature: using $tag to remove and hide elements. It is documented for Component diagrams. I've just added documentation for Class diagrams (based on plantuml/plantuml#1240, waiting for approval, I think).

Other diagrams supporting $tag in need of documentation update based on my tests:

use-case diagram
state diagram
deployment diagram
archimate diagram

Diagram types not supporting $tag:

sequence diagram
activity-diagram, both legacy & new Beta
object diagram
timing diagram
network diagram
wireframe diagram
gantt diagram
mindmap diagram
WBS diagram
JSON diagram
YAML diagram

Meanwhile #11052 can be ticked off the list, it is done:

plantuml / plantuml