Skip to content

Latest commit

 

History

History
155 lines (114 loc) · 4.67 KB

rep-0003.adoc

File metadata and controls

155 lines (114 loc) · 4.67 KB

REP 3 - Red Documentation

REP:

3

Title:

Red Documentation

Author:

Peter W A Wood

Status:

Permanent

Date Created:

1-Aug-2018

Date Last Actioned

28-Sep-2018

Introduction

The Red Foundation develops and maintains four types of documents for Red.

Specifications

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 ""

References

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 ""

User Guides

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 ""

Tutorials

These are basic Red programming tutorials.

They are aimed at people new to a programming domain or specific feature.

"" Do we include How-To/Cookbook docs under this banner?

--Gregg ""

Red Documentation

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


1. includes libRed API & RedBin
2. including interpreter
3. The Red User Guide
4. includes Parse
5. excludes Parse
6. includes View, VID and Draw
7. An updated BNF Grammar
8. The current specification