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 [email protected]


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 [email protected]


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.