Documentation/Playground Observations & Questions

[StephenF55]

1. Question EGL page, Merge Engine section:
   The text states that "out" is a keyword, however this is not colour coded in the example code. I personally would expect keywords to be coloured. Is there a reason this isn't the case here?

2. Suggestion Epsilon Playground:
   Would it be possible to make the examples searchable? e.g. I wanted to see what the above "out" keyword looked like in the Playground 'IDE' but had to guess which example EGL to open (other than code comments, I didn't find it in the end and gave up). Having a 'Playground' search of source code (not comments!) would enable users new to the Epsilon languages easily find practical examples that bring to life the concept they are interested in exploring further. A similar improvement would be to have the ability to filter examples by language e.g. to show only EGL examples. Finally, I wonder would it be feasible for the Documentation page code examples themselves to be also available in the Playground?

3. Typo EOL page, Primitive Types section:
   Says "Returns true iff" in several places - "iff" should be "if"

[alfonsodelavega]

Hi Stephen,

1. I would say that out is a special EOL variable that is available in the template to communicate with the output stream. Being a variable, it is coloured as such, instead of using the keyword highlighting. As the documentation mentions, this variable is also used internally when other EGL constructs that provide syntactic sugar are used:

The [%=expr%] construct (line 2) is shorthand for [% out.print(expr); %], which appends expr to the output generated by the transformation

2. That could be a nice addition to make the playground examples easier to browse! We'll give it a thought.

3. Thanks for the pointer! I'll fix the typos in a minute.

Cheers,
Alfonso

[kolovos]

Says "Returns true iff" in several places - "iff" should be "if"

Iff is an abbreviation for "if and only if", but "if" works equally well in these sentences.

[kolovos]

Regarding syntax highlighting the out built-in variable, we already do this in the Eclipse EGL editor and I've now updated the EGL editor on the playground to do the same.

[StephenF55]

Thank you both.

1. On the meaning of the term 'out', I had expected you would say it isn't a keyword (as it has methods e.g. "out.print()") and that the following slightly confusing sentence in the Merge Engine section would be revised accordingly e.g. replace "keyword" with the correct description as follows:

"Within an EGL program, protected regions are specified with...on the out built-in variable."

Would that be possible?

2. Searchable playground: Thanks for considering!

3. "iff": Thanks for the explanation. I did wonder if this meant something more formal. For those of us unfamiliar with that shorthand, I feel that the plain old "if" reads better from the point of view of introducing EOL to newcomers

[kolovos]

"Within an EGL program, protected regions are specified with...on the out built-in variable."

This has been fixed in eclipse-epsilon/epsilon-website@06805c7

[StephenF55]

Thanks Dimitris 👍