So, in a nutshell: - github for hosting the docs (in a red/documentation repo) - markdown for the initial format (with eventually some additions) - Nim's documentation layout and style
For the content itself, we need: 1) a user manual (with the same level as the Rebol/Core Manual) 2) a dictionary of the words 3) some tutorials
(1) is the biggest and most important part.
4) a language reference
You mean a language specification document?
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.