World: r4wp

If you want to do something fancy, you could add interactive examples, 
like on http://w3schools.com

My thoughts - All documentation needs to be in a single location. 
It should comprise 3 main sections 1) Explanation of how rebeol works 
- like core manual plus inner working of Rebol - the theory, 2) Reference 
of every word with samples of how to use the each word - must be 
exhaustive, 3) Tutorials split into novice, intermediate and advanced 
- all with examples. Current Reboi documentation is much better now 
but is still too scattered and fragmentary and not enough examples 
on how to use each word. Anything in Red that is not documented will 
be a cause of frustration and will result in lack of use. Plan to 
do the documentation for someone who has never heard of Rebol and 
Red that way less corners will be cut and important information will 
not be assumed to be known.

Sorry for Rebol - read - RED

I think in sequence of creation, the reference should be done first.

Henrik, I agree. However, documentation that just regurgitates the 
api that can be gleaned with "help" word is next to useless - documentation 
needs to explain a lot more about a word than the api does - iat 
least: ts reason for existence, how to use it, and examples of usage.

yes, the R3 reference is functional for this. Initially it fills 
the skeleton parts that contain the same information as help, but 
it works like a wiki, where each page can be filled with examples. 
I think comments were planned as well, but that never came about.

when it comes down to it, I want every function to be documented 
in the reference with every defect, caveat, bugs, tricks and whatever 
can be found.

One example of a reference that I find very useful is the Clojure 
cheat sheet. The one one clojure.org doesn't have tooltips, but some 
do. The nice thing is that all link to the clojuredocs.org site which 
is a great for crowdsourcing usage examples, including notes, caveats. 
For sure Red should have something similar.


http://jafingerhut.github.com/cheatsheet-clj-1.3/cheatsheet-tiptip-cdocs-summary.html

http://clojuredocs.org

I don't know how it stands up to "modern" standars wrt interactive 
documentation, but I know that Gigaspaces won some kind of award 
for the organization/presentation of their developer documentation 
- this was a few years ago when I was investigating the technology.


http://wiki.gigaspaces.com/wiki/display/XAP91/XAP+9.1+Documentation+Home

Good example docs from Closure - very comprehensive and helpful - 
something like that with tutorials and theory would be cool

Hey, everyone seems to be in agreement on docs :-)

This one from Carl is even kind of nice - http://www.rebol.com/docs/reference.html

it should be easy to improve Carl's reference to look like the Clojure 
one - showing the help string on roll over event which is nice and 
helpful.

Regarding the Red's VID discussion - I think it's still too early 
to ask something like this. First there must be I/O implemented in 
Red. You cannot start bulding a house from the roof. I'm pretty sure 
that once Red will be mature enough, there will be people trying 
to make own VID clones. I have also no problem with native VID. It 
should be transparen imho. And tt should be clever enough to support 
different screen resolutions. Not like old R2's one. I don't remember 
if the R3's version was better in that.

Turn it around. You cannot seriously start building a house without 
knowing how the roof is going to be. After all the house is built 
because of the roof!

(at) Clojure jafingerhut: To be honest I hate those popup messages. 
You cannot copy anything from them and to keep them in site you are 
required to hover the mouse over the link. Not  what I want if I 
have to type something from its contents in another window.

site = sight

clojuredocs: check out this http://api.clojuredocs.org/search/clojure.core/map
real state of the art documentation :D

If you need to know how the roof will be before starting on the floor, 
we can do it like REBOL 3 and not release Red until we have VID

Arnold: it's clear that people will have different preferences. I 
find the tooltips handy for when I just want to refresh my memory 
by a quick hover without having to lose the context of the page I'm 
on. If I want more details (which could be copied and pasted), I 
just click through. What's the problem with that? If you don't want 
tooltips, don't keep moving your cursor, or make tooltips optional.

His point is, that with PC world converging towards touch, tooltips 
are a dead concept - there is no hover with touch devices. I also 
myself don't like pop-up menus, etc. - it was always a hell, and 
requires special treatment in GUI subsystems ....

Not so sure that mobile trends will mean no hover ability - I expect 
there's going to be a rise in the use of active styluses (along with 
touch) with the growing number of higher resolution tablets on which 
you can do some real work.

Put it this way - why should it bother someone if I want/like these 
tooltips as long as each person gets to configure the UI to their 
liking?

I've had a tablet pc (with active stylus) since 2007 and I still 
like what that brings for certain applications.

Adrian, tablets with styluses are rare now; the iPad led the way 
toward finger-only interfaces. It's been announced that the Surface 
Pro will have a stylus, but it's a passive one. The Android tablets 
with styluses are passive too, just using the stylus for a sharper 
pointer. An active stylus is an expensive peice of electronics, while 
a passive stylus is just plastic with maybe some metal or rubber 
on it, so you can see why they're preferring passive now. Hover is 
going away for a lot of platforms, or was never there for some of 
the new ones.

I think I'm seeing a different trend Brian. Non-active styluses were 
first used on the not tablet pc tablets because it's the cheapest 
solution and the first tablets had relatively low rez screens and 
were primarily meant for consuming content. When you start doing 
any serious content creation palm rejection is a big issue and the 
non-active styluses do a relatively poor job of this. BTW, the Surface 
Pro looks to have an active stylus - not sure where you heard otherwise. 
Also see the Samsung Galaxy Note tablets (hugely popular)  which 
also have an active stylus. IMO, you're just going to see more and 
more tablets support these as screen resolutions go higher and people 
start doing real work on their devices. 


http://forum.tabletpcreview.com/microsoft/54066-microsoft-announces-surface-pro-pricing.html

sorry, Doc - we shouldn't be polluting this group

EXIT and RETURN support have been added. Function! support is now 
complete. I plan to add closure! support too (and maybe R2-like functions 
also), but having object! seems like higher priority for now, as 
I want to implement port! datatype asap.

A mention about THROW function attribute: I will add support for 
it, but it won't be usable until we get  dynamic function creation 
support.

I need to process some pending tickets from the bugtracker, so I 
will probably start working on object! support tomorrow.

btw - will you allow append to objects, like R3 does? (at least I 
think it does :-)

I always had mixed feelings about it, on one side it allows to extend 
objects in-place, which is very useful when they are referenced (in 
a tree structure for example), but it also encourages a, IMHO bad 
coding pattern, which is using objects to store data when you should 
use (the much cheaper) blocks instead.

So far, I think that the pros are more important than the cons, so 
Red will probably support it too.

Well, it would be strange from you to try to push us to recreate 
an object just to expand it, whereas in REBOL3 group you are wondering, 
why function bodies are not hot-patchable anymore, no? :-)

Well, it is not the same thing. APPEND on object is blurring the 
semantic lines between an object and a block, that is not a good 
thing IMHO. It makes the choice more confusing between them for newbies 
(or maybe even some more experienced REBOL coders) while the distinction 
should be clear.

it would be strange from you to try to push us to recreate an object 
just to expand it


That is part of the basic semantics of the R2 object! datatype, it 
follows the prototype-based model. You construct new objects by copying 
existing ones, it can be just a copy (cloning the source object), 
or derivation (extending the source object with new words). Changing 
object context (adding/removing words) without creating a new one 
is not consistent anymore, so it can look like a big hack.

Correcting myself: "derivation" might not be the best word in such 
context, "extension" would be more neutral.

On the subject of hot-patching, I've thought for a long time that 
the ability to instrument apps--like DTrace--would be very helpful. 
I know DTrace is deep kernel voodoo, and not available on all OSs. 
If Red supported probe points for DTrace, that would be great for 
those who use it. My question is whether it would be better to use 
a DTrace model, where the analysis happens from outside the app, 
or if having an instrumentation/tracing/logging model internally 
is better. Or can you support both with the same set of probe points 
in an app?

It is in my plans since the beginning to support internal profiling 
feature for Red, though I was thinking about processing them in the 
IDE mainly. In the Red/System v2 specs, I have already made some 
provision for low-level profiling of native functions.


I know about DTrace but never used it. I would need to study how 
it implements probe points to see if same technic could be used internally.


Currently, it would be quite easy to add a profiler to Red layer, 
it would just need to extend the stack/mark*, stack/unwind* and stack/unroll 
function to collect the data. But as we have other high-priority 
features to implement first, it will probably wait a few months (unless 
someone wants to implements it, I would be glad to give the basic 
hints on how to achieve it easily).

I might make a 0.3.1 release tomorrow to set a milestone for functions 
support. If you have Red scripts, it's time to test them with latest 
commit.

Thanks Doc. Excellent info.

I agree that objects should be used sparingly, but not being able 
to expand them makes it expensive to implement VMs for substantial 
dialects. I did that and started out with blocks only, but over time 
I had to decide to use objects in places crucial to the user dialect

My conclusion was that, being fundamental to the language abilities 
of REBOL, contexts should be more flexible

I did a build run of the examples. It looks OK, but the many casting 
warnings on the GTK bindings are still there. I think that should 
be fixed

Doc, Is is possible to support something like VFS in SQLite (http://www.sqlite.org/c3ref/io_methods.html), 
So we (OK, me) can develop a simple RDBMS on Red, instead of doing 
it using Red/System

I'm not sure what you mean exactly by "support". I haven't implemented 
yet the interface for cross-access between Red and Red/System. A 
minimal interface will probably appear in the next weeks.

That VFS is about the file system interface. Do you want to write 
your own RDBMS on top of it, or do you want to use SQLite?

Part of that VFS is covered by the REBOL file access methods, but 
not the advanced functions

I am a bit short on time for testing on all platforms, did anyone 
find any regression in Red before I release v0.3.1?

Hi I had a look at the last changes yesterday . For what it's worth, 
code was cleaner/prettier. That's a good sign in general :)