At 16:21 -0500 1999.10.19, Matthew Langford wrote: >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. We already have. >What about the Mac documents already present? They're fine, but they >could be merged into a comprehensive doc set. They are. >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". First, I don't see a problem. If you cannot read "DISREGARD THE INSTALLATION INSTRUCTIONS BELOW" then you can't follow the (inappropriate) installation instructions that follow. >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. I do not like, at all, the idea of changing docs. A note at the top of the docs is the only change I would ever make to the README. I think anything else is bad form. However, a README.orig could be made or something. But again, I just don't see the significant need. It is all very clear to anyone who is willing to read even a little bit. >IMHO, the readme need not include revision history; separate >that into a separate file. I don't care either way. Yes, the docs could be fixed up a bit, and I hope to do it or get someone to do it. But this does not speak to what Robin was saying, from what I can tell, which was separating the docs to Unix and Mac, which for the most part is entirely inappropriate. Aside from the README, perlport.pod (not included with MacPerl now, included with perl5.004_05 and up) is the "don't do this on a Mac" document. There is stuff in the various Perl docs that are possibly wrong on the Mac. I think it is wrong to change them, though. That is what perlport is for. >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. I don't really care how it is done specifically, but yes, the docs can be fixed up (I think they should almost all, if not all, be POD, and cleaned up, collated, etc.) and I personally move them to a Docs 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. We could include Mac OS 8 bookmark clippings files. :D >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"?). MacPerl Scripts is for the Script menu. But yes, I would like to bundle all of cpan-mac. RuntimeBuilder is a good idea, too. >While I'm on the soapbox, does it bother anyone else the "MacPerl >Overview" is not MacPerl's overview, but really a "Perl Overview"? Yeah, probably. >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. Unless I have already convinced you otherwise :), do you have any thoughts aside from the README of what should be changed? Give some examples, please. -- Chris Nandor mailto:pudge@pobox.com http://pudge.net/ %PGPKey = ('B76E72AD', [1024, '0824090B CE73CA10 1FF77F13 8180B6B6']) # ===== Want to unsubscribe from this list? # ===== Send mail with body "unsubscribe" to macperl-request@macperl.org