Re: on the lack of documentation (was: Re: on neophytes vs perfectionists)
Re: on the lack of documentation (was: Re: on neophytes vs perfectionists)
- Subject: Re: on the lack of documentation (was: Re: on neophytes vs perfectionists)
- From: "Mark J. Reed" <email@hidden>
- Date: Sat, 20 Dec 2008 02:16:06 -0500
On Sat, Dec 20, 2008 at 1:18 AM, Shane Stanley
<email@hidden> wrote:
> Perhaps not so much hard to find as hard to fathom without some background
> in shell scripting. I'm not saying they're worse than AS dictionaries, just
> that they're not something I'd hold up as a shining example. I get the
> impression that the aim of many is to be as terse as possible, often at the
> expense of helpfulness.
I'm not going to hold up man pages as a shining example - they're at
best tarnished - but they do seem to be better than most of what you
get for AppleScriptable apps. There are exceptions, of course. And
the new ASLG means that AppleScript itself is much better documented
than it used to be (unless you count Matt's book as documentation.
:))/.
>> Most man pages include an EXAMPLES section, which alone goes a long way.
>
> I have no idea about most, but a quick check of cp, mv, rm, ls doesn't turn
> up an examples section between them.
You're right, there aren't many EXAMPLES sections. I very much
overstated, probably due to recent perldoc perusal (CPAN modules have
perldoc pages that are patterned after man pages and often stored in
the same directories, and they're more likely to have examples
sections).
It does seem that many of the man pages that describe complex or just
relatively-recent commands have EXAMPLES sections on Linux; the common
OS X commands, not so much. But I see that both the BSD and GNU "tar"
pages have an EXAMPLES section.
I suppose the "usage" bit at the top of the man page is probably
considered enough of an example for straightforward commands like cp,
where a typical example is just "cp source_file target_file". But
getting that far does require one bit of "insider" knowledge, which is
that the stuff in square brackets in between the "cp" and the
"source_file" is all optional.
>
>
> --
> Shane Stanley <email@hidden>
> AppleScript Pro Florida, April 2009 <http://scriptingmatters.com/aspro>
>
>
> _______________________________________________
> 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
>
--
Mark J. Reed <email@hidden>
_______________________________________________
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