Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Poor Language reference structure #232

Closed
bernardnormier opened this issue Aug 3, 2023 · 1 comment
Closed

Poor Language reference structure #232

bernardnormier opened this issue Aug 3, 2023 · 1 comment
Labels
bug Something isn't working

Comments

@bernardnormier
Copy link
Member

The structure of the Language reference is not good:

  • virtually all the useful information is on the Grammar specification page
  • the information on the remaining pages is mostly or entirely redundant

Furthermore, it's impossible to reference specific syntax on the grammar page:
https://docs.testing.zeroc.com/slice2/language-reference/grammar

because it uses gigantic code blocks such as:
https://docs.testing.zeroc.com/slice2/language-reference/grammar#lexical-grammar
https://docs.testing.zeroc.com/slice2/language-reference/grammar#syntactic-grammar

I think it would make much more sense to:

  • "merge up" the grammar specification, convert each section on the grammar page into a separate page: Lexical Rules, Grammar notation, Symbol conventions, Core languages, Preprocessor directives etc
  • delete the other pages while salvaging any useful information in them
  • introduce additional titles and levels to allow referencing

For example, if you look at the C# spec, you can reference
https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/types#82-reference-types
https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/types#83-value-types

It's not one giant ANTLR block with everything in it.

@bernardnormier bernardnormier added the bug Something isn't working label Aug 3, 2023
@InsertCreativityHere
Copy link
Member

The language reference has been temporarily deleted. See #304.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working
Projects
None yet
Development

No branches or pull requests

2 participants