Guide how to enable keywords as identifiers #218

[JohannesMeierSE]

This PR contributes a guide to the Langium documentation, how to enable keywords to be used as regular names/identifiers/values for properties, according to #218.

It roughly explains the background for the issues and shows to how overcome them along the "hello world" example.

I am looking forward to your feedback!

[github-actions]

PR Preview Action v1.4.6
Preview removed because the pull request was closed.
2024-05-16 09:41 UTC

[JohannesMeierSE]

Thanks for your feedback so far! I just pushed the corresponding fixes.

[sailingKieler]

Thanks a lot for this guide @JohannesMeierSE 🙏.

I've a bunch of smaller improvements in the wording, feel free to take those you like.

[sailingKieler]

A few more suggestions, I'm done now 🤓

[sailingKieler]

Again, nice work!
I have a few more detailed optimizations.
Overall it's great, so 🚀

[JohannesMeierSE]

Thanks @sailingKieler for your helpful reviews! I just pushed the fixes.

[msujew]

Suggestion: The introduction in general is good, but I feel like the requirement to use keywords as identifiers should be explained a bit better:

Suggested change

	Langium treats keywords like `var`, `const` or `function` as keyword tokens, even at unintended locations according to your grammar.
	Additionally, these strings are always highlighted as _keyword_ (in blue in this guide, while other text is white) whenever they are used.
	Summarizing, these keywords cannot be used as values for names, identifiers or other properties by default and need to be explicitly enabled.
	This guide explains how to do that.
	As you write your grammar, you will add keyword such as `var`, `get` or `function` to improve the readability of your language and add structure.
	These keywords get a special keyword highlighting by default - in blue in this guide, while other text is white - and are handled separately from other terminals such as names, identifiers, numbers and so on.
	You will quickly notice that a function such as `function get()` will lead to parser errors, as `get` is a keyword and no valid identifier.
	This guide is all about how to enable these keywords to be treated as identifiers.

[JohannesMeierSE]

Thanks for the suggestion, I used it (slightly adapted)!

[JohannesMeierSE]

Thanks @msujew for the review! I applied the suggestions and moved the guide to the new location according to the new structure of the documentation.

[msujew]

Looks good to me. We could eventually factor out step 2 into a dedicated guide for semantic highlighting, but that's currently not necessary.