closed EBNF add notes?

0 votes
asked Oct 7, 2022 in Wanted features by Todd Musheno (2,680 points)
closed Oct 11, 2022 by Todd Musheno
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.
closed with the note: Works as I would expect

2 Answers

+1 vote
answered Oct 7, 2022 by plantuml (294,660 points)
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!
commented Oct 7, 2022 by Todd Musheno (2,680 points)
edited Oct 7, 2022 by Todd Musheno

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.

commented Oct 10, 2022 by plantuml (294,660 points)

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

commented Oct 11, 2022 by Todd Musheno (2,680 points)
I think that will do it!
commented Oct 11, 2022 by The-Lu (63,000 points)

Good. yes

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.

commented Oct 11, 2022 by Todd Musheno (2,680 points)
Looks good, might want to ad the little triangle pointing to what it's referring to, definitely optional
commented Oct 11, 2022 by Todd Musheno (2,680 points)
I have seen allowing multi stars to allow any characters in comments
(** *) **)
Is a comment with the text "*)" but it's rare
+1 vote
answered Oct 11, 2022 by plantuml (294,660 points)

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

commented Oct 11, 2022 by Todd Musheno (2,680 points)
The bottom note is optional.
commented Oct 11, 2022 by Todd Musheno (2,680 points)
Keep in mind, IF you need to, I think adding a dashed box around things is fine... if it helps the programmer.
commented Oct 11, 2022 by The-Lu (63,000 points)

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) wink

Regards.

commented Oct 11, 2022 by Todd Musheno (2,680 points)
Looks great, if anyone disagrees, please open a new ticket.
commented Oct 11, 2022 by The-Lu (63,000 points)
edited Oct 11, 2022 by The-Lu

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! sad

Regards.

commented Oct 12, 2022 by The-Lu (63,000 points)

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.

commented Oct 12, 2022 by The-Lu (63,000 points)

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.

commented Oct 13, 2022 by plantuml (294,660 points)
  • 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!
commented Oct 20, 2022 by The-Lu (63,000 points)

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

Thanks a lot,
Regards.

...