EBNF add notes?

Question

Could we add the ability to add notes to ebnf diagrams?

It would be nice to be able to add them to a rule, as well as a node in a rule.

Answer 1

That's a nice suggestion.

Could you give a simple example of the expected syntax? And also some examples of notes in EBNF diagrams if you have any.

Thanks!

Comments

Stealing from class diagrams... maybe something like the following:

@startebnf
rep = {fixed};
!note top of rep: Represents a repetition of fixed things
!note top of rep::fixed: The fixed things
@endebnf

Would add notes on rep and fixed the same way its done for classes/methods (not 100% on if fixed should even be allowed, but not against it).

Another way of doing this might be to annotate just the rule, syntax might be something like:

@startebnf
rep = {fixed}; note: Represents a repetition of fixed things
@endebnf

Open to either approach. but the documentation should show up in the standard note color either way.

---

Thanks for the idea...

We try to stick to existing standard when possible, so what about using (* and *) which are used for comment in EBSN:

@startebnf
(* This note is before the first expression *)

digit10 = ["0" (*this is a comment on 0*), "1" (*this is a comment on 1*)];

(* Yet another note *)

foo = bar;

(* A final note *)

@endebnf

---

I think that will do it!

---

Good. 

Here is the ISO EBNF comment definition:

@startebnf
title Comment def. on ISO EBNF

(* A comment is allowed anywhere outside a <terminal string>, <meta identifier>, <integer> or <special sequence> *)

comment = '(*', {comment-symbol}, '*)';
comment-symbol = comment 
  | terminal-string
  | special-sequence
  | character;
@endebnf

I will to check that...

Then during tests...

1/ Here is a minor issue when we have double or more comments:

@startebnf
title Test on comments
test = {exp1 (*this is a comment on exp1*)} (*this is a comment on rep. not shown*);
test = {exp1 (*this is a comment on exp1*) | exp2} (*this is a comment on rep. not shown*);
@endebnf

2/ Here is a minor issue when we have multi-line comments:

@startebnf
title Test on multi-line comments

(*
Multi-line
comment
*)
 a = a;

@endebnf

Or KO:

@startebnf
title Test on multi-line comments

(* Multi-line
comment *)
 a = a;
@endebnf

3/ Then:

• Could you allow begin line comments (see example on the ISO EBNF standard)?

@startebnf
title Test on the comments at the beginning of the line
(* begin line comment *) a = a;
(* begin line comment *) b
 = b;
@endebnf

Thanks for the improvement.
Regards.

---

Looks good, might want to ad the little triangle pointing to what it's referring to, definitely optional

---

I have seen allowing multi stars to allow any characters in comments
(** *) **)
Is a comment with the text "*)" but it's rare

Answer 2

We've made some progress but still have questions :-)

Comments

https://www.plantuml.com/plantuml/uml/JL7DQlD03BpxAUQxVGccq5v38QLGo6F8NjbUkjurAxakj7ttId4eELbcVZIpEejILUxoq6ZKn7Z6ImWnZxZ-2eHv5WmnCovlY8fGM92B8cRbEZ1LR54dwCIWNbTAHkdNcRD2fhAcO50KT9NftSSy2aZSQYWfbKrS2bcunwdvVyHhcLqi1bVKDJ6KHLlCSPmK6sMz6RA9NGid2IQcmBL5jogeAn-Cg88GQQmqutXetCRwVV7dyWXRv2xx0liktgNNVqR4Dupoz6CSfpXAwFTKA1cLbmVaSgstvUFXr7Zi2pOl2rd7aUKl8_hxEfxMabLATwz4uab1WtA58yLeUtLfSOkmdu1yz2vdpi6lzWi0

---

The bottom note is optional.

---

Keep in mind, IF you need to, I think adding a dashed box around things is fine... if it helps the programmer.

---

Hello PlantUML,

Here is a fully example:

@startebnf
title Test on comments
test_rep = {exp1 (*this is a comment\non exp1*) | exp2 (*this is a comment\non exp2*)} (*this is a comment on the repetition not shown*) | a (* comment on a *);

test_alt = z (*this is a comment\non z*), [a (*this is a comment\non a*)| b(*this is a comment\non b*)] (*this is a comment on the alt. not shown*), z (*this is a comment\non z*);

test-grp = (a (*this is a comment\non a*) | b (*this is a comment\non b*)) (*this is a comment on the group not shown*) , c (*this is a comment\non c*);
test-grp = a | b , c;
@endebnf

Then, a proposal:

• preferentially above [without arrow](with the same width as the corresponding element, on which the comment is given) (or all below) 

Regards.

---

Looks great, if anyone disagrees, please open a new ticket.

---

I was lost...

Here is a funny example:

@startebnf
title Test on comments

test_alt = z (*this is a comment\non z*), (*this is a prefix comment\non alt*) [(*this is a <b><color:red>prefix comment\non a*) a (*this is a comment\non a*)| b(*this is a comment\non b*)] (*this is a comment on the alt. not shown*), z (*this is a comment\non z\n<b><color:blue>or a global end comment ??*);

@endebnf

No ideas for this night...
Help is welcome...

The big issue is what do we do with the final comment...
and how to display the examples of the ISO EBNF standard?

How to dissociate an 'end global comment'  with a 'comment on the last element'?

Finally EBNF is not consistent with comment! 

Regards.

---

Hello PlantUML, and all,

A little idea for the evening.
Forget the 'global comment' at the end of the declaration (due to ISO EBNF std).

Then let's look at the other comments:

• why not say that the prefixed comment will give comments above the objects
  and that the suffixed comment will give comments below their respective object?
• That's make sens or not?

Here is an example:

@startebnf
title Test on comments

test_alt =  z (*this is a comment\nbelow z*), (*this is a prefix comment\nabove alt*) [(*this is a comment\nabove a*) a (*this is a comment\nbelow a*) | (*this is a comment\nabove b*) b (*this is a comment\nbelow b*)] (*this is a suffix comment below the alt. *), (*this is a comment\nabove z*) z (*this is a comment\nbelow z*);
@endebnf

In the same topic, beware to:

@startebnf
title Test on comments

test_above_below_first = (*this is a comment\nabove z*) z (*this is a comment\nbelow z*);
@endebnf

Have a good night,
Regards,
Th.

---

The last question before the night:

• Is possible to have an empty comment on EBNF?

Then, beware to:

OK:

@startebnf
(**)
test =  a ;
@endebnf

@startebnf
test =  a (* *);
@endebnf

KO:

@startebnf
test =  a (**);
@endebnf

@startebnf
test  =  a (*) ; 
@endebnf

Thanks to avoid a `java.lang.IllegalArgumentException`.

Regards,
Th.

---

• why not say that the prefixed comment will give comments above the objects
  and that the suffixed comment will give comments below their respective object?
• That's make sens or not?

Yes, that's a very good idea and make completely sense!

We're going to work on it and will post a message here when ready.

Thanks again!

---

It seems good with last Snapshot (~v1.2022.10beta1+)

Thanks a lot,
Regards.