Glad to see traffic on the list!
Is it just me or are the docs for Mac::Files and Mac::MoreFiles
hopelessly obscure? Example:
FSpDirectoryCopy fails (a) when attempting to copy over an existing
folder -- as expected but without calling COPYERRHANDLER as
advertised; and (b) when attempting to copy a very large folder --
unexpectedly. I'd like to know more.
This is the Shuck for this routine:
* * *
FSpDirectoryCopy SRCSPEC, DSTSPEC, PREFLIGHT, [COPYERRHANDLER]
Make a copy of a directory structure in a new location. The
FSpDirectoryCopy function makes a copy of a directory structure in a
new location. COPYERRHANDLER is the Perl routine name to handle an
error, should one arise. It will be called as:
$bailout = &$COPYERRHANDLER(ERRORCODE,OPERATION,SRCSPEC,DSTSPEC);
* * *
What is PREFLIGHT? What is $bailout? What is OPERATION? What,
*exactly*, are the permissible values of SRCSPEC and DSTSPEC? What
must I do to make COPYERRHANDLER work? What obscure little bit of
magic is implied by &$COPYERRHANDLER? Where would I go to find a
table of ERRORCODEs? (I know, Inside Macintosh, right?)
There doesn't seem to be any more info, anywhere. Call me an old fart
but I started programming in a world where there was a page or
several on every word ever used anywhere *in* the manual. This makes
for big manuals, since, well, every page has many words on it -- but
eventually the writer starts to reuse words and so the size is
finite. There's also a problem of circular reference but patience and
experience is usually enough to catch the drift of what's being said.
With every term defined, nothing is left to chance.
The MacPerl stuff seems particularly poorly documented but I find the
problem across the world of Perl. All the docs seem to assume that
you already know what they're about to say; they're just handy to jog
your memory. Where is:
* * *
THING
Thing does *this*. It accepts /foo/ and /bar/ as inputs and produces
/baz/. Thing requires this, this, and this. It fails if this or that.
The exact format of /baz/ is:
bip bip bip bip boo
FOO
Foo is a data structure of type /gimble/. Its contents are explained
in this long, exhaustive table in which every key and field is
listed, the types of every element of the structure, the permissible
values.
. . . . .
* * *
Perl docs seem to breeze through it all with:
$baz = Thing (foo, bar);
-- and a 3-line explanation. It's like the blonde's cocktail dress --
it looks very nice but it doesn't quite cover the subject.
--
Xiong Changnian
[EMAIL PROTECTED]
You must be the change you want to see in the world.
-- Mahatma Gandhi
