Rev Documentation [WAS: Launch another app from my standalone]

[Len Morgan]

Adrian Williams wrote:
>
> IMHO in the doc for 'launch', right underneath 'Examples', an 
> additional 'Example in use' would be helpful.
> Jim's snippet with its comments puts one of the example statements 
> into some context...
>
> put the defaultFolder into tOrigDefaultFolder
> set the defaultFolder to "C:\theDirTheExeIsIn" -- Put actual dir the 
> exe is in here
> launch "MyProgram.exe" -- Put the actual name of the exe here
> set the defaultFolder to tOrigDefaultFolder -- Puts the defaultFolder 
> back where it was
>
The problem with the above explanation that the defaultFolder lines have 
absolutely nothing to do with the launch command.  You could have just 
as easily wanted to launch an app that is relative to a URL which would 
take
another set of "chunk" explanations that again are totally different and 
totally unrelated to the launch command.  To write such all inclusive 
documentation for every command would be a daunting task and so verbose 
that it goes too far the other direction (i.e., so much to read that no 
one would read any of it).

It's a fine line that the documentation writers have to walk.  In the 
future, be sure to look at all the "See Also" entries in the dictionary 
and read the WHOLE command description.  The See Alsos can often point 
you in the right direction but also, at least in my case, lead me to 
learn things I hadn't even thought about before so I end up learning a 
lot more than if I'd had Scott's example laid out in front of me, took 
it verbatim, and left.

You are suffering from the same problem I know I had and I'm sure a lot 
of others had: The lack of a good tutorial book on Revolution to get you 
over the "hump" when you're new to the language.  It's my impression 
that a large percentage of the current Rev users came from a HyperCard 
(or one of it's derivatives) background and so they've  already  been 
over that "hump."  The simple terse Rev dictionary format is just fine 
for them.  I remember when I started (from a C/Tcl/Assembly background 
of MANY years) I couldn't even figure out where to start.  The whole 
concept of passing messages and calling handlers it totally different 
that the in-line code you'd write in C or Tcl.  Once I made that mental 
leap, things just started falling into place.  I still had questions 
that the documentation didn't answer by that's where this mailing list 
came in.  There was always somebody that could quickly fill in the 
"whole" in my knowledge.

I believe you can still get Dan Shaefer's (spelling?) book "Software at 
the Speed of Thought" which was written around Rev 2.1 I think but it 
was very helpful in getting me over a lot of the rough spots that the 
dictionary and user's manual didn't cover (and shouldn't have).  There 
are also a couple of HyperCard/Talk books by Danny Goodman that several 
people here have recommended.  I bought them but haven't really read 
them so I can't vouch for how helpful they'd be to you.

You do have a chance to help out humanity though (well, at least the 
part of humanity that is struggling to learn Revolution): the user 
comments at the bottom of the dictionary.  They are there for just the 
same kind of problem you were having, in other words, not quite enough 
meat around the bone to make it clear.  If you feel that something might 
need more (or better) explaination, add a user comment to enlighten the 
rest of us.  If we all contribute a little here and little there, we 
should end up with a first class reference that everyone will benefit from.


len