README for Mac::RecentDocuments
                                        Time-stamp: "2000-10-12 17:07:29 MDT"

NAME
     Mac::RecentDocuments -- add items to the MacOS Recent Documents menu

SYNOPSIS
       use Mac::RecentDocuments qw(:ARGV);
        # Adds all files in @ARGV to Recent Documents folder,
        #  and imports recent_documents and recent_document

       foreach my $in (@ARGV) {
         open(IN, "<$in") or die "Can't read-open $in: $!";
         my $out = $in . '2';
         die "But $out already exists!" if -e $out;
         open(OUT, ">$out") or die "Can't write-open $out: $!";

         ...do whatever to $out...

         recent_documents($out); # add to Recent Documents folder
       }

DESCRIPTION
     This module provides a function that adds specified files to
     the MacOS Apple Menu "Recent Documents" folder.  You can use
     this module under non-MacOS environments, and it will
     compile, but it will do nothing.

FUNCTIONS
     recent_documents( ...files... )
          This adds the given items to the Recent Documents
          folder, for each item that is a pathspec to an existing
          file. Relative (":bar.txt") as well as absolute
          filespecs ("Lame Drive:stuff:bar.txt") should work
          equally well.

          The number of aliases that this creates in the Recent
          Documents folder is returned.

          Under non-MacOS environments, this function does
          nothing at all, and always returns 0.

     recent_document( file )
          This is just an alias to recent_documents

     Mac::RecentDocuments::OK()
          This function returns true iff you are running under
          MacOS, and if, at compile-time, Mac::RecentDocuments
          was able to find your Recent Documents folder, and
          verified that it was a writeable directory.  In all
          other cases, this returns false.

IMPORTING, AND :ARGV

     If you say

       use Mac::RecentDocuments;

     then this will by default import the functions
     recent_documents and recent_document.

     This is equivalent to:

       use Mac::RecentDocuments qw(:all);

     If you want to use the module but import no functions, you
     can say:

       use Mac::RecentDocuments ();

     or

       use Mac::RecentDocuments qw(:none);

     This module also defines a use-option ":ARGV" that causes
     Mac::RecentDocuments to also call recent_documents(@ARGV),
     at compile time.  This should be rather useful with MacPerl
     droplets.

     That is, this:

       use Mac::RecentDocuments qw(:ARGV);

     is basically equivalent to:

       BEGIN {
         use Mac::RecentDocuments;
         Mac::RecentDocuments(@ARGV);
       }

     (The only difference is that if several instances of use
     Mac::RecentDocuments qw(:ARGV) are seen in a given session,
     Mac::RecentDocuments(@ARGV) is called only the first time.)

     When "qw(:ARGV)" is the whole option list, it is interpreted
     as equivalent to "qw(:ARGV :all)".  If you want the :ARGV
     option without importing anything, explicitly specify the
     ":none" option:

       use Mac::RecentDocuments qw(:ARGV :none);

CAVEAT
     The module is called Mac::RecentDocuments (no underscore),
     but the function is called recent_documents (with
     underscore).

     The module is called Mac::RecentDocuments, not Mac::RecentFiles.

THANKS
     Thanks to Chris Nandor for the kRecentDocumentsFolderType
     tips.

COPYRIGHT
     Copyright (c) 2000 Sean M. Burke. All rights reserved.

     This library is free software; you can redistribute it
     and/or modify it under the same terms as Perl itself.

AUTHOR
     Sean M. Burke sburke@cpan.org


PREREQUISITES

This suite requires Perl 5; I've only used it under Perl 5.004, so for
anything lower, you're on your own.

Mac::RecentDocuments doesn't use any nonstandard modules.


MACPERL INSTALLATION NOTES

Don't bother with the makefiles.  Just make a Mac directory in your
MacPerl site_lib or lib directory, and move RecentDocuments.pm into there.


INSTALLATION

You install Mac::RecentDocuments, as you would install any perl module
library, by running these commands:

   perl Makefile.PL
   make
   make test
   make install

If you want to install a private copy of Mac::RecentDocuments in your home
directory, then you should try to produce the initial Makefile with
something like this command:

  perl Makefile.PL LIB=~/perl


DOCUMENTATION

POD-format documentation is included in ISA.pm.  POD is readable with
the 'perldoc' utility or the Shuck program under MacOS.  See ChangeLog
for recent changes.


SUPPORT

Questions, bug reports, useful code bits, and suggestions for
Mac::RecentDocuments should just be sent to me at sburke@cpan.org


AVAILABILITY

The latest version of Mac::RecentDocuments is available from the
Comprehensive Perl Archive Network (CPAN).  Visit
<http://www.perl.com/CPAN/> to find a CPAN site near you.