Re: [MacPerl-Porters] [ macperl-Bugs-486790 ] Shuck file problems

On Sat, 1 Dec 2001, Chris Nandor wrote:

> At 13:14 +0000 2001.12.01, Peter Prymmer wrote:
> >Apparently, as Thomas has pointed out, the "MacPerl.podhelp" index file
> >would need to be updated then the "BuildHelpIndex" script would need to be
> >run.
>
> Not really.  The MacPerl Help file is a DB file; you can manipulate it
> directly with DB_File (which is what I've done in the past).  Something
> like:
>
> 	$dbm{'My::Module'} = 'pod:site_perl/My/Module.pm';
>
> I might have the syntax off by a bit.

OK, that sounds easier than what I thought would be necessary.

> >The appending of the information to perllocal.pod typically
> >gets done my your make utility as part of the `make install` build target,
> >hence the appendage to perllocal.pod should apparently be added to
> >ExtUtils::MM_MacOS.pm.  I wonder: would it hurt the index to have
> >"MacPerl.podhelp" updated to "add" perllocal.pod each time a module has
> >`BuildProgram install` run?
>
> Probably adding to perllocal.pod and adding to MacPerl Help would be in
> order.  Patches welcome, of course.  :-)  The problem is that the "make
> install" process is kinda weird.  It can work, though.  See
> Mac::BuildTools::make_install().  I am not sure offhand where and how it
> happens on Unix.

Perhaps all that needs to take place is the appending of an entry in
perllocal.pod.  I wouldn't think too much (if anything at all) needs
to be added to the MacPerl Help.  Once the index had an entry for
perllocal.pod that should suffice.  It wouldn't necessarily need to point
to all the pods for the additional CPAN modules modules that eventually
get installed.  Note that on Unix perllocal.pod merely list the package
name and version and does not attempt to L<link> to the installed pod.

If you are interested in looking at how it happens on Unix then look
at :lib:ExtUtils:MM_Unix.pm.  Inside the install() sub there is a
doc_perl_install target and a doc_site_install target that append lib and
exe entries to perllocal.pod.

> >One would need to ensure that one entry only
> >is made for perllocal.pod but that could be arranged with a hash of
> >"MacPerl.podhelp" pod document names for keeping track of the uniq ones.
>
> I didn't think it bothered to check for unique entries in perllocal.pod on
> Unix.

I think you misunderstood my statement.  I was referring to uniqueness of
the entries in MacPerl.podhelp with one unique one pointing to
perllocal.pod.  I was not trying to say anything about the uniqueness of
entries within the perllocal.pod document itself.  Indeed if you upgrade a
module on Unix you will see that the upgrade simply appends info to
perllocal.pod and the info from the previously installed version is still
there.  Hence one must read perllocal.pod from top to bottom to glean the
list of modules and their versions that are currently installed.

Appently the DB_File entries will be hashed in a unique way - meaning no
redundant entries.

> >Also: would any harm come from running "BuildHelpIndex" for each module
> >that is installed?
>
> It's unnecessary.  Also, it might produce unpredictable results, since I am
> not sure if it is designed to be re-run.  As noted, I don't think it's
> necessary, though.

OK.

> >If there is harm then perhaps a stub for an empty
> >perllocal.pod could be left in place as part of the installation of Perl.
>
> I think both adding perllocal.pod as a stub, and adding to it on install,
> and adding entries with DB_File on install to MacPerl Help, are all in
> order.

I follow you with the adding to perllocal.pod on install, but I am not
sure what you mean by the DB_File entries here.

Peter Prymmer