Re: [MacPerl] Q: documentation how to

[Chris Nandor <pudge@pobox.com>]

At 08.44 -0400 1998.10.14, Xah Lee wrote:
>In unix, one can do "perldoc -f xxx" to get the docs for xxx. Similarly, with
>cmd-l in Shuck on the mac.
>
>I'm writing a module with docs embeded. What is the standard practice so that
>users can also do -f or cmd-l to lookup my functions?

There isn't one, in either case.

First, the -f flag for perldoc only works for functions in the perlfunc
manpage.  What WILL work is that when the module is installed with
make;make test;make install, people will be able to view your documentation
with:

  perldoc YourModule

or:

  man YourModule

if man and perldoc are working properly.

For Shuck, the only way to get Cmd-l to do a lookup for your module is if
you edit the MacPerl Help document to include your module, which is
probably not a good idea, though that may be for you to decide.

You could have the user run something like:

  #!perl -w
  use DB_File;
  tie %h, 'DB_File', "$ENV{MACPERL}MacPerl Help", O_RDWR, 0644 or die $!;
  $h{'My::Module::Name'} = 'pod:site_perl/My/Module/Name.pm';
                                # relative path to module, probably this
                                # will work

This is NOT recommended, however, as you don't want to go messing with the
Help file, get it cluttered, or whatever.

This is a program I wrote some time ago that is does find any module
installed, even if it is not in the MacPerl Help file; the drawback is that
it actually executes module files it finds.

I recently edited this, though, to not die if the module file does not
compile.  So do $file executes the file, but whether or not it executes
successfully is not relevant; we just check %INC to see if it is there or
not.

#!perl
# macperldoc a.k.a. perldoc/2
# requires IC setup to use Shuck for pod URLs
use strict;
my($what, $why, $where, $ic, %help);

$what = MacPerl::Ask('What do YOU want?') or exit;
($why = $what) =~ s|::|/|g; $why .= '.pm';
do $why;

if (exists($INC{$why})) {
  $where = $INC{$why};
} elsif (-e "$ENV{MACPERL}pod:$what.pod") {
  $where = "$ENV{MACPERL}pod:$what.pod";
} else {
  require DB_File;
  require Fcntl;
  tie(%help, 'DB_File', "$ENV{MACPERL}MacPerl Help",
    Fcntl::O_RDONLY(), 0) or die $!;
  if (defined($help{$what})) {
    ($where = $help{$what}) =~ s|^pod:|$ENV{MACPERL}|;
    $where =~ tr|/|:|;
  }
}

if (!$where) {
  MacPerl::Answer("Cannot find $what.");
  exit;
} else {
  require Mac::InternetConfig;
  Mac::InternetConfig->import();
  $ic = ICStart();
  ICGeneralFindConfigFile($ic);
  ICLaunchURL($ic, 0, "pod:///$where");
  ICStop($ic);
}
__END__

--
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 mac-perl-request@iis.ee.ethz.ch