Hi Bernie, On Tuesday, July 12, 2005, 11:20:13 PM, you wrote:
BS> Perhaps Rebol needs it's own built-in documentation standard. BS> MakeDoc is a very good tool for that purpose, but I don't see it BS> being used very much. An embedded documentation feature, a bit BS> like Perl's POD (Plain Old Documentation) or Java's JavaDoc, BS> both of which are embedded within a source program's comments, BS> might be a nice thing to add to Rebol. The embedded docs could BS> be generated by running the source files through some kind of a BS> MakeDoc front-end. This way, the program and the source code are BS> always together, which should encourage keeping them both up to BS> date and in synch. I agree - see: http://www.colellachiara.com/soft/Libs/autodoc.r for an example using PREBOL (the preprocessor bundled with the SDK, but also available separately). Example script: http://www.colellachiara.com/soft/Libs/utility.r However - please note that the documentation is usually intended for people that already know REBOL. What would really be needed - other than a real View manual - is "medium" size example scripts specifically annotated for beginners. Also... most focus on showing only the surface of REBOL, so to make it easy to learn. That only works if you are interested in: send [EMAIL PROTECTED] read http://www.rebol.com/ Anything more serious than that requires more understanding on the fundamental concepts of REBOL, and you can't guess those just by knowing other languages. (You can guess the concepts behind PHP if you know C or any other similar language; but you can only get a partial idea of REBOL if you know Lisp and Forth very well; still, you would not realize that REBOL is a data language, closer to XML than to C for e.g., and that a functional interpreter is just built over it.) BS> I tried Rebol several years ago, and I didn't "stick" because BS> trying to figure things out from the always skimpy and out of BS> date docs was simply making me exhausted. While I was gone BS> though, I did keep an eye on Rebol, and several months before BS> View 1.3 was released, I noticed that the Rebol Dictionary and BS> User's Guide had been dramatically improved, so I decided to BS> give it another try. But I soon discovered that the View docs BS> still hadn't been consolidated, expanded or updated in those BS> four intervening years. Now that View 1.3 has been released, BS> it's even more critical that its documentation be brought up to BS> date, but that's not even a low RT priority, it's not even BS> mentioned in RT's future plans (see BS> http://www.rebol.net/article/0181.html). Actually, Docs are the highest priority right now. What is being very hard to do is finding someone to write them. You need a writer (not just a programmer!), and he has to know REBOL very well too. BS> But it's a mistake to believe that just because something is BS> simplified, that it's necessarily easy. In fact, simplification BS> can sometimes, make understanding harder, at least for a while, I agree 100%. Regards, Gabriele. -- Gabriele Santilli <[EMAIL PROTECTED]> --- http://www.rebol.com/ Colella Chiara software division --- http://www.colellachiara.com/ -- To unsubscribe from the list, just send an email to lists at rebol.com with unsubscribe as the subject.
