Mailing List Archive: bad pods

bad pods

Nov 6, 1995, 3:03 PM

Post #1 of 7 (742 views)

Oh darn it. I think I better go and hack on installman....

$ makewhatis: processing man tree /usr/local/lib/perl5/man...
ExtUtils::Liblist.3: no NAME lines, so has no whatis description!
ExtUtils::Mkbootstrap.3: no NAME lines, so has no whatis description!
ExtUtils::Miniperl.3: no NAME lines, so has no whatis description!
Math::BigFloat.3: no NAME lines, so has no whatis description!
Math::BigInt.3: no NAME lines, so has no whatis description!
Math::Complex.3: no NAME lines, so has no whatis description!
Search::Dict.3: no NAME lines, so has no whatis description!
Shell.3: no NAME lines, so has no whatis description!
SubstrHash.3: no NAME lines, so has no whatis description!
Sys::Hostname.3: no NAME lines, so has no whatis description!
Sys::Syslog.3: no NAME lines, so has no whatis description!
Term::Cap.3: no NAME lines, so has no whatis description!
Term::Complete.3: no NAME lines, so has no whatis description!
Test::Harness.3: no NAME lines, so has no whatis description!
Text::ParseWords.3: no NAME lines, so has no whatis description!
Text::Soundex.3: no NAME lines, so has no whatis description!
Text::Tabs.3: no NAME lines, so has no whatis description!
TieHash.3: no NAME lines, so has no whatis description!
Time::Local.3: no NAME lines, so has no whatis description!
Exporter.3: no NAME lines, so has no whatis description!
NDBM_File.3: no NAME lines, so has no whatis description!
ODBM_File.3: no NAME lines, so has no whatis description!

Tom Christiansen Perl Consultant, Gamer, Hiker tchrist@mox.perl.com

"Don't let it get to you. Shout happens." --Larry Wall

Re: bad pods [ In reply to ]

doughera at lafcol

Nov 6, 1995, 3:07 PM

Post #2 of 7 (707 views)

Permalink

On Mon, 6 Nov 1995, Tom Christiansen wrote:

> Oh darn it. I think I better go and hack on installman....
>
> $ makewhatis: processing man tree /usr/local/lib/perl5/man...
> ExtUtils::Liblist.3: no NAME lines, so has no whatis description!
...

Are you proposing not installing man pages just because they don't have
a NAME line? I think the time would be better spent fixing the .pm
files.

Andy Dougherty doughera@lafcol.lafayette.edu

Re: bad pods [ In reply to ]

tchrist at mox

Nov 6, 1995, 3:20 PM

Post #3 of 7 (702 views)

Permalink

>> Oh darn it. I think I better go and hack on installman....
>> $ makewhatis: processing man tree /usr/local/lib/perl5/man...
>> ExtUtils::Liblist.3: no NAME lines, so has no whatis description!
>...

>Are you proposing not installing man pages just because they don't have
>a NAME line? I think the time would be better spent fixing the .pm
>files.

Mais non!

The problem is that some of these don't have pod directives at all,
and it installs empty files!

I suggest something like this be done:

open (MOD, "< $mod") || die "can't open $mod: $!";
local $/ = '';
while (<MOD>) {
if (/^=head1\s+\S/) {
close MOD;
cmd("$pod2man $mod > $manpage");
next POD_
last POD_SEARCH
}
}
warn "$0: No documentation in module $mod";

I don't mind scolding for missing docs.

Also, I notice that I got

/usr/local/man/man1/perlrun.1
/usr/local/lib/perl/man/man3/Fcntl.3

I don't think these should be in different place.

All I typed, btw, was

./configure
make
make test
make install

Hm... any word on the DB_File coredump?

--tom

Re: bad pods [ In reply to ]

rjray at lookout

Nov 6, 1995, 3:41 PM

Post #4 of 7 (698 views)

Permalink

>Also, I notice that I got
>
> /usr/local/man/man1/perlrun.1
> /usr/local/lib/perl/man/man3/Fcntl.3
>
>I don't think these should be in different place.
>
>All I typed, btw, was
>
> ./configure
> make
> make test
> make install

I don't have any real heartburn with the disparate locales of these. Somewhere
in the docs (perlmods, I think) it tells the user that to see the docs for
the modules, add "/usr/local/lib/perl/man" to MANPATH. I have, and I can read
them without worrying about where they are. I don't like a lot of stuff
cluttering up man/man3 on my system, so I can live with this. IMHO, of course.

Randy
--
^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^
Randy J. Ray -- U S WEST Technologies IAD/CSS/DPDS Phone: (303)595-2869
Denver, CO rjray@lookout.ecte.uswc.uswest.com

I don't suffer from insanity. I enjoy every minute of it.

Re: bad pods [ In reply to ]

tchrist at mox

Nov 6, 1995, 3:45 PM

Post #5 of 7 (704 views)

Permalink

>>Also, I notice that I got
>>
>> /usr/local/man/man1/perlrun.1
>> /usr/local/lib/perl/man/man3/Fcntl.3
>>
>>I don't think these should be in different place[s].

>I don't have any real heartburn with the disparate locales of these. Somewhere
>in the docs (perlmods, I think) it tells the user that to see the docs for
>the modules, add "/usr/local/lib/perl/man" to MANPATH. I have, and I can read
>them without worrying about where they are. I don't like a lot of stuff
>cluttering up man/man3 on my system, so I can live with this. IMHO, of course.

Is there any reason not to be basing everything off of one nice
packaged up installdir the way many other things do, eg:

$(INSTALL_DIR)/bin/perl5.001
$(INSTALL_DIR)/lib/Exporter.pm
$(INSTALL_DIR)/man/man1/perl.1
$(INSTALL_DIR)/man/man3/Exporter.1

It seems tidier.

If you set INSTALL_DIR to /usr/local, then you get things like

/usr/local/bin/perl5.001
/usr/local/lib/Exporter.pm
/usr/local/man/man1/perl.1
/usr/local/man/man3/Exporter.1

If you set it to /usr, you get things like

/usr/bin/perl5.001
/usr/lib/Exporter.pm
/usr/man/man1/perl.1
/usr/man/man3/Exporter.1

And if you set it to /usr/local/perl, you get things like

/usr/local/perl/bin/perl5.001
/usr/local/perl/lib/Exporter.pm
/usr/local/perl/man/man1/perl.1
/usr/local/perl/man/man3/Exporter.1

Hm... maybe if we make a link from /usr/bin/perl we should also
make one from /usr/man/man1/perl.1

--tom

Re: bad pods [ In reply to ]

wscott at pdx202

Nov 6, 1995, 4:31 PM

Post #6 of 7 (698 views)

Permalink

> Is there any reason not to be basing everything off of one nice
> packaged up installdir the way many other things do, eg:
>
> $(INSTALL_DIR)/bin/perl5.001
> $(INSTALL_DIR)/lib/Exporter.pm
> $(INSTALL_DIR)/man/man1/perl.1
> $(INSTALL_DIR)/man/man3/Exporter.1

Because users will be very upset when 'man less' brings up a description
on a perl module. (Perl? whats perl?)

Or how about 'man Socket'

Don't repeat the mistake of the TCL distribution. I curse that program
often for what it does to my man pages.

And remember telling people to get a better 'man' program is not a
solution. I think perldoc is the solution.

Wayne

Re: bad pods [ In reply to ]

tchrist at mox

Nov 6, 1995, 7:28 PM

Post #7 of 7 (703 views)

Permalink

>> Is there any reason not to be basing everything off of one nice
>> packaged up installdir the way many other things do, eg:
>>
>> $(INSTALL_DIR)/bin/perl5.001
>> $(INSTALL_DIR)/lib/Exporter.pm
>> $(INSTALL_DIR)/man/man1/perl.1
>> $(INSTALL_DIR)/man/man3/Exporter.1

>Because users will be very upset when 'man less' brings up a description
>on a perl module. (Perl? whats perl?)

>Or how about 'man Socket'

>Don't repeat the mistake of the TCL distribution. I curse that program
>often for what it does to my man pages.

>And remember telling people to get a better 'man' program is not a
>solution. I think perldoc is the solution.

*BZZZZZZZZT*

This is not a problem is you set INSTALL_DIR to be something like
/usr/local/perl, in which case you get less.3 in
/usr/local/perl/man/man3/less.3, and this won't conflict with anything.

--tom