Mailing List Archive: 49091 messages
  • Home
  • Script library
  • AltME Archive
  • Mailing list
  • Articles Index
  • Site search
 

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