REP: |
3 |
Title: |
Red Documentation |
Author: |
Peter W A Wood |
Status: |
Permanent |
Date Created: |
1-Aug-2018 |
Date Last Actioned |
28-Sep-2018 |
The Red Foundation develops and maintains four types of documents for Red.
These are formal specifications of the Red language and its major dialects. The relevant syntax will be formally documented using Backus-Naur Form (BNF) notation. The semantics will be concisely described using a formal style.
These documents are targeted at language implementors.
"" Rudolf Meijer’s spec is the current incarnation of this (https://github.com/meijeru/red.specs-public/blob/master/specs.adoc).
It should either be approved as the baseline, or a specific list of change requests made so it can be. This may have to come after a Style Guide is developed, but informal comments can be made in the meantime.
The home for this doc will be spec.red-lang.org
--Gregg ""
"" I do not agree that Rudolf Meijer’s spec is anything like a formal language specification. It is a decription of the features of the red executable and is much more like a reference document than a language specification. Rudolf has said the same himself in one of the chat systems.
Peter ""
These are reference documents that provide detailed information on the content of Red and its major dialects. They provide minimal explanation on usage and few examples.
These documents are targeted at experienced programmers familiar with Red (or similar languages). The Lua Reference Manual and the Python Reference Manual provide similar levels of detail. (Though both also incude elements of formal language specification in addition to their reference information.)
"" doc.red-lang.org is the current incarnation of this set of documents.
It should either be approved as the baseline, or a specific list of change requests made so it can be. This may have to come after a Style Guide is developed, but informal comments can be made in the meantime.
The home for this doc will be doc.red-lang.org
--Gregg ""
"" doc.red-lang contains multiple documents (some of which are self-contained) that may, or may not, be included in Red’s reference manual.The View/VID/Draw documents could easliy be consolidated as the basis of the Red/GUI reference manual. The pre-processor document can be included in the compiler and runtime reference manuals. The other material needs to be incorporated into a Red reference manual.
Peter ""
These are fuller explanations of Red and its major dialects including more detailed examples.
These documents are targeted mainly to programmers new to Red. The Rebol/Core User Manual and Programming in Lua provide similar levels of detail.
"" The REBOL Core Guide is the closest model we have for this, but we don’t, and likely won’t, get permission to clone it.
Some years ago, I started comparing models (6 or so) of various lang books, with basic scripting over MD files. Easy to experiment, or find an authoring tool. The main thing is that this needs a single author, or strong leader with 1 or 2 support people.
--Gregg ""
The following documents will be published by the Red Foundation.
Specification |
Reference |
User Guide |
Tutorial |
|
Red Language |
Not Yet Written |
Not Yet Written[1] |
Not Provided |
Not Provided |
Red Compiler |
Not Provided |
Not Yet Written |
Not Provided |
Not Provided |
Red Runtime[2] |
Not Provided |
Not Yet Written |
Not Provided |
Not Provided |
Red Console |
Not Provided |
Not Yet Written |
Not Provided |
Not Provided |
Red Core, Console & Toolchain[3] |
Not Provided |
Not Provided |
Not Yet Written[4] |
Not Yet Written[5] |
Red GUI[6] |
Not Yet Written |
Written |
Not Yet Written |
Not Yet Written |
Parse |
Not Yet Written |
Written |
Not Provided |
Not Yet Written |
Red/System Language |
Written[7] |
Written[8] |
Not Provided |
Not Provided |
Red/C3 |
Not Yet Written |
Not Yet Written |
Not Yet Written |
Not Yet Written |