Integration into main plantuml.jar file

[arnaudroques]

First, many thanks for your work!
Those themes are really nice and greatly improve the default rendering of PlantUML which is known to be very old-fashioned :-)

We are thinking about integrating your work into our own repository.
In practice, this means that we would create a themes folder in https://github.com/plantuml/plantuml where we would copy all puml-theme-xyz.puml files from https://github.com/bschwarz/puml-themes/tree/master/themes

More important, we would also introduce a new dedicated directive !theme. Somehow, this !theme directive would be a synonym for !include, but less verbose. For example !theme cyborg would simple include puml-theme-cyborg.puml from the inner themes folder. Usage of themes would be even easier this way.

Integrating those themes inside plantuml.jar (like we have done for the standard library) will allow people which are running PlantUML on servers that have no direct access to Internet (which is frequent in many enterprises) to use your themes.

Of course, we will credit you for the themes in our license, since we don't want to take credit from other people works.

Would that be ok for you ? Does it sound as a good idea ?

Thanks,

[bschwarz]

Thank you for all your work on plantuml, it's great!

I am fine with integrating into plantuml, in fact that is probably better. I think some of the themes might need some tweaking still, which I can help you out with, or if you want to handle that, either way.

I like the !theme idea. The easier for the user to use it, the better. Would there be a command line option as well? For example, instead of -config <config-file>, could use -theme cyborg.

Also, it would be cool to build in some introspection, if possible. You do this already for many things in plantuml (i.e. -language). Some directive or command line flag that will print out the theme (either in skinparam format or style format). This would help users create their own themes based off of existing themes. It is a little selfish of me too, since I have been working on a theme designer for plantuml, which would help that. Of course, this isn't a big priority, but an idea.

Let me know how I can help.

Cheers

[arnaudroques]

I am fine with integrating into plantuml, in fact that is probably better. I think some of the themes might need some tweaking still, which I can help you out with, or if you want to handle that, either way.

I'm not sur that we will be able to handle themes, so we let it to the hands of the community (that is you! :-)
We've just release a first beta of PlantUML with your work. You can do pull request to https://github.com/plantuml/plantuml/tree/master/themes

I like the !theme idea. The easier for the user to use it, the better.

Done!

Would there be a command line option as well? For example, instead of -config <config-file>, could use -theme cyborg.

Very good idea!
It is next on our TODO list, and will be implemented quickly.

Also, it would be cool to build in some introspection, if possible. You do this already for many things in plantuml (i.e. -language). Some directive or command line flag that will print out the theme (either in skinparam format or style format). This would help users create their own themes based off of existing themes. It is a little selfish of me too, since I have been working on a theme designer for plantuml, which would help that. Of course, this isn't a big priority, but an idea.

Well, that's also a good idea. More difficult to implement, but we are starting to think about it :-)

Let me know how I can help.

Well, if you accept to manage https://github.com/plantuml/plantuml/tree/master/themes this would be really great.

Another point, note that somehow we are deprecating skinparam and moving to style syntax.
(even if skinparam will always be supported for ascending compatibility).
So it would be nice if you could migrate all themes to style (instead of skinparam).
I know that some features must be missing in style syntax, so you could report those miss so that we fix them.

Another possible help: if you have any ideas of builtin functions we could provide to facilitate themes creation (for example, function to darker or lighter a color, to reverse it, to turn it to gray...) please do suggest.
We will implement them for you.

Regards,

[bschwarz]

Well, if you accept to manage https://github.com/plantuml/plantuml/tree/master/themes this would be really great.

Yes, I can manage this, no problem

Another point, note that somehow we are deprecating skinparam and moving to style syntax.
(even if skinparam will always be supported for ascending compatibility).
So it would be nice if you could migrate all themes to style (instead of skinparam).
I know that some features must be missing in style syntax, so you could report those miss so that we fix them.

Yeah, when I originally did these themes, I wanted to use the style syntax, but I wasn't sure when it would become official, so I kept with the skinparam syntax. I can try to convert to style syntax.

Another possible help: if you have any ideas of builtin functions we could provide to facilitate themes creation (for example, function to darker or lighter a color, to reverse it, to turn it to gray...) please do suggest.
We will implement them for you.

I'm glad you asked :)

There are a few functions/variables that would help out a lot. I was meaning to create a feature request for these, but didn't get to it.

I am not sure if Java has a package/library to handle these conversions already. If not, then we can base off of an existing implementation (I have used this node pkg in the past, and I like their api).

Flag to indicate plantuml support for style

First, related to the above style syntax, it would be nice to have a function or probably variable set which indicates that the style syntax is supported in the plantuml verion. So, in the theme files, I can support both skinparam and style (eventually we can phase out skinparam). So, it might look like this inside each theme file:

!if %variable_exists("PLANTUML_STYLE_EXISTS")
'
'  Use style configuration
'
!else
'
' Use skinparam configuration
'
!endif

Doesn't have to be this exactly, but some mechanism so that the theme file can support skinparam and style

Shading and tinting

As you mentioned, a shading (darker) and tinting (lighter) function would help a lot. Many of the themes have soft gradients, to give an impression of elevation. I had to manually covert theses gradient colors (I used this web site to do it). This works, but it is very tedious and error prone. So, something like:

%darken(color, level)
%lighten(color, level)
where:
    _color_ is the base color
    _level_ is how much darker/lighter it should be

Light/Dark Detection

Have a function(s) to determine if a color is light or dark. Something like:

%is_dark()
%is_light()

The reason this will be useful is the determination of a color to use. One example, if the background color is dark, then we can set the text color as light, and vice versa.

Text color

I believe some text color (text on sequence diagrams and class diagrams -- the text along the arrowed lines ), is automatically set, and can not be set via skinparam (perhaps style has this??). It would be nice to have some mechanism to set this as a default. The reason for this is because many web pages now support dark/light modes, so in that case you will want the text color set to something that looks good on dark and light backgrounds (if diagram is transparent). See this issue (last few comments) for some background on this.

Lesser priority

I think having a function to reverse and one to turn into grayscale would be good too, but these would be lower priority.

[arnaudroques]

I am not sure if Java has a package/library to handle these conversions already. If not, then we can base off of an existing implementation (I have used this node pkg in the past, and I like their api).

Thanks for the link.
We have started to copy their API in last beta version. We are just using integer instead of float.
For example:

@startuml
title
Example
lighten50=%lighten("012345", 50)
lighten50=%lighten("#012345", 50)
color10=%lighten("red", 10)
color10=%darken("red", 10)
color50=%lighten("red", 50)
color50=%darken("red", 50)
red is_dark=%is_dark("red")
red is_light=%is_light("red")
white is_dark=%is_dark("white")
white is_light=%is_light("white")
endtitle
alice->bob
@enduml

Is this what you were expecting ?
Tell us if other functions are missing.

Flag to indicate plantuml support for style

First, related to the above style syntax, it would be nice to have a function or probably variable set which indicates that the style syntax is supported in the plantuml verion. So, in the theme files, I can support both skinparam and style (eventually we can phase out skinparam).
Doesn't have to be this exactly, but some mechanism so that the theme file can support skinparam and style

That's a very good idea.
So with this last beta, there is a new %feature() function:

@startuml
title
Value for style: %feature("style")
Value for theme: %feature("theme")
Value for non-existing: %feature("some future feature")
endtitle
alice->bob
@enduml

Any other strings than style and theme will return 0.
In the future, we could change those values and add new features, so that themes/library could test which features are available on current running version.

This won't help you right now, because this %feature() function is not implemented on older versions.
So you can use the following workaround:

!if %function_exists("%is_light")
' this is 1.2020.6, at least
' use style
!else
' for older PlantUML, let's use skinparam
' use skinparam
!endif

Text color

I believe some text color (text on sequence diagrams and class diagrams -- the text along the arrowed lines ), is automatically set, and can not be set via skinparam (perhaps style has this??). It would be nice to have some mechanism to set this as a default. The reason for this is because many web pages now support dark/light modes, so in that case you will want the text color set to something that looks good on dark and light backgrounds (if diagram is transparent). See this issue (last few comments) for some background on this.

So we have just introduced a new syntax, where you provide two colors: one for light background, one for dark background.
This is quite experimental and working only for Font color.

@startuml
<style>
document {
  BackGroundColor Navy
}
root {
  FontColor #?black:white
}
</style>
title
my title
endtitle
class foo1
foo2 <|-- foo1
@enduml

This is not finished and not working in all case, but you've got the idea.
Is this what you where expecting ? (Of course, you can choose other colors than black and white)

PS: the -theme flag is also implemented in last beta.

[bschwarz]

Thanks for the link.
We have started to copy their API in last beta version. We are just using integer instead of float.
For example:

@startuml
title
Example
lighten50=%lighten("012345", 50)
lighten50=%lighten("#012345", 50)
color10=%lighten("red", 10)
color10=%darken("red", 10)
color50=%lighten("red", 50)
color50=%darken("red", 50)
red is_dark=%is_dark("red")
red is_light=%is_light("red")
white is_dark=%is_dark("white")
white is_light=%is_light("white")
endtitle
alice->bob
@enduml
Is this what you were expecting ?
Tell us if other functions are missing.

That's perfect, thank you. This will condense the themes files quite a bit.

That's a very good idea.
So with this last beta, there is a new %feature() function:

@startuml
title
Value for style: %feature("style")
Value for theme: %feature("theme")
Value for non-existing: %feature("some future feature")
endtitle
alice->bob
@enduml
Any other strings than style and theme will return 0.
In the future, we could change those values and add new features, so that themes/library could test which features are available on current running version.

This won't help you right now, because this %feature() function is not implemented on older versions.
So you can use the following workaround:

!if %function_exists("%is_light")
' this is 1.2020.6, at least
' use style
!else
' for older PlantUML, let's use skinparam
' use skinparam
!endif

This helps. It will allow me to include both skinparam and style into the theme files.

So we have just introduced a new syntax, where you provide two colors: one for light background, one for dark background.
This is quite experimental and working only for Font color.

@startuml

<style> document { BackGroundColor Navy } root { FontColor #?black:white } </style>

title
my title
endtitle
class foo1
foo2 <|-- foo1
@enduml
This is not finished and not working in all case, but you've got the idea.
Is this what you where expecting ? (Of course, you can choose other colors than black and white)

Yep, this will be good. I think with this, a theme will be able to support both light and dark backgrounds (maybe not perfectly, but sufficiently).

Question: The FontColor at the root level, that will be the default color, correct? In other words, you can override this value within each component (i.e. activity, sequence, etc)?

PS: the -theme flag is also implemented in last beta.

Ok, cool. I will try it out this weekend.

If I have time, I might start modifying the themes this weekend to take advantage of these new features.

[bschwarz]

Sorry, one more question. For the FontColor:

root {
  FontColor #?black:white
}

What will get chosen if the background is set to 'transparent'?

[arnaudroques]

Question: The FontColor at the root level, that will be the default color, correct? In other words, you can override this value within each component (i.e. activity, sequence, etc)?

Yes, exactly. Everything inherits from root, so you may set this value (as a default value), then override it as you wish afterwards.

Sorry, one more question. For the FontColor:

root {
  FontColor #?black:white
}

What will get chosen if the background is set to 'transparent'?

Here we have a real issue.

There is no way to guess if the real background color behind transparent is dark or light. (Well, I think, tell us if you have an idea!). So right now, we assume 'transparent' to be light.

We are thinking about adding two directives:

• !assume transparent dark
• !assume transparent light

So that the end-user can change this default behavior. This is not perfect...

[bschwarz]

Here we have a real issue.

There is no way to guess if the real background color behind transparent is dark or light. (Well, I think, tell us if you have an idea!). So right now, we assume 'transparent' to be light.

We are thinking about adding two directives:

!assume transparent dark
!assume transparent light
So that the end-user can change this default behavior. This is not perfect...

How about adjusting the syntax, so it might look like this:

root {
  FontColor #?black:white:blue
}

Where that third color (i.e. blue), would represent the color to use if transparent. Could make that one optional, and default to current behavior.

I know that makes that a little more messy, but seems consistent with current syntax.

[arnaudroques]

So your suggestion has been implemented in last commit.

The third color is optional.
To cover all cases, we have also implemented !assume transparent dark and !assume transparent light.

Hope this helps !

[bschwarz]

Ok cool. I will try this out this weekend.