From:	Xiong	Date:	Sun Jul  8 19:57:15 2007
Subject:	use Mac::Files, Mac::MoreFiles;

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
xiong@mochamail.com

You must be the change you want to see in the world.
   -- Mahatma Gandhi