After investigating, we identified that the root cause lies in an ambiguity in the behavior of %newline(). Specifically, %newline() serves two conflicting purposes:
1. It inserts a line break in the postprocessed source text, which can affect the syntax and validity of the generated script.
2. It also controls visual line breaks in the rendered diagrams.
This dual purpose creates confusion and potential inconsistencies, especially in cases like yours where %newline() is expected to generate valid source code during preprocessing.
Proposed Solution:
To resolve this ambiguity, we are considering introducing a new function, %breakline().
- %breakline() would strictly insert a new line in the postprocessed source text, ensuring valid syntax generation when building PlantUML scripts dynamically.
- %newline() would retain its current behavior for visual line breaks.
We believe this separation will make the language more predictable for users.
For example, consider this diagram:
@startuml
!function $message()
!return "this is" + %newline() + "on several lines"
!endfunction
Alice -> Bob: $message()
@enduml
In this case %newline() inserts a new line in the text sent to the rendering engine.
Here’s your original example modified to demonstrate how we’re considering addressing this issue:
@startuml
note as N
bla bla
end note
!function $createNoteM()
!return "note as M" + %breakline() +
"this should work too in " + %version() + %breakline() +
"end note" + %breakline()
!endfunction
$createNoteM()
@enduml
Here, %breakline() would specifically insert a new line in the preprocessed source text, ensuring the generated script is valid.
We fully acknowledge that this approach would introduce a breaking change for users who rely on %newline() for source preprocessing. We deeply regret the inconvenience this may cause, and we’re carefully evaluating the best way to manage this transition. Your feedback helps us improve and make the language more consistent in the long run.
Thank you again for your report, and please accept our apologies for the disruption. We’ll keep you updated on the resolution.