Mailing List Archive

On Sun, 8 Oct 1995, Tom Christiansen wrote:

> > Followup: Yes, Configure now includes man3ext, and installman3dir. I'm in
> > the process of adding support to MakeMaker to install appropriate pods in
> > the named location.
>
> Thank you VERY much.

No problem. I was meaning to do it once Configure was ready, and
Configure finally was ready.

Apply this patch in lib/ExtUtils over perl5.001m + Andy's Jumbo Configure
patch. Once in place, MakeMaker will take a new MANPODS argument, which is
a hash listing source and targets to be pod2manified. The default is any
.pod files in PM, and and .pm files from PM that contain =head?
directives. ReadKey.pm will be installed as Term::ReadKey.pm by default,
for example.

Tom, you can tell Configure that you want your modules pages in
/usr/local/man/man3, and the extension should be 3pm, and you should get
what you're aiming for.

Note that if Configure overrides the module installation path to "none"
for any reason, then no installation will be done at all, MM override or
not. Configure will do this on systems limited to 14 character filenames,
among other things.

There is one subtle bit of magic. If more then one pod file is detected,
then _any_ pod files that look like "setup.pm" or "config.pm" or
"installation.pm" will _not_ get installed as man files. Term::ReadKey
includes "Configure.pm" which is complex enough to contain documentation,
but is not intended to be installed or manified. It's easy to imagine
other packages containing similar installation aids.


Andreas K., you may want to modify it a bit to be more in keeping with
MakeMaker style, though it seems decent as-is.


Andy D., there is one section in Configure that isn't quite right as-is:

case "$nroff" in
nroff)
$cat <<'EOM'
However, you don't have nroff, so they're probably useless to you.
You can use the supplied perldoc script instead.
EOM
case "$man3dir" in
'') man3dir="none";;
esac;;
esac

While well intentioned, this missed the point that perldoc uses pod2man
and nroff. Eventually when the new POD tools get finished, this will be
changed, but for now it is the case.

*** MakeMaker.pm.save Mon Oct 9 00:08:09 1995
--- MakeMaker.pm Mon Oct 9 03:00:04 1995
***************
*** 170,173 ****
--- 170,178 ----
The .c files will automatically be included in the list
of files deleted by a make clean.
+
+ MANPODS: Hashref of .pm and .pod files. MakeMaker will default this
+ to all .pod and any .pm files that include POD directives. The
+ files listed here will be converted to man pages and installed
+ as was requested at Configure time.

C: Ref to array of *.c file names. Initialised from a directory scan
***************
*** 258,261 ****
--- 263,267 ----
'static_lib' => {},
'installpm' => {},
+ 'manifypods'=> {},
'processPL' => {},
'installbin' => {},
***************
*** 713,716 ****
--- 719,726 ----
$att{INSTALLARCHLIB} ||= $Config{'installarchlib'};
$att{INSTALLBIN} ||= $Config{'installbin'};
+ $att{INSTALLMAN1DIR} ||= $Config{'installman1dir'};
+ $att{INSTALLMAN3DIR} ||= $Config{'installman3dir'};
+ $att{MAN1EXT} ||= $Config{'man1ext'};
+ $att{MAN3EXT} ||= $Config{'man3ext'};

$att{MAP_TARGET} = "perl" unless $att{MAP_TARGET};
***************
*** 753,757 ****
sub init_dirscan { # --- File and Directory Lists (.xs .pm .pod etc)

! my($name, %dir, %xs, %c, %h, %ignore, %pl_files);
local(%pm); #the sub in find() has to see this hash
$ignore{'test.pl'} = 1;
--- 763,767 ----
sub init_dirscan { # --- File and Directory Lists (.xs .pm .pod etc)

! my($name, %dir, %xs, %c, %h, %ignore, %pl_files, %manifypods);
local(%pm); #the sub in find() has to see this hash
$ignore{'test.pl'} = 1;
***************
*** 837,840 ****
--- 847,899 ----
$att{H} = [sort keys %h] unless $att{H};
$att{PL_FILES} = \%pl_files unless $att{PL_FILES};
+
+
+ # Set up names of manual pages to generate from pods
+
+ foreach $name (keys %{$att{PM}}) {
+ if ($name =~ /\.pod$/ ) {
+ $manifypods{$name} = $att{ROOTEXT}.'/'.$`;
+ } elsif ($name =~ /\.p[ml]$/ ) {
+ local(*TESTPOD);
+ my($ispod)=0;
+ open(TESTPOD,"<$name");
+ while(<TESTPOD>) {
+ if(/^=head/) { $ispod=1; last}
+ #Speculation on the future:
+ #if(/^=don't\S+install/) { $ispod=0; last}
+ }
+ close(TESTPOD);
+
+ $name =~ /\.p[ml]$/;
+
+ if( $ispod ) {
+ $manifypods{$name} = $att{ROOTEXT}.'/'.$`;
+ }
+ }
+ }
+
+ # Remove "Configure.pm" and similar, if it's not the only pod listed
+ # To force inclusion, just name it "Configure.pod", or override MANPODS
+ if( scalar(keys %manifypods) > 1) {
+ foreach $name (keys %manifypods) {
+ if ($name =~ /(config|install)(ur(er?|ation))|setup\.pm/i) {
+ delete $manifypods{$name};
+ }
+ }
+ }
+
+ foreach $name (keys %manifypods) {
+ $manifypods{$name} =~ s,^/+,,; # Strip leading slashes
+ $manifypods{$name} =~ s,/,::,g; # Turn other slashes into colons
+ $manifypods{$name} = "\$(INST_MAN3)/$manifypods{$name}.\$(MAN3EXT)";
+ }
+
+
+ $att{MANPODS} = \%manifypods unless $att{MANPODS};
+
+ # Configure overrides anything else
+ if( $att{INSTALLMAN3DIR} eq "none" ) {
+ $att{MANPODS} = {};
+ }
}

***************
*** 1049,1052 ****
--- 1108,1119 ----
O_FILES = ".join(" \\\n\t", @{$att{O_FILES}})."
H_FILES = ".join(" \\\n\t", @{$att{H}})."
+ MAN_FILES = ".join(" \\\n\t", sort keys %{$att{MANPODS}})."
+
+ # Man installation stuff:
+ INST_MAN1 = $att{INSTALLMAN1DIR}
+ INST_MAN3 = $att{INSTALLMAN3DIR}
+ MAN1EXT = $att{MAN1EXT}
+ MAN3EXT = $att{MAN3EXT}
+

.SUFFIXES: .xs
***************
*** 1556,1559 ****
--- 1623,1644 ----
}

+ sub manifypods {
+ my($self, %attribs) = @_;
+ my($dist);
+ return '' if scalar(keys %{$att{MANPODS}})==0;
+ my(@m) = "\nmanifypods :";
+ foreach $dist (sort keys %{$att{MANPODS}}) {
+ my($inst) = %{$att{MANPODS}}->{$dist};
+ push(@m," $dist");
+ }
+ push(@m,"\n");
+ foreach $dist (sort keys %{$att{MANPODS}}) {
+ my($inst) = %{$att{MANPODS}}->{$dist};
+ push(@m,"\tpod2man $dist > $inst\n");
+ push(@m,"\t\$(CHMOD) 644 $inst\n");
+ }
+ join('', @m);
+ }
+

sub installpm {
***************
*** 1890,1893 ****
--- 1975,1983 ----
'EXE_FILES=$(EXE_FILES)')" >> $(INSTALLARCHLIB)/perllocal.pod
};
+
+ push @m, q{
+ doc_install :: manifypods
+
+ } if scalar(keys %{$att{MANPODS}})!=0;

push(@m, "


--
Kenneth Albanowski (kjahds@kjahds.com, CIS: 70705,126)