REBDOC redux WAS => Re: Re: Please explain...
[1/1] from: jasonic::panix::com at: 17-Nov-2001 22:41
> so we shouldn't be too hard on RT about this. Just a little hard. (:
agreed..
But seriously what kind of docs-how-to search and indexing features would
you want to see there?
If parse is "the jewel in REBOL's crown" then waht role does it have to
play?
What kind of tools do you think are easy | hard for rebol to do?
I was wondering what simple wide changes could improve the long-term
documentation situation. To build and improve documentation, particularly
the little narrative threads and one wants to find in the source is tricky.
It takes time, knowledge, bytes, cvs-like versioning of some kind to allow
people to share but keep sync and control where RT need it to be.
So here's my idea:
1. insert some small documentation token widely through out all the
mezannine source. Just a brief unique marker to keep the file size minimal.
2. maintain a documentary database online, using a wikilog type of engine. I
propose use Vanilla.
3. Each doc token would represent, and be represented by a Vanilla {snip}..
comments can be added accordingly. Follow the simple, potent, consistent
modularity that Vanilla offers.
4. Create a few REBOL programs to handle the merging linking, search adn
display of doc {snips}. Now, when one wants to docs they are can always be
fetched and displayed by an application or interface one wants to develop.
They are even partially pre-parsed by nature of their intrinsic modularity!
just as now one can download all the library or update REBOL implicitly, so
one could say:
>> source/documented someword
This would display the source as now, but also evaluate the tiny doctokens,
replacing them with the expanded readable text {snips}. Likewise
>> source/documented/comments someword
would show all the above PLUS other contributors comments to the 'offcial'
inline doc text. This idea assumes one needs a system in place which will
really help grow a rich and sustainable documentation environment. That this
takes time and REBOL has enough organic scope to encourage people to add
value, but RT do not have enough time/people/? to track all that and play
publisher. They are focused on moving the technology itself forward. However
at their peril if some better strategy for documentation is not addressed
more intelligently.
>> source/documented/examples someword
would display someword with RT's in-line text but also small examples.
>> source someword
would only show the code, no help other than hardwired help.
>> source/need someword
might open a messaging reblet where one could submit needed documentation or
comments.
Since REBOL uses a cache mechanism but implies internet connectivity, the
doctoken {snips} could be made available on-demand and/or as an aggregated
download. Serving the snips would be interesting especially with the
extended /examples refinement library. Everyone could keep adding to the
examples library.
I believe if such a mechanism were in place now for /Core /View & family, it
will become MUCH easier when people start building more complex application
suites, new dialects etc.
Glass may be the sort of development which could profit from this. Don;t
know yet.
Mailing lists like this do work very well, but tools like REBOL can quickly
become victims of their own success. The more people jump in the more
development the more excitement the ifsadnsbuts the more layers of answers..
<anecdote>
This is what has happened to Zope. I am moving apt next week, going through
everyhting, packing up, There are piles and boxes with wonderful clustered
printouts from the past 2 years of Zope gems. It is almost all going in the
bin. Overwhelming, and largely obselete.
</anecdote>
./Jason