Should we reduce legend text width with line, border style symbols (instead of text)?

[kirchsth]

Atm we have a lot of different line, border and shape styles and the legend text can be very wide like below

(@Potherca:) Should we uses symbols that the legend size is reduced, like below?

The disadvantage could be that the symbols are not clear for everybody.

I found no useful color alternatives for "transparent", "no text color", "no back(ground) color" and "no line color" therefore this would remain unchanged atm. In most of the cases the e.g. "no text color" can be avoided at all (as soon a concrete color is defined).

Second question: should I remove (border) "transparent" from the legend at all?

Thank you and best regards Helmut

PS.: source of the samples

```plantuml @startuml ' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally !if %variable_exists("RELATIVE_INCLUDE") !include ./../C4_Container.puml !else !include https://raw.githubusercontent.com/kirchsth/C4-PlantUML/extended/C4_Container.puml !endif ''''' THIS SECTION ACTIVATES THE NEW SYMBOLS (deactivate it and you get the orig. design back) !global $LEGEND_SHADOW_TEXT = "(<$shadowSprite>) " !global $LEGEND_NO_SHADOW_TEXT = "(no <$shadowSprite>) " !global $LEGEND_ROUNDED_BOX = "(<$roundCornerSprite>) " !global $LEGEND_EIGHT_SIDED = "(<$cutCornerSprite>) " ' http://unicode-search.net/unicode-namesearch.pl !global $LEGEND_DOTTED_LINE = "() " !global $LEGEND_DASHED_LINE = "() " !global $LEGEND_BOLD_LINE = "() " !global $LEGEND_DASHED_BOUNDARY = "boundary () " !global $LEGEND_DASHED_TRANSPARENT_BOUNDARY = "boundary (, transparent) " ''''' END OF SECTION SHOW_PERSON_OUTLINE() ' Tags support no spaces in the name (based on the underlining stereotypes, which don't support spaces anymore). ' If spaces are requested in the legend, legend text with space has to be defined AddElementTag("backendContainer", $fontColor=$ELEMENT_FONT_COLOR, $bgColor="#335DA5", $shape=EightSidedShape(), $shadowing="true") AddRelTag("async", $textColor=$ARROW_COLOR, $lineColor=$ARROW_COLOR, $lineStyle=DashedLine()) AddRelTag("sync/async", $textColor=$ARROW_COLOR, $lineColor=$ARROW_COLOR, $lineStyle=DottedLine()) UpdateSystemBoundaryStyle() UpdateElementStyle("external_system", $EXTERNAL_SYSTEM_BG_COLOR, $ELEMENT_FONT_COLOR, $EXTERNAL_SYSTEM_BORDER_COLOR, $shape=RoundedBoxShape()) sprite $roundCornerSprite [16x16/16] { 0000000000000000 0000000007BEFFF0 0000000AFA631000 000005FC20000000 00007F7000000000 0005F30000000000 002F700000000000 00AB000000000000 02F2000000000000 07A0000000000000 0B60000000000000 0E30000000000000 0F10000000000000 0F00000000000000 0F00000000000000 0000000000000000 } sprite $cutCornerSprite [16x16/16] { 0000000000000000 0000000004EFFFF0 000000004E400000 00000004E4000000 0000004E40000000 000004E400000000 00004E4000000000 0004E40000000000 004E400000000000 04E4000000000000 0E40000000000000 0F00000000000000 0F00000000000000 0F00000000000000 0F00000000000000 0000000000000000 } sprite $shadowSprite [16x16/16] { 0000000000000000 00000000000F0000 00000000000FA000 00000000000FA800 00000000000FA800 00000000000FA800 00000000000FA800 00000000000FA800 00000000000FA800 00000000000FA800 00000000000FA800 00000000000FA800 0FFFFFFFFFFFA800 00AAAAAAAAAAA400 0008888888888800 0000000000000000 } title Container diagram for Internet Banking System Person(customer, Customer, "A customer of the bank, with personal bank accounts") System_Boundary(c1, "Internet Banking") { Container(web_app, "Web Application", "Java, Spring MVC", "Delivers the static content and the Internet banking SPA") Container(spa, "Single-Page App", "JavaScript, Angular", "Provides all the Internet banking functionality to cutomers via their web browser") Container(mobile_app, "Mobile App", "C#, Xamarin", "Provides a limited subset of the Internet banking functionality to customers via their mobile device") ContainerDb(database, "Database", "SQL Database", "Stores user registration information, hashed auth credentials, access logs, etc.") Container(backend_api, "API Application", "Java, Docker Container", "Provides Internet banking functionality via API", $tags="backendContainer") } System_Ext(email_system, "E-Mail System", "The internal Microsoft Exchange system") System_Ext(banking_system, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.") Rel(customer, web_app, "Uses", "HTTPS") Rel(customer, spa, "Uses", "HTTPS") Rel(customer, mobile_app, "Uses") Rel_Neighbor(web_app, spa, "Delivers") Rel(spa, backend_api, "Uses", "async, JSON/HTTPS", $tags="async") Rel(mobile_app, backend_api, "Uses", "async, JSON/HTTPS", $tags="async") Rel_Back_Neighbor(database, backend_api, "Reads from and writes to", "sync, JDBC") Rel_Back(customer, email_system, "Sends e-mails to") Rel_Back(email_system, backend_api, "Sends e-mails using", "sync, SMTP") Rel_Neighbor(backend_api, banking_system, "Uses", "sync/async, XML/HTTPS", $tags="sync/async") SHOW_LEGEND() footer drawn with PlantUML v. %version() and C4-PlantUML v. C4Version() @enduml ```

[Potherca]

Usually I am not a big fan of replacing information with symbols. It might be clear to the author of the diagram but most likely not to other people.

Before I can really comment, I would need to better understand why it is an issue that the legend can become rather wide...

Looking only at the legend:

If the transparent is removed, things could also be made less wide by using a smaller font for the additional information:

The shortest it could be is this:

If the user is willing to gain a shorter legend by losing some meaning, that would be easy enough to achieve.

[kirchsth]

I like the idea with the smaller size.

I could make following changes:

1. The user can define the legend text without the additional information via a new $label=... parameter of the Add...Tag()/Update..Style() calls (as an alternative to $legendText).

And if $label is defined then it will be combined with the (calculated) additional information. This has the advantage that no (calculated) additional information has to be added to $legendText anymore.

E.g. AddElementTag("backendContainer", ... , $legendText = "backend container (shadowed) (eight sided)" ) and AddElementTag("backendContainer", ... , $label = "backend container" ) produce the same output.

2. add to SHOW_LEGEND() and SHOW_FLOATING_LEGEND() a $showStyle(?) parameter with the options "none", "normal", "small", "symbol"(?) The $showStyle(?) parameter requires a tag definition with $label (and if $label is defined then the default is small)

source

```plantuml @startuml skinparam LegendBorderColor transparent skinparam LegendBackgroundColor transparent skinparam LegendFontColor #FFFFFF skinparam shadowing<> false skinparam rectangle<> { backgroundcolor #00000000 bordercolor #00000000 } sprite $roundCornerSprite [16x16/16] { 0000000000000000 0000000007BEFFF0 0000000AFA631000 000005FC20000000 00007F7000000000 0005F30000000000 002F700000000000 00AB000000000000 02F2000000000000 07A0000000000000 0B60000000000000 0E30000000000000 0F10000000000000 0F00000000000000 0F00000000000000 0000000000000000 } sprite $cutCornerSprite [16x16/16] { 0000000000000000 00004EFFFFE40000 0004E400004E4000 004E40000004E400 04E4000000004E40 0E400000000004E0 0F000000000000F0 0F000000000000F0 0F000000000000F0 0E400000000004E0 04E4000000004E40 004E40000004E400 0004E400004E4000 00004EFFFFE40000 0000000000000000 } sprite $shadowSprite [16x16/16] { 0000000000000000 00000000000F0000 00000000000FA000 00000000000FA800 00000000000FA840 00000000000FA840 00000000000FA840 00000000000FA840 00000000000FA840 00000000000FA840 00000000000FA840 0FFFFFFFFFFFA840 00AAAAAAAAAAA840 0008888888888840 0000444444444440 0000000000000000 } legend right <#00000000,#00000000>|**Legend** | | | |<#335DA5> backend container (eight sided, shadow) | | | |<#335DA5> backend container (eight sided, shadow) | | | |<#335DA5> backend container (<$cutCornerSprite>, <$shadowSprite>) | | | |<#335DA5> backend container | | | endlegend @enduml ```

3. remove "transparent" (which is basically only a specific color like white and white is not displayed too) from boundary that we avoid a legend like

What do you think? And do you have a better name for showStyle?

Thank you and best regards Helmut

[Potherca]

1. The user can define the legend text via a new $label=... parameter

Sounds good.

2. add to SHOW_LEGEND() and SHOW_FLOATING_LEGEND() a $showStyle(?) parameter

Also good.

3. remove "transparent" from boundary

Also good.

do you have a better name for showStyle?

Naming a thing is always a bit tricky.

What does the parameter do or represents to a user? :thinking:

It doesn't really have to do with "style" as much as information representation. It gives the user an option to change how secondary information is display in the legend. $legendSecondaryInformationDisplayMethod is a bit verbose but it also doesn't fell "right".

For the user the information has meaning. That meaning is not "secondary" but is part of how they can identify items of a specific type.

$legendTypeDisplay is better but not there yet. Currently, I do not have a better suggestion yet.

Looking at the values "none", "normal", "small", "symbol" I think "symbol" might be "pictogram"? Also not sure yet.

[Potherca]

Regarding

do you have a better name for showStyle?

and

$legendTypeDisplay is better but not there yet.

Currently, I am oscilating between "shapeDescription" and "legendVerbosity" or something like that.

[kirchsth]

• I wouldn't use verbosity because normal and small displays the same information. We could call it "(legend)Layout" or something like this.

• I don't like the current no color implementation too;

  1. text is long and not 100% clear
  2. the used colors but I have no better idea atm

PS.: I'm not sure if I implement the pictograms at all (only none, normal and small)

• without the pictogram I can implement it via the font size (0..none) and I'm finished
• and your argument that a pictograms is not so clear is correct
• Atm I have no preference, and therefore I think this will be the last of my 2.5.0 issues ;-)

[Potherca]

I think "legendLayout" is a good description. Lets go with that.

Skipping pictograms sounds like a good plan. Only having "none", "normal" and "small" is good enough.

As to "no-color", I have no clear solution. I guess an unsatisfactory solution is still better than no solution. :shrug:

[Potherca]

@kirchsth Do you want this to be part of v2.5 or should we bump it to v2.6?

[kirchsth]

please wait