New User Doc Whine & What?

[François Chaplais]

Good point. This is why I wrote the dictionary stack

http://pagesperso-orange.fr/francois.chaplais/Site_2/Welcome_files/ 
MyDict.rev

Once you have built the stack, you go to the "Find" window (or hit  
command-F on a Mac) and look for "checkbox" in field "All"
and here is what you find
http://cjoint.com/?bdvgyOLyj8  (link to a snaphot)
If you are totally new, you look at all the cards except those  
obviously unrelated (database etc...)
If you know you are looking for a property, refine your search to  
"find chars" "property" in field "type" (I'll grant you this is not  
obvious)
and here is what you get
http://cjoint.com/?bdvlcL4V5u (snapshot)
which restrict your search to a dozen keywords. Clicking on a given  
of the list brings you directly to the doc.

I know I should documment this stack a little more... (which brings  
back the subject of documentation, hehe)

chers from Paris
	François

Le 3 janv. 08 à 20:40, Ken Ray a écrit :

<snip>


> Good point. In fact I attempted to find the answer to this same
> question, imagining that I was new to Rev. Here's my experience:
>
> 1) I assumed this would be documented, so I went to the online
> documentation, which if I was a first time user, would take me to the
> Getting Started screen of the docs.
>
> 2) Of the six options there, the most reasonable choice is "Using
> Objects", so I clicked that, which took me to the Tutorial Chooser.
>
> 3) I looked at the five options there to see if anything about buttons
> are mentioned, and the first one "Interface objects" mentioned  
> buttons,
> so I clicked it (although it was already highlighted), and the options
> were Download PDF or Download Video. Not sure which one should provide
> the answer, I figured I'd double-click on the line and see if there is
> a default choice.
>
> 4) Turned out there was; the video downloaded and started to play, but
> I could only hear the audio; the area of the QT player didn't redraw
> and so I couldn't figure out what was going on (must be some bug with
> my system - I hope). So I clicked Download PDF.
>
> 5) Looked a the PDF and did a search for "checkbox"; although it had a
> handful of hits, there was no help there (no scripts, just interface
> layout). So I closed that and returned to the Tutorial Chooser.
>
> 6) I looked to see if there was another tutorial that might help -
> perhaps "Properties: Customizing interface and window objects to suit
> your needs"? So I tried the video for that one (same problem as  
> before)
> and went to the PDF.
>
> 7) Opened the PDF and did a search for "checkbox" - no hits. Searches
> on "check" and "checked" (perhaps that's the property?) also resulted
> in no hits.
>
> 8) Back to the Docs - perhaps some other area of the docs? Clicked on
> "User Guide", and launched the PDF, did a search for "checkbox" -
> hooray! 14 hits!
>
> 9) Clicked through three of them to get to one where there's a line
> that states "This example sets a checkbox in the current stack to have
> the same setting as a checkbox in another stack..." and there's code
> chunks on the page - bingo! This should do it; the script goes to the
> next page, so I followed it...
>
> 10) Sure enough, there is an example of getting/setting the  
> "hilite" of
> the button.
>
> As you can see, it took me a lot of back-and-forths and dead ends  
> until
> I finally came up with the answer.
>
> Suppose I attempted to look in the Dictionary? Nope... a search for
> "checkbox" lists nothing; "check" only lists "checkmark", which isn't
> helpful. Perhaps "button"? OK, well I got a lot of results of keywords
> that apply to buttons, but I'd have to look through them one at a time
> to find the right one.
>
> How about the Glossary? I type in "checkbox" and get a hit, but  
> it's of
> course only a definition with synonyms and not properties, etc. No  
> help
> there.
>
> How about Search? After getting a notice about building databases
> (which I activate and wait until it's done), I did a search on
> "checkbox", which after a long search (took about a minute to complete
> on my MacBookPro) returned 54 related entries doing a "deep  
> search" (it
> didn't return any with a Quick search). The first item in the list is
> "autoHilite", which looks like it might be right, but it's *close* to
> what I'm looking for, although it does state when I read through it:
> "When the button is highlighted, its hilite property is also set to
> true". Bingo!
>
> OK... what did all of this tell me?
>
> 1) Search was the best way to go, but it took a long time to do a deep
> search, and I was lucky that the first item at the top of the list had
> my answer.
>
> 2) The User Guide was useful, but I went down an (understandably)  
> wrong
> path to get there. Even so, I had to extrapolate for myself that
> "hilite" was the property since it was only implicitly stated by the
> construct of the script lines and the explanation of what was going  
> on.
>
> 3) The Glossary would seem to be a good place for getting a list of
> properties of objects and perhaps adding something simple to the root
> glossary entries for the different object types would help a lot. For
> example if "button" in the Glossary had a list of properties with a
> short one-line description of each property, and clicking the prop
> would link to the proper Dictionary page, that would be a "low hanging
> fruit" benefit to the user.
>
> 4) There definitely needs to be a faster way to get to the info, at
> least for basic things like determining what token to use to turn a
> checkbox on and off.
>
> (Also, as a side note, the "Synonyms" for glossary items would make me
> thing I could use these in code somewhere, and of course I can't use
> button's or buttons' in script anywhere. BTW: What are the benefit of
> the Synonyms to the user?)
>
>> A BNF of the language would be most helpful, does one exist?  Or
>> really any complete language reference.
>
> Well, there's a BNF of HyperTalk
> (http://www.jaedworks.com/hypercard/scripts/hypertalk-bnf.html), which
> was the first xTalk language, several generations before Revolution -
> it might help in the interim.
>
>> Is there a message reference?  In the video about how to find
>> information, it shows (what seems to be) pre-2.8.1 documentation, and
>> just from the short clip, it looks like this documentation could help
>> somewhat (there was a short clip of a message reference too).  After
>> my open/closeStack default message passing incident,  I feel a sudden
>> need to know every message.
>
> See my comment about the scripting conference stacks above.
>
>> And just now, my variable watch window decided to not show most
>> variables.  Instead, it shows the variable names in the values.
>
> This happens when a variable has been used, but has not been  
> defined to
> hold any value. This is because of Revolution's ability to coerce one
> thing into another without having to apply types to it, and sometimes
> without even providing quote marks.
>
> For example, "put Ken into field 1" will put the string "Ken" into
> field 1 unless it has been declared as a variable with the "local" or
> "global" command, or if it has been assigned a value:
>
>    put 10 into Ken
>    put Ken into field 1
>
> ... will put 10 into field 1.
>
> Hope this helps,
>
> Ken Ray
> Sons of Thunder Software, Inc.
> Email: kray at sonsothunder.com
> Web Site: http://www.sonsothunder.com/
> _______________________________________________
> use-revolution mailing list
> use-revolution at lists.runrev.com
> Please visit this url to subscribe, unsubscribe and manage your  
> subscription preferences:
> http://lists.runrev.com/mailman/listinfo/use-revolution