Beefy Boxes and Bandwidth Generously Provided by pair Networks
Do you know where your variables are?
 
PerlMonks  

Getting man-page info on metacpan and search.cpan.org

by rockyb (Scribe)
on May 31, 2016 at 00:34 UTC ( #1164534=perlquestion: print w/replies, xml ) Need Help??

rockyb has asked for the wisdom of the Perl Monks concerning the following question:

Suppose I have a module and a command-line interface to that.

Right now using Module::Build, if I create a directory called /bin those scripts get installed. I recently learned that Metacpan.org will treat POD files (.pod) as documentation for corresponding Perl modules (.pm). But will it do the same for command-line scripts?

And if I want to link to that command from a readme or the corresponding library, can I do that with L<> and have it link correctly on metacpan?

I can and will make experiments, but it would save a lot of spurious releases and testing and time waiting for indexing if someone out there just knew what works. Thanks.

Replies are listed 'Best First'.
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.

      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 :)

        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.

Re: Getting man-page info on metacpan and search.cpan.org
by Anonymous Monk on May 31, 2016 at 00:44 UTC

      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.

        (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

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlquestion [id://1164534]
Approved by GrandFather
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others romping around the Monastery: (3)
As of 2022-05-26 20:30 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Do you prefer to work remotely?



    Results (94 votes). Check out past polls.

    Notices?