"1.2025.0" has "%newline()" bug (older version 1.2024.7 was working)

0 votes
asked Jan 21 in Bug by kirchsth (7,300 points)

maybe related to New Syntax Error in existing Sequence Diagrams (since 1.2025.0??) - PlantUML Q&A, but I tested it online and with "1.2025.1beta5"

In older versions following script worked without any problems:
e.g. I executed it locally with "plantuml-mit-1.2024.7"

@startuml

note as N
bla bla
end note

!function $createNoteM()
  !return "note as M" + %newline() + "this should work too in " + %version() + %newline() + "end note" + %newline()
!endfunction

$createNoteM()

' works with plantuml-mit-1.2024.7.jar
' fails with plantuml-mit-SNAPSHOT-1.2025.1beta5.jar

@enduml


I tested it locally with 1.2025.0, 1.2025.1beta5 and online. (link) None are working 



Can you check it. 
Thank you and best regards
Helmut

2 Answers

0 votes
answered Jan 21 by plantuml (295,960 points)
Thank you, Helmut.  

This issue appears to be a regression caused by the preliminary work related to "Suppression of \n management and Multiline text blocks proposal"  https://github.com/plantuml/plantuml/issues/1985

In principle, these preliminary changes should not have introduced any regressions, but clearly, that’s not the case here.  

We’ll investigate this further. Apologies for the inconvenience, and thank you for bringing it to our attention!
0 votes
answered Jan 21 by plantuml (295,960 points)

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.  

commented Jan 25 by kirchsth (7,300 points)
edited Jan 25 by kirchsth

thank you for the fast implementation

a) you are right: your version with automatic replacement is the more intuitive one
    (is was a 50:50 decision on my side)

You are right my ABC sample was very hypothetically but I tried to cover all scenarios
Maybe you extend the documentation with
   - the "$ advantages" are: automatic replacement works in all scenarios, supported by online/many editors ...
   - related to "%": it is reserved for builtin functions



With the new implementation, it could be very hard to write %newline() without replacement.
Therefor I suggest that
1) the escape character \ supports % and $ too  (\\..\; \n..produces new line; \%..% ->  \%newline()..%newline(), ... )
or 2) add a function (like %raw($mulltipleM()) ) that the argument of the raw function is not replaced.
or 3)  wink use the existing %chr(36) and %chr(37) and extend the documentation with the possibility 
or 4)  wink use a variable like !$msg="XXX%newline()XXX" and A->B:$msg and extend the documentation with the possibility 


b) you are right the 2 terms %newline() and %breakline() are necessary.
     (luckily, you checked that C4-Stdlib can be reused without any changes. Thank you for your effort)

c) sorry I have a finding with the new implementation: %newline() in table is not working

@startuml
!function $myMultiTableOK()
   !return "| a | b | abc\n def |" +%breakline()+ "| x | y | z |"
!endfunction

!function $myMultiTableNOK()
   !return "| a | b | abc" + %newline() + " def |" +%breakline()+ "| x | y | z |"
!endfunction

note as N
$myMultiTableOK()

$myMultiTableNOK()
end note
@enduml




d) with the new %newline() implementation, can you continue the next line with the same format too? (Or has compatibility the higher priority?)

@startuml
A -> B : <b>only first line%newline()is bold</b>
@enduml


BR 
Helmut

commented Jan 26 by plantuml (295,960 points)

a) We have created a new method: %percent().

Regarding the backslash, the main idea is to stop using it as an escape character.
We have started drafting some explanations here: https://plantuml.com/newline.
It's still a work in progress!

c) Thank you for the feedback, it has been fixed in V1.2025.1beta8.

d) Currently, formatting is reset with %newline().
I agree that this is not ideal.
It’s not easy to fix immediately, but I’m willing to consider this as a bug.
However, I suggest postponing this issue until after version V1.2025.3.

I hope this is not a big issue for you

commented Jan 26 by kirchsth (7,300 points)
a) my simplest (and still consistent) solution would be "4) updating documentation and using a variable".
    if you have %percent() then I think you need a $dollar() too,  

c) thank you

d) formatting is not a big issue for me (I have already the workaround with my own implementation in C4). A fix in one of the next versions is fine for me
commented Jan 26 by plantuml (295,960 points)

a) since buitin functions starts with %, we just added the %dollar() function.

Hope this helps!

commented Jan 30 by kirchsth (7,300 points)

related to d) only for documentation, there is an old format \n issue 
HTML tag based format lost after \n - PlantUML Q&A 

...