Re: [MacPerl] installing libraries in mac perl

[Matthew Langford <langfml [at] eng [dot] auburn [dot] edu>]

On Tue, 19 Oct 1999, Brian McNett wrote:

> > In brief, the following should work on most systems:
>                                          ^^^^
> "Most" systems in the context the author of this document is refering to 
> means "most UNIX" systems.  This is generally well understood within the 
> community of unix users
> 
> That being said, I second Chris' comments regarding the not-entirely-unix 
> nature of this README.  In particular it contains information relative to 
> both GPL and the Perl Artistic License, that all Perl programmers need to 
> be aware of.  

I have to agree with the first poster (robinmcf).  The MacPerl docs are
reassuring for those coming from Unix backgrounds, but not entirely
applicable to Macs.  Why not put in (or take other people's rewrites)
customized documents specifically for MacPerl.  

What about the Mac documents already present?  They're fine, but they
could be merged into a comprehensive doc set.  It may seem a minor fault
to include too much information, until you are the one trying to figure
out what's relevant (and getting annoyed by useless streams of unnecessary
or inapplicable info).  For example, when I work on my car, it annoys me
to separate all the stuff for the different engine sizes, model
variations, carburetor vs. fuel injection, and so on.  The same thing
happens with MacPerl, often.  To some extent it may be necessary for
modules.  For the core distribution, though, we can do better.

How hard would it be to strip the stuff after
"Please read all the directions below before you proceed any further, and
then follow them carefully."

until 

"Just a personal note".

That's the platform independent stuff.  Then, package that in the same
file as README.Mac--probably toward the end of it, perhaps even with a
heading saying it was from the original, non-ported distribution.  Bam.
One file.  IMHO, the readme need not include revision history; separate
that into a separate file.  Then, back in the Readme, put a short
description about the help resources--you can access many PODs straight
from the Help menu, you can drag any .PM module onto Shuck to read
internal documentation, and you should be able to double-click or
drag-and-drop any POD file in the pod directory (which is the help
directory for newbies).

Again, IMHO, I would put MacPerl.Packages, MacPerl.Specifics,
MANIFEST.appl in a separate MacPerl Specifics folder.

Parts of MacPerl.Frontend could also be incorporated into the Readme (eg
the help stuff I mentioned above), and the more involved technical stuff
(eg AppleScript details, anything beyond newbie info) into a file inside
the MacPerl Specifics folder.

As I look at my installation, this would leave just the applications,
their help files, the _one_ Readme, and the License in the main folder
(besides sub-folders). Clean and simple.  Furthermore, the Readme would
point people in the necessary direction for more information: PODs and the
Help menu.  _After_ these are mentioned, a pointer to these mailing lists,
MacPerl.com, and the MPPE would be nice.

In addition, I would package Chris Nandor's excellent [un]tarzipme.plx,
installme.plx, and CPAN-shell.plx (with a note in the Readme about
memory guidelines for using these).  I would also bundle RuntimeBuilder.
These could go in MacPerl Scripts (what's that for?) or "macscripts"
(what's that for, and how's it different from "MacPerl Scripts"?).

While I'm on the soapbox, does it bother anyone else the "MacPerl
Overview" is not MacPerl's overview, but really a "Perl Overview"?


I understand that it is much easier to just bundle all the original files,
and put in a note to disregard all the Unixisms, but it is far better to
do some simple modifications to the documentation.  After all, you change
the source to match the platform, why not tailor the documentation?  The
good thing is, the documentation changes far more slowly, so a one-time
change may last a long time.


> I don't see this as an immediate or pressing concern.  You're arguing 
> straw men here.

You probably are coming at this from a Unix mindset (and you probably care
very little about the documentation, anyway).  MacPerl, as it is currently
distributed, shouts "port" and "Unix".  Nothing wrong with that, but a
little bit of documentation polish would improve the newbie experience a
great deal.  And _that_ is very Mac-like.


--
MattLangford 




# ===== Want to unsubscribe from this list?
# ===== Send mail with body "unsubscribe" to macperl-request@macperl.org