Re: Getting man-page info on metacpan and search.cpan.org
by rockyb (Scribe) on May 31, 2016 at 04:34 UTC
|
It looks like using .pod in a bin directory is a lose. At least with Module::Build. So for now, I think the best route is to link to a wiki or put command-line pods its own directory and again link. Sigh. | [reply] |
|
It looks like using .pod in a bin directory is a lose. At least with Module::Build. So for now, I think the best route is to link to a wiki or put command-line pods its own directory and again link. Sigh. What does Module::Build have to do with it?
You can't have three things with the same name and have pod tools know which one you want as the real one :)
| [reply] |
|
First, there aren't three things, but two: bioseq and bioseq.pod.
Second, that metacpan lists this three times in two lines with one name duplicated in https://metacpan.org/source/ROCKY/Bio-BPWrapper-1.02_02/bin is its doing. And the second entry is backwards; the name listed is actually the documentation and the documentation associated with that name is really the command-line program. And that is a bug.
As for pod tools "knowing", if that's the thing that is deciding this, well it somehow knows that for a perl module. If there is a file that has extension .pod with the same name as he Perl Module, then that's not a separate program but documentation for the corresponding perl module. This is what LanX's answer in Using .pod as a standalone file rather than in .pm and it showing up in MetaCPAN is about. I am sorry I didn't link that before.
Finally, what Module::Build may have to do with this is possibly how this stuff gets tagged or set up in a tarball: the pod in the bin directory is installed same as without the pod. It is possible and likely this is that's not dictated by Module::Build, but the tools and rules for processing a tarball: what and where to install. In this case it happens to have been created by Module::Build so that is one interface for controlling the building of the tarball. Sure, there are other things too that influence this as well.
| [reply] [d/l] [select] |
|
|
|
|
|
Re: Getting man-page info on metacpan and search.cpan.org
by Anonymous Monk on May 31, 2016 at 00:44 UTC
|
| [reply] |
|
Thanks. It took me a while to understand you because of the HTML escaping in the link. I went to that URL, and yes I see a nice link to a man page. (BTW, the first link in that section, to lwp-request, is broken).
So that answers part of the question. However lwp-dump puts its POD inside the script and I'd like to have that be separate, because it may be shared/duplicated in a github wiki. So my thought was to create in the same directory the something like lwp-dump.pod.
Again I'll make a little test, and make sure to follow your guidelines and follow the format of lwp-dump.
| [reply] [d/l] [select] |
|
(BTW, the first link in that section, to lwp-request, is broken). I'm guessing, but probably because it is created at when you run Makefile.PL , so if you install LWP, the link will work, just not on CPAN
update: well I checked, its a typo in the NAME section of https://metacpan.org/pod/distribution/libwww-perl/bin/lwp-request, must use dash, convention is NAME - description so it should be
lwp-request - GET, POST, HEAD - Simple command line user agent
This is also a bug in PAUSE/CPAN indexer, most folks figure out the right formatting, but it should warn the rest when =head1 NAME doesn't match NAME - description because its used for resolving links
It took me a while to understand you because of the HTML escaping in the link.
Aww :) I usually double check ... metamod:// should be smarter and save me when I typo :) https://metacpan.org/pod/LWP#MORE-DOCUMENTATION
| [reply] [d/l] [select] |
|
| [reply] |
|
|
|
|