Re: Standard Additions documentation
Re: Standard Additions documentation
- Subject: Re: Standard Additions documentation
- From: John Baltutis <email@hidden>
- Date: Sat, 20 Dec 2008 15:55:45 -0800
On 12/20/08, Chris Page <email@hidden> wrote:
>
> Terminology dictionaries are intended for the computer to compile and
> decompile scripts, and to provide a quick-reference for humans. The
> AppleScript Language Guide is intended to describe the language
> generally, including how ìmakeî works and what a ìclassî is. There's a
> Help menu item in Script Editor that takes you to the ASLG. The ASLG
> includes a section documenting the Standard Addition commands in
> greater detail than in the dictionary:
>
><http://developer.apple.com/documentation/AppleScript/Conceptual/AppleScriptLangGuide/reference/ASLR_cmds.html#//apple_ref/doc/uid/TP40000983-CH216-DontLinkElementID_723 >
>
> Mac OS X ships with a number of scripts that we hope serve as
> examples. There's an alias adjacent to Script Editor that points to
> them, ì/Applications/AppleScript/Example Scripts/î.
>
> The ìdo shell scriptî dictionary entry points at a web page with a
> detailed discussion of the command, with examples.
>
> I suppose we should think about updating the Standard Additions
> dictionary to pick up the revised reference documentation from the
> ASLG, but I'm hesitant to attempt to fill dictionaries with more than
> quick-reference information.
>
> If we added links within the dictionary to the ASLG, would that help?
Yes
> Would anybody notice and follow them? (Has anybody noticed and
> followed the one for ìdo shell scriptî?)
Yes
****
I'm a lurker here, have onlycreated some basic AS scripts which I use on my
single-user machine, have some familiarity with scripting, but don't script
often enough to remember all the nuances, so I'm forced into revisiting the
dictionaries for the details. Forme and I suspect most newcomers to AS, there
are many inconsistencies and counterintuitive descriptions in the various
libraries and in the other documentation, such as the ASLG.
For example, since you brought up the 'do shell script' command, below are just
some questions I have:
StandardAdditions.sdef
do shell script v : Execute a shell script or command using the 'sh' shell
do shell script text : the command or shell script to execute. Examples are
'ls' or '/bin/ps -auxwww'
[as type class] : the desired type of result; default is text (UTF-8)
[administrator privileges boolean] : execute the command as the administrator
[user name text] : use this administrator account to avoid a password dialog
(If this parameter is specified, the "password" parameter must also be
specified.)
[password text] : use this administrator password to avoid a password dialog
[altering line endings boolean] : change all line endings to Mac-style and trim
a trailing one (default true)
->text : the command output
The dictionary examples are simplistic because they only show the basic command
and no options. The only generic Tech Note example covering most, but not all
options and not in the same order above (which is confusing), is:
do shell script "command" user name "me" password "mypassword" with
administrator privileges
There's a disparity between the examples in the sdef do shell script text
section where single quotes are used andthe TechNote example where double
quotes are used. Which is it? Can either beused? If so, then explain or add the
double quote examples. If not, fix the inconsistency. For newbies and me, this
kind of thing is confusing and counterintuitive.
Next, where did the with part come from in with administrator privileges? Why
does it come after username and password? Neither is documented and is
inconsistent.
Where's the example showing explicitly how to incorporate the [as type class]
and [altering line endings boolean] options? Are they simply added in the
relative positions as noted in the sdef orare there other subtle differences as
noted in the above generic example?
What other type classes are permitted in the 'as' option and what's the format?
AFAICT, text is the only appropriate class. What's really meant here? Could it
be UTF-16, vice UTF-8? If so, how is that entered? As UTF-16, (UTF-16), or some
other variant? The text class in your linked document doesn't say.
This is just one example of one command from one dictionary. IMO, every
dictionary should have a generic example for each command that includes every
option so there's no guesswork on what the proper syntax one should be using
when constructing scripts. Then, for completeness, include a link to the ASLG
for more detail.
_______________________________________________
Do not post admin requests to the list. They will be ignored.
AppleScript-Users mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
Archives: http://lists.apple.com/archives/applescript-users
This email sent to email@hidden