Yes. Everything that is not covered by the dictionary.
And stuff at a technical detail that is too much for the user manual.
One of the more important aspects: syntax. But also stuff like: binding, argument passing modes, cor e evaluation semantics.
Language Design/Implementation Reference?
That's a very, very good suggestion Andreas. It won't be easy to write well. Do you think you may have a little time to help with it?
5) a dictionary of values
I always found it strange that the equivalent of the word dictionary for values was hidden away as an appendix in the Rebol user guide. I think such an important aspect of the language needs a more visible presence.
Do you mean like a standard library reference Peter? I have notes for something like a Nutshell series book.
What I'm thinking of is a short explanation of each value! type.
Something like this:
A char! value represents a Unicode code point. It is a number in the range hexadecimal 00 to hexadecimal 10FFFFF.
The literal value of a char! value is of the form #"a" or #"^(0032)".
I would call that a "reference", and could be an appendix in the core user manual.
Listing all the datatypes should be part of 1).
Yes. Working on some of that now.
By the way, a preliminary work would also be to define a lexicon for the basic concepts, like talking about "variables" or not, "assigning a value to a word" vs "giving a meaning to a word in a context". We need to define a common vocabulary so that the docs look consistent regardless of who is writing.
Yes. That will be very important.
I am also wondering if a single entry point for (1) is the best option. We know from Rebol that the learning curve has at least two steps (Carl's lake analogy) the surface and the depth. The surface is very quick and simple to learn, but might be misleading or even confusing for users with a CS background. So, there's a second "advanced" step in the learning process where you usually get the "eureka" moments, once you get things like code/data duality or the nature of definitional and dynamic binding.
I'm sure we'll want special docs for advanced users who would otherwise not find the information sprinkled in the standard user guide.
So for (1), you suggest we aim at the "surface" only?
I think (1) can, and should mention these things, but doesn't need them as complete chapters. They could be advanced chapters or appendices. But could stand alone as well.
Wasn't there once the community effort, to bring some kind of better docs to Rebol? I remember we defined structure or something like that ...