Documentation - Was -"What are hSscroll, vScroll really? (Richmond)"

[Francis Nugent Dixon]

Hi from Sunny (would you believe it ?) Brittany

Richmond wrote :

> The current documentation DOES contain a lot of good, a lot that is 
> obscure, and a fair bit missing or incomplete.

Here's my 2 cents ……

I would like to second all that Richmond has said concerning "DOCUMENTATION",
but I would like to add a few comments.

The "Dictionary", available from the IDE, gives us a list of all possible
LiveCode commands, with a "limited" set of examples. This, in my view
is where the Documentation fails. As a LiveCode user for several years,
with a 15 year Hypercard background, the "limited" examples in the online
documentation provide me with more frustration than solutions.

I admit that a complete description of LiveCode commands plus an exhaustive
set of examples would result in a humungous file that would blind most
LiveCode users (and take years to produce).

So, using "links", let us see if we can get ALL the answers, in a relatively
simple "LEVEL" approach.

Most of LiveCode subtilities (especially examples) have been drafted already
by Revolution personnel and LiveCode Users. It's all there - "somewhere".
I find that a reasonably intelligent search command on Google, such as
"Livecode functions" will point me to a few Google "hits", one of which will
satisfy my requirements. (try this on Google and number one hit is Jacque's
comprehensive discussion about "Functions). Why doesn't the online doc point
to such beautiful overviews ?

However, this takes time, and energy, and I think that the Revolution
Documentation Specialists should finally reply to this need. The addition
of "User" comments to the online documentation was a great idea, but had
little (and only partial) responses.

So I humbly suggest (and open a door to discussion ?) the following :
To each of the command descriptions in the online LiveCode documentation,
I would add 3 lines :

1 - Link to - " A wider range of examples of the current command",
2 - Link to - "A more complex set of examples, with explanations",
3 - Link to - "Examples for the LiveCode geeks, who really push LiveCode to the limits.

(2) and (3) would probably have snippets of code to wrap up a complex use of a command.

This would mean relatively few mods to a pretty good (but incomplete) online dictionary.

All of the information for these three levels of information exists. It could
be gathered together in several data bases accessible on the Internet, or, to
simplify implementation, the links could point to existing internet data
(there are Gigabytes "out there", we just need to point to them in an intelligent manner).

Whatever the way of implementing a comprehensive presentation of LiveCode mechanisms,
I think it should be attempted. How about a "Call for Papers" to RevCode users, specifying
format and structure of papers entered ? Lots of RevCode knowledge "out there" !!!

And we should never forget the old adage " It is by example that we learn" !

So why don't we have examples - ALL OF THEM -  (simple AND complex), and a
clear set of rules to access them ?

With Hope

-Francis