[REBOL] Proposal: REBOL Documentation indexing system for newbies
From: gerardcote:sympatico:ca at: 3-Feb-2004 0:29
Hello Rebolers,
I finally thought of some structure to help index all the REBOL related Documentation
available, be it to any existing format from
paper to various electronic ones (HTML, XML, PDF, FLASH, script).
And this includes the many sources too : Existing and to come paper and electronic books,
tutorials and scripts, mailing list
archives, past and current articles and discussions held into Forums, chats, wikis, vanilla,
AltMe and IOS sites, and every other we
could think of.
I don't pretend to index all individual pieces but instead the many active and latent
sources where REBOL is discussed in some way -
trying to classify the many contributions by attributing them keywords and enabling some
full text search over these keywords. Like
is currently done for ML archives and scripts contained into the Official Library. But
I will need some help for deciding the many
categories to be finally used since they could also be used for the Library and any other
REBOL related similar work. I tried at
some of them in the enclosed documents but the list is neither definitive or exhaustive.
It's work in progress.
Try to think of it at it as being a cross indexing tool for the many following POVs that
our community members share :
As a newcomer that has questions to ask related to those general aspects : Where can
I find help about something, Where to start,
Where to get, What can be done with, How to download, install, configure, What if, How-to
applied to each phase of the software
development cycle (individual language construct learning oriented, task based oriented,
problem-solving oriented, debug or test
oriented, doc oreinted) and the most hard to answer Why does REBOL do that this way or
How is REBOL doing this (can even relate to
the internal mechanisms or structure of REBOL or some Dialect like Draw, VID and View
- and many of them are missing or must be
found the hard way by studying at the REBOL sources which already implies some advanced
knowledge of the language constructs).
As a more advanced programmer that has to develop some quality code to be shared with
other community members or even external
programmers when contracting, put code into some library, test it and ensure it to be
reusable. Use all the toolkit the pros use :
compression/decompression, encode/decode, loader, distributed programming and the like.
May be some models are no more necessary
when programmers arrived at this level come from another programming environment/language
where they have already learned to use all
these tools but some demo is nevertheless needed for others that didn't follow these
usual tracks so they can't get any help from
other sources than the REBOL World itself since they don't know any other language or
existing tool and often don't even know the
techniques that go hand in hand with these.
As a teacher who wants to put together most of these questions and try to answer them
with his own limited knowledge of the REBOL
language with its internals and his own limitation as a programmer so he must also refer
to some documented (or live as here)
knowledge somewhere to put some script to work and help newcomers and intermediate programmers
too.
But this fact must also reflect into the indexing and documentation I plan to produce.
Here is the first try I did to put together a global indexing system for all the doc
about REBOL that a newbie can find anywhere -
to be referred to a new source must be known to me and must acknowledge its content to
be shared by others too.
Enclosed are 2 files of my first general index for review and comment. The first is the
.txt that was used by make-doc-pro to
produce the other HTML output.
Except if you don't think it's a good idea or don't like the complete proposed structure
of the document - in the case which you can
suggest another one, I'd like to receive annotations about individual sections only.
Don't send back the complete .txt document
since it would be too long for me to locate the part of the text which was modified by
the submitter.
After compiling all the data received - if any - I will send the revised document. It
is possible that I go to the codeur.org forum
to submit it there for review and discussion too since Didec and Jason offered me to
help. However I wanted everybody to know what
was our work basis. Feel free to suggest any add-on to any current section. We'll take
every submission into account and we'll see
if each one can be kept or not. We'll advise and explain any submitter when his submission
can't be taken into account.
Regards,
Gerard
-- HTML Attachment decoded to text by Ecartis --
-- File: REBOL-Doc-Structure.html
@media screen { h1,h2,h3,h4,h5,p,a,br,li,td, .underline
{font-family:Arial;text-align:justify} hr {text-align:center} p,table
{margin-left: 10px;margin-right:10px} .defword {white-space:nowrap}
..deftable{border-style:none;vertical-align:top} .deftablefaq
{border-style:solid;border-width:thin} .end {font-size:8pt} .example
{margin-left:50px;margin-right:50px;border:2px solid;padding:
10px;background-color:#EEEEEE} .header
{margin-left:50px;margin-right:50px;border:2px solid;padding:
10px;background-color:yellow} .indented {margin-left: 50px} .litable
{text-align:left} .new {border-right: 10px solid; padding-right: 10px;
font-family:Arial} .note {margin-left:50px;margin-right:50px;border:2px
solid;padding: 10px;background-color:#FFCCCC} .tocindent {margin-left: 20px}
..top {font-size:8pt;text-align:right} .underline {text-decoration:underline}
} @media print { h1,h2,h3,h4,h5,p,a,br,li, #underline
{font-family:Arial;text-align:justify;orphans:5;widows:5} p,li,td
{font-size:10pt} ul,ol {page-break-after:avoid;orphans:5;widows:5} }Plan for
a suggested REBOL Documentation Structure
Plan for a suggested REBOL Documentation Structure(Note: Much work is left
tobe done for but this is a first try - Comments are welcome! Any omission
isentirely my fault and please help to complete if this project seems to be
useful to most of the REBOL community members to help any newcomer to better
find his way through the vast REBOL related material pool.
* The black bullets indicate work in progress that I planned to
personally contribute to.
* The white bullets are related to completed work that needs to be
indexed somewhere to be easily found and usable by any newcomer.
----------------------------------------------------------------------------
Contents1. Getting started[1]
1.1 Where to search for Help about REBOL[2]
1.2 A Brief Tour of REBOL family[3]
1.3 Teach Yourself REBOL in a fixed number of Days[4]
2. The REBOL Language[5]
2.1 REBOL Language Manuals and published Books[6]
2.2 Beginning Student subset Language (Should complete the actual
dictionary)[7]
2.3 Intermediate Student subset Language (Idem above)[8]
2.4 Advanced Student Language (Idem above)[9]
3. Learning REBOL[10]
3.1 How to Design Programs in REBOL - Teaching Modules[11]
3.2 Insider's view of REBOL[12]
4. Tools to support developers[13]
4.1 Tools Categories (to be refined)[14]
4.1.1 File and database management[15]
4.1.2 Debug support[16]
4.1.3 Library management[17]
4.1.4 Distributed programming[18]
4.1.5 Gui Management or Enhancement[19]
4.1.6 Graphics toolkit[20]
4.1.7 HTML - XHTML - XML - XML-RPC support[21]
4.1.8 Document Creation and Publishing support for multiple formats (HTML,
PDF, FLASH)[22]
4.1.9 Learning aids creation tools[23]
4.1.10 Dialects (created to help programmers and users alike)[24]
5. Libraries[25]
5.1 Official REBOL script Library Manual[26]
5.2 Miscellaneous Libraries: Reference Manuals[27]
6. Unofficial but Useful Documentation[28]
6.1 REBOL Hosting available[29]
6.2 Articles and discussions from the Official Mailing List (ML)[30]
6.3 Forums List (non exhaustive)[31]
6.4 Other REBOL related resources indexes[32]
7. Shared REBOL apps - by categories (Many are missing)[33]
7.1 Documents Publishing Tools[34]
7.2 Idea Sharing and organizing tools[35]
7.3 Other apps spreaded that must be indexed and classified[36]
1. Getting started1.1 Where to search for Help about REBOL
* Some hints to guide the newcomer to the REBOL world and its vast
documentation
1.2 A Brief Tour of REBOL family
* Comparative presentation of each family member and reasons to select
it(See REBOL site)
* The "Ten steps" proposed by Carl on the OFFICIAL REBOL site
http://www.rebol.com
1.3 Teach Yourself REBOL in a fixed number of Days
* This could be the Tutorial I'm working on now (in Easy-vid format)
Content yet to be refined before submission but will promote a REBOL based
problem solving approach Will present many small tasks to be done using
REBOLas a programming tool Will also emphasize some classical methodology
forstructured analysis, design (algorithms), coding, testing and debugging
techniques using REBOL's own tools and style guide. Some help in the form of
knowledge coming from the unified REBOL community members will be requested,
welcomed and sometimes necessary for me to complete this project...[ back to
top[37] ]
----------------------------------------------------------------------------
2. The REBOL Language2.1 REBOL Language Manuals and published Books
* Refer to the many manuals for - Core, View &PRO, IOS, Command , SDK -
See the official REBOL site http://www.rebol.com (Core User manual, Language
Dictionary, etc...)
* The published books available to help starters and advanced
programmerstoo!
2.2 Beginning Student subset Language (Should complete the actual
dictionary)
* A Illustrated minimalist list of REBOL words
2.3 Intermediate Student subset Language (Idem above)
* An Illustrated enriched list of REBOL words
2.4 Advanced Student Language (Idem above)
* An Illustrated more elaborate list of REBOL words
[ back to top[38] ]
----------------------------------------------------------------------------
3. Learning REBOL3.1 How to Design Programs in REBOL -
Teaching Modules
* Guidelines to help newcomers to programming develop their scripts
* Usage-vid script by Cybarite for /View programming
* Various tutorials about Parse and the many Dialects created by
community members
3.2 Insider's view of REBOL
* Here could be concentrated many articles from REBOL Zine and
* from other contributors as to how REBOL do some of its inside work
[ back to top[39] ]
----------------------------------------------------------------------------
4. Tools to support developers4.1 Tools Categories (to be
refined)4.1.1 File and database management
* File Manager (Gabriele Santilli)
* Other File Managers (See REBOL.ORG Library)
* ODBC socket server (REBOLFRANCE)
* MySQL Protocol (DocKimbel)
* DyBase Oriented Object Database (Konstantin Knizhnik)
* RebDB - Pseudo-Relational Database (Ashley Trüter)
* Flat Database (See REBOL.ORG Library and The Official Book)
Other entries to be put here4.1.2 Debug support
* Anamonitor (Romano Paolo Tenca)
Other tools to be added here4.1.3 Library management
* Slim (Maxim Olivier-Adlhoch)
* Many Loaders
Other stuff to be added here4.1.4 Distributed programming
* Rugby (Marteen Koopmans)
* eREBOL (ASP and JSP like)
Other entries to be put here4.1.5 Gui Management or Enhancement
* Glass Library (Maxim Olivier-Adlhoch)
4.1.6 Graphics toolkit
* Draw Dialect (Cyphre)
Many other contributions to be added here4.1.7 HTML - XHTML - XML - XML-RPC
support
* ML (Andrew J. MArtin)
* Names of the many other scripts contributed and their authors
4.1.8 Document Creation and Publishing support for multiple formats (HTML,
PDF, FLASH)
* Make-doc (Carl Sassenrath)
* Make-doc-pro (Robert Muench)
* Flash dialect (Oldes)
* Easy-VID (Carl Sassenrath)
4.1.9 Learning aids creation tools
* Make-doc-pro (Robert Muench)
* vid-usage (Cybarite)
* easy-vid (CArl Sassenrath)
* Vanilla (Christian Langreiter &al)
Others to be added here4.1.10 Dialects (created to help programmers and
usersalike)
* ML (Andrew J. Martin)
Others to be added here[ back to top[40] ]
----------------------------------------------------------------------------
5. Libraries5.1 Official REBOL
script Library Manual
* Doc already available from REBOL.org for the Librarian and the Library
Data Services
* Analysis of some selected scripts
* Additional DOC to be added for selected scripts: Usage, GOAL
description, High Level Design and sample data for testing
* May be we can expect some additional scripts sharing from the many
individual REB sites
5.2 Miscellaneous Libraries: Reference Manuals
* Slim (Maxim Olivier-Adlhoch)
* Other librarians available - ?
* Glass (Maxim Olivier-Adlhoch)
* High Level functions (Ladislav Mecir)
Others to be shared and added here[ back to top[41] ]
----------------------------------------------------------------------------
6. Unofficial but
UsefulDocumentation6.1 REBOL Hosting available
* Gabriele's Hosting company
Others to be added here6.2 Articles and discussions from the Official
MailingList (ML)
* ML archives contents for consulting and searching
* REBOL Zine
* REBOLForces
* Codeconscious web site
* Compkarori web site
* Individual contributors articles : Ladislav, Marteen, Jeff, Gregg,
Chris and others...
Others to be added here6.3 Forums List (non exhaustive)
* REBOLFRANCE - codeur.org
* REBOLTALK
Others to be added here6.4 Other REBOL related resources indexes
* DMOZ (the Open Directory Project)
* REBOLFRANCE
Others to be added here[ back to top[42] ]
----------------------------------------------------------------------------
7. Shared REBOL apps - by
categories (Many are missing)7.1 Documents Publishing Tools
* make-doc-pro
* make-doc
* Online make-doc anywhere (by Christopher Ross-Gill)
Others to be added here7.2 Idea Sharing and organizing tools
* Vanilla
* REBOL Wikis
Others to be added here7.3 Other apps spreaded that must be indexed and
classified
* Graphical Toolkits
* REBOL Application Framework (RFM)
Others to be added here[ back to top[43] ]
----------------------------------------------------------------------------
Document formatter copyright Robert M. M=FCnch[44]. All Rights Reserved.
XHTML 1.0 Transitional formatted with Make-Doc-Pro Version:1.0.8 on
2-Feb-2004 at 23:26:30
--- Links ---
1 #sect1
2 #sect1.1
3 #sect1.2
4 #sect1.3
5 #sect2
6 #sect2.1
7 #sect2.2
8 #sect2.3
9 #sect2.4
10 #sect3
11 #sect3.1
12 #sect3.2
13 #sect4
14 #sect4.1
15 #sect4.1.1
16 #sect4.1.2
17 #sect4.1.3
18 #sect4.1.4
19 #sect4.1.5
20 #sect4.1.6
21 #sect4.1.7
22 #sect4.1.8
23 #sect4.1.9
24 #sect4.1.10
25 #sect5
26 #sect5.1
27 #sect5.2
28 #sect6
29 #sect6.1
30 #sect6.2
31 #sect6.3
32 #sect6.4
33 #sect7
34 #sect7.1
35 #sect7.2
36 #sect7.3
37 #top
38 #top
39 #top
40 #top
41 #top
42 #top
43 #top
44 http://www.robertmuench.de
-- Attached file included as plaintext by Ecartis --
-- File: REBOL-Doc-Structure.txt
Plan for a suggested REBOL Documentation Structure
(Note: Much work is left to be done for but this is a first try - Comments are welcome!
Any omission is entirely my fault and please help to complete if this project seems to
be useful
to most of the REBOL community members to help any newcomer to better find his way through
the
vast REBOL related material pool.
**The black bullets indicate work in progress that I planned to personally contribute
to.
**The white bullets are related to completed work that needs to be indexed somewhere
to be easily found and usable by any newcomer.
=toc
===Getting started
---Where to search for Help about REBOL
** Some hints to guide the newcomer to the REBOL world and its vast documentation
---A Brief Tour of REBOL family
**Comparative presentation of each family member and reasons to select it (See REBOL
site)
**The "Ten steps" proposed by Carl on the OFFICIAL REBOL site http://www.rebol.com
---Teach Yourself REBOL in a fixed number of Days
* This could be the Tutorial I'm working on now (in Easy-vid format)
Content yet to be refined before submission but will promote a REBOL based problem solving
approach
Will present many small tasks to be done using REBOL as a programming tool
Will also emphasize some classical methodology for structured analysis, design (algorithms),
coding, testing and debugging techniques using REBOL's own tools and style guide.
Some help in the form of knowledge coming from the unified REBOL community members will
be requested,
welcomed and sometimes necessary for me to complete this project...
===The REBOL Language
---REBOL Language Manuals and published Books
**Refer to the many manuals for - Core, View & PRO, IOS, Command , SDK -
See the official REBOL site http://www.rebol.com
(Core User manual, Language Dictionary, etc...)
**The published books available to help starters and advanced programmers too!
---Beginning Student subset Language (Should complete the actual dictionary)
* A Illustrated minimalist list of REBOL words
---Intermediate Student subset Language (Idem above)
* An Illustrated enriched list of REBOL words
---Advanced Student Language (Idem above)
* An Illustrated more elaborate list of REBOL words
===Learning REBOL
---How to Design Programs in REBOL - Teaching Modules
* Guidelines to help newcomers to programming develop their scripts
**Usage-vid script by Cybarite for /View programming
**Various tutorials about Parse and the many Dialects created by community members
---Insider's view of REBOL
**Here could be concentrated many articles from REBOL Zine and
**from other contributors as to how REBOL do some of its inside work
===Tools to support developers
---Tools Categories (to be refined)
+++File and database management
**File Manager (Gabriele Santilli)
**Other File Managers (See REBOL.ORG Library)
**ODBC socket server (REBOLFRANCE)
**MySQL Protocol (DocKimbel)
**DyBase Oriented Object Database (Konstantin Knizhnik)
**RebDB - Pseudo-Relational Database (Ashley Tr=FCter)
**Flat Database (See REBOL.ORG Library and The Official Book)
Other entries to be put here
+++Debug support
**Anamonitor (Romano Paolo Tenca)
Other tools to be added here
+++Library management
**Slim (Maxim Olivier-Adlhoch)
**Many Loaders
Other stuff to be added here
+++Distributed programming
**Rugby (Marteen Koopmans)
**eREBOL (ASP and JSP like)
Other entries to be put here
+++Gui Management or Enhancement
**Glass Library (Maxim Olivier-Adlhoch)
+++Graphics toolkit
**Draw Dialect (Cyphre)
Many other contributions to be added here
+++HTML - XHTML - XML - XML-RPC support
**ML (Andrew J. MArtin)
**Names of the many other scripts contributed and their authors
+++Document Creation and Publishing support for multiple formats (HTML, PDF, FLASH)
**Make-doc (Carl Sassenrath)
**Make-doc-pro (Robert Muench)
**Flash dialect (Oldes)
**Easy-VID (Carl Sassenrath)
+++Learning aids creation tools
**Make-doc-pro (Robert Muench)
**vid-usage (Cybarite)
**easy-vid (CArl Sassenrath)
**Vanilla (Christian Langreiter & al)
Others to be added here
+++Dialects (created to help programmers and users alike)
**ML (Andrew J. Martin)
Others to be added here
===Libraries
---Official REBOL script Library Manual
**Doc already available from REBOL.org for the Librarian and the Library Data Services
* Analysis of some selected scripts
* Additional DOC to be added for selected scripts: Usage, GOAL description, High Level
Design and sample data for testing
**May be we can expect some additional scripts sharing from the many individual REB sites
---Miscellaneous Libraries: Reference Manuals
**Slim (Maxim Olivier-Adlhoch)
**Other librarians available - ?
**Glass (Maxim Olivier-Adlhoch)
**High Level functions (Ladislav Mecir)
Others to be shared and added here
===Unofficial but Useful Documentation
---REBOL Hosting available
**Gabriele's Hosting company
Others to be added here
---Articles and discussions from the Official Mailing List (ML)
**ML archives contents for consulting and searching
**REBOL Zine
**REBOLForces
**Codeconscious web site
**Compkarori web site
**Individual contributors articles : Ladislav, Marteen, Jeff, Gregg, Chris and others...
Others to be added here
---Forums List (non exhaustive)
**REBOLFRANCE - codeur.org
**REBOLTALK
Others to be added here
---Other REBOL related resources indexes
**DMOZ (the Open Directory Project)
**REBOLFRANCE
Others to be added here
===Shared REBOL apps - by categories (Many are missing)
---Documents Publishing Tools
**make-doc-pro
**make-doc
**Online make-doc anywhere (by Christopher Ross-Gill)
Others to be added here
---Idea Sharing and organizing tools
**Vanilla
**REBOL Wikis
Others to be added here
---Other apps spreaded that must be indexed and classified
**Graphical Toolkits
**REBOL Application Framework (RFM)
Others to be added here