Library & smart docs => was:{Re: [REBOL] Re: Parsing comment}
From: jason:cunliffe:verizon at: 25-Sep-2002 19:04
Hi Graham
Yes Tim <wink> described it like this:
<quote>
I don't know that they do. I was active on the Rebol mailing list for a
year, and most newbies appeared to be baffled by both the semantics and the
(lack of) syntax. Few appeared to make swift progress in "getting it",
either, and most left. A few hung on baffled the whole time I was there.
The docs were a mess at that point in Rebol's life (much of the mailing list
traffic at the consisted of "hey! I typed this in, and this is what I got!
Can anyone guess what it's doing?"), and the language has changed some since
then, but I stopped paying attention.
</quote>
> If the librarian project ever gets off the ground, perhaps
> this aspect could be addressed. Scripts could be rated on
> their instructive value. A way to vote perhaps?
Glad you steered the topic this way!
..if the project gets off the ground here's some of my recent thoughts about
it..
Rebol Library contributors should be able to add comments and explanation to
code source *in-line*.
But how to do that without making a mess of the so?
Too much of good think is not a good thing, especially when its Rebol!
Too many comments would bloat the size, and worse make it hard to read. If
comments are added only at the head or tail then it the larger size is not such
an issue.
That's like a wiki-blog where comments are 'beads' - a set of threaded files
joined together in sequence. Vanilla creates snips named "comment-{snipname}"
In-line comments could be brilliant though.
Tutorials are what beginners lack - running commentary.
So we need a way to manage the Library which accomplishes several things:
1. Keep it up to date and intelligently structured.
2. Indexed and searchable, returning useful results.
3. Open for contributors to add comments, examples using scripts, and links to
others.
4. Open for contributors to suggest special in-line comments suitable for
generating tutorial versions of the scripts
4. A review mechanism so the Librarian can review all contributions and include
them easily, select and include the changes
5. Notify people what's new. ie: precise links when changes have been committed
How to do this?
Vanilla can do the content management issue right now. Andrew Martin's wiki can
too I think, though I've not used it. Brett said he was working on CMS stuff too
I think.
>> But in-line comment handling is trickier. How to do this well?<<
'Leo' can do this !!
It handles prefix- and suffix- type comments, structural code/comment includes
and {tada!} in-line comments.
I have been learning to use Leo better over past few days. Leo is a powerful
tool to organize and manage source changes with comments and flexible cross
linking/categorizing.
I just added Rebol to Leo's list of language types.
Now when I 'saves' a project several things happen:
1. Leo saves everything as a single ".leo" file
This is a legit XML file which can be processed by anything. The XML markup
includes syntax so when Leo opens these xml files the tree is rendered correctly
with all metadata, cross-links and content intact. Any nodes marked for source
are also saved out automatically in their native formats. They can be edited
externally. The Leo file will include them correctly and update itself:-)
2. Node in the tree marked with "@file somename" will be saved as an external
file.
3. Nodes marked "@language rebol" are saved as ".r" rebol files.
Leo's own markup are converted to comments with ";"
Other ['--language'] types include Actionscript, Java, C, C++, HTML, Python, PHP.
4. There are a small number of other Leo directives for managing comments,
includes and special features.
@ignore does not export. So a page of notes within a node can be left out of a
the rebol file.
@first lets one specify the bangpath statement
5. If you don't want any trace of the Leo markup, that's easy to do with command
'RemoveSentinels' Voila! 100% pure clean sweet short REBOL scripts.
6. Leo lets one reuse the same content in several ways. 'Clones' are aliases
used within the outline tree to make it easy to have the same content under
different category headings in different places. Combined with in-line
insertions it's very powerful. Since Leo files are 100% XML, on can use XSLT to
process them. For example the same source saved in a Leo outline file could be
used to generate rebol, Easy-VID, HTML, colorized stylesheet layout HTML, and
even an entire linked Library site.
A good use of XSLT would be to generate HTML from Leo of rebol source code so
that in-line tutorial comments can be "folded/unfold" with a click like XML does
in MSIE. Another is sophisticated dynamic stylesheets are easy to do because
simple user requests can trigger changes. For example user search would
'highlight' and 'expand' results within code.
The decision to use REBOL vs. XSLT is an open one. One can mix and match them
even.
I have only just got into XSLT. I was scared and confused and suspicious of it
before. I am starting to see that it has much in common with REBOL.
REBOL is always shortest and sweetest it seems. But XSLT has the advantages of
immediate inter-operability with a rich set of tools, docs, and tutorials. For
content already in XML, XSLT makes pretty good sense. Some say it's too
cluttered and complex. XSLT is very versatile. It does not even have to be used
with XML. For example, XSLT could be used to convert a Leo REBOL Library tree
into MakedocPro or Easy-VID files. I don't have enough experience to know which
is easier for parsing and exporting a big XML source input file like that.
LIBRARY - 5 solutions
A. KISS-XP
Forget all this.
Just add some comments to the source.
Ask people to add in-line notes.
Librarian reviews and commits via simple expedient FTP/HTTP/REBOL tools
http://www.rebol.com/docs.html
B. VANILLA
Vanilla can do all the above too.
It's a 100% rebol web-based solution.
Vanilla has a simple elegant architecture with custom scripts, comments and
in-lining now.
Con: It's Rebol but hacking around takes time because severe lack of docs.
http://www.langreiter.com/space/Vanilla
C. LEO
Use Leo now. And 'publish' to multiple formats including Vanilla for web site
presence.
Librarian needs to try Leo and learn it. Leo benefits from openSource community
and has strong interoperability. Needs Python skills to customize.
http://personalpages.tds.net/~edream/front.html
D. EASY-VID LIBRARY
Build a version for the Library in 100% Rebol, adapting some of Leo's good
ideas.
Easy-VID
sort of does this now. It has the wonderful and rather unique ability
to execute code with a single mouse click, right in the middle of text.
It's an incredibly persuasive demo of Rebol itself.
Two problems I see in Easy-Vid based solution is that it is not web friendly
and enabling.disabling so that needs to be managed.
http://www.reboltech.com/library/html/easy-vid.html
E. REBOL APPLICATION FRAMEWORK
Robert's new 'Rebol Application Framework
I need to read the white paper carefully and catch up on the RFC thread.
To understand what it is and if its relevant here. Anyone?
http://www.robertmuench.de/rebol-framework.html
./Jason