AltME: Red Docs

Messages

Gregg
I think the clojure ref model and the couchbase manual model are fairly compatible as well.

Gregg
DocKimbel
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
DocKimbel
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.

Andreas
4) a language reference
DocKimbel
You mean a language specification document?
Andreas
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.
Gregg
Language Design/Implementation Reference?
PeterWood
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.

Gregg
Do you mean like a standard library reference Peter? I have notes for something like a Nutshell series book.
PeterWood
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)".
Gregg
I would call that a "reference", and could be an appendix in the core user manual.
DocKimbel
Listing all the datatypes should be part of 1).
Gregg
Yes. Working on some of that now.
DocKimbel
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.
Gregg
Yes. That will be very important.

Last message posted 405 weeks ago.