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

[Jim Bufalini]

Adrian Williams wrote:

> Len,
> 
> Your observations are correct and I already have Dan's "Software at
> the Speed of thought".
> It's just that I'm an occasional user of Rev; I don't use it anywhere
> near full-time.
> Not coming from a HyperCard background does not prepare one for Rev's
> principles.
> If there are different ways to achieve the same thing, then let's have
> some cross-referenced examples.
> I've seen talk of a 'cookbook' on this list. Perhaps it is time for
> someone to captalise on that?
> 
> Like the Internet, when something is too flexible, it's a job to know
> where to start.
> Three ways to accomplish a few commonly used tasks may be enough to
> introduce novices the various processes.
> Three ways to "Launch an application"
> Three ways to "Track the path to a file"
> Three ways to...
> 
> Dans' book, great though it is as a primer, is not as accessible as
> many 'QuickStart' guidebooks available these days.
> Peachpit Press
> (http://www.peachpit.com/imprint/series_detail.aspx?ser=335245
> ) does a good job on many topics such as Java for example.
> HyperCarders must be fewer and fewer as time goes by, so something
> like that would make Rev far more accessible to newbies.
> That's my two-penneth for what its worth. As it's Bank Holiday, I'm
> off to fire up the BBQ.
> 
> All the best,
> Adrian
> ______________________
> Club Type
> http://www.clubtype.co.uk
> <adrian at clubtype.co.uk>
> 
> 
> 
> On 31 Aug 2009, at 13:05, Len Morgan wrote:
> 
> >
> >
> > 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.

I don't think I've ever seen a comprehensive and completely satisfactory
answer to the documentation conundrum for any language or application.

For example, I just looked at the Launch doc (which I hadn't for a while). I
note that it can be misleading. For example it shows, as an example, *launch
"SimpleText"*. Well, if this is on Windows and SimpleText is an executable,
you need to include the ".exe" extension. How would you know this? 

And, to make it cross-platform, you need to add a conditional that properly
launches on Mac or Linux. And, since many, if not most executables assume
dependencies, such as other files they look for in their own directory, or
subdirectories of their directory (think of your own standalones that may
look for an Externals subdirectory or other stacks in other subdirectories
to startusing or attach), you need to CD (Change Directory) to the app's
directory before calling the app.

And, it can get even more complex. For example, if on Windows the launched
app alters the Path statement, this "new" Path only applies to child
processes of the app and the original Path remains for the app itself,
siblings and parent processes. How does each app accept command line params?
And it goes on and the factors that could be relevant  multiply.

So, it's not just that Rev offers multiple ways to accomplish the same goal
(in this case: launch, shell, open process). There are so many other factors
that one needs to be aware of to even use a simple handler like launch. What
is then the scope and responsibility of documenting a single handler like
Launch?

Would a cookbook help? Maybe some. But could a cookbook address all the
possibilities? And, if it did, who would read it? I doubt anything short of
this list and others like it, where users answer questions and point to
available resources and sample code, in response to a specific question,
within a specific platform, environment and context, does the job.


Aloha from Hawaii,

Jim Bufalini