Re: CPAN vs. POD outside of .pm (.pl) files?

From	Ivan Shmakov <oneingray@gmail.com>
Newsgroups	comp.lang.perl.misc
Subject	Re: CPAN vs. POD outside of .pm (.pl) files?
Date	2013-06-27 05:42 +0000
Organization	Aioe.org NNTP Server
Message-ID	<8761x09kjx.fsf@violet.siamics.net> (permalink)
References	<87y5a8es4l.fsf@violet.siamics.net> <3jl39a-9b61.ln1@anubis.morrow.me.uk> <87li68eog9.fsf@violet.siamics.net> <pl649a-mb42.ln1@anubis.morrow.me.uk>

Show all headers | View raw

>>>>> Ben Morrow <ben@morrow.me.uk> writes:
>>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
>>>>> Ben Morrow <ben@morrow.me.uk> writes:

[...]

 >>> What do you mean by 'CPAN'?  The CPAN shell doesn't normally do
 >>> this.  Do you mean search.cpan.org?

 >> Yes, I've meant http://search.cpan.org/ specifically, even though
 >> I've inaccurately referenced the whole cpan.org infrastructure.

 >> I didn't mean cpan(1).

 > OK.  I asked because I think it's possible to configure at least
 > cpanp to install HTML documentation, and IIRC ActiveState have or
 > used to patch their CPAN.pm to do the same.

	That's interesting.  Thanks.

[...]

 >>> search.cpan.org already displays a list of all the .pod files in a
 >>> distribution under the 'Documentation' section.  If a .pm file has
 >>> no Pod, and there is a .pod file next to it, it moves the .pod link
 >>> up into the 'Modules' section.

 >> (Which makes me wonder where is it documented?)

 > I don't think it is.  search.cpan.org is not part of the CPAN
 > infrastructure per se, it was just a useful website written by Graham
 > Barr which was given a domain under cpan.org.

	Which seems to make it quite a "part," at least for a casual
	user like me.

 > I believe the intention is that it should index things in the same
 > way as CPAN.pm and perldoc.

	ACK, thanks.

 >>> It's probably important to get the NAME section of the Pod right.
 >>> I don't exactly know how the search.cpan.org/perldoc?foo links it
 >>> uses for L<> work, but I suspect they're indexed based on the NAME
 >>> section.

 >> ACK, thanks!  Hopefully, such indexing won't insist on the use of a
 >> HYPHEN-MINUS (U+002D) there, instead of the arguably more
 >> appropriate EN DASH (U+2013).

 > I wouldn't muck about with the formatting of the NAME section.

	FWIW, http://search.cpan.org/ seems to handle it just fine.
	Consider, e. g.:

http://search.cpan.org/perldoc?Tree::Range::base
http://search.cpan.org/perldoc?Tree::Range::RB

	Preasumably, it just indexes the PODs by the filename.

 > pod2man in particular is quite picky about it, and there are other
 > tools which rely on the format being right.

	As it seems, ExtUtils::MakeMaker assumes (SPACE, HYPHEN-MINUS,
	SPACE) for the delimiter while handling ABSTRACT_FROM, and I'm
	considering it a bug (yet to be filed.)

	I've not seen any problem with pod2man(1) vs. NAME as of yet.
	What should I take note of?

	(It appears to assume that --quotes= is a string of two
	/octets/, not two /characters,/ though.)

-- 
FSF associate member #7257

Back to comp.lang.perl.misc | Previous | Next — Previous in thread | Next in thread | Find similar

Thread

CPAN vs. POD outside of .pm (.pl) files? Ivan Shmakov <oneingray@gmail.com> - 2013-06-17 14:20 +0000
  Re: CPAN vs. POD outside of .pm (.pl) files? Ben Morrow <ben@morrow.me.uk> - 2013-06-17 16:12 +0100
    Re: CPAN vs. POD outside of .pm (.pl) files? Ivan Shmakov <oneingray@gmail.com> - 2013-06-17 15:39 +0000
      Re: CPAN vs. POD outside of .pm (.pl) files? Ben Morrow <ben@morrow.me.uk> - 2013-06-17 21:03 +0100
        Re: CPAN vs. POD outside of .pm (.pl) files? Ivan Shmakov <oneingray@gmail.com> - 2013-06-27 05:42 +0000
          Re: CPAN vs. POD outside of .pm (.pl) files? Ben Morrow <ben@morrow.me.uk> - 2013-06-27 08:12 +0100
            issues with POD Ivan Shmakov <oneingray@gmail.com> - 2013-06-27 08:50 +0000
              Re: issues with POD Ben Morrow <ben@morrow.me.uk> - 2013-06-27 12:32 +0100
                Re: issues with POD Ivan Shmakov <oneingray@gmail.com> - 2013-06-27 12:48 +0000
                Re: issues with POD Ben Morrow <ben@morrow.me.uk> - 2013-06-27 14:53 +0100
                $ pod2man --quotes= Ivan Shmakov <oneingray@gmail.com> - 2013-06-27 15:20 +0000
                Re: issues with POD Ivan Shmakov <oneingray@gmail.com> - 2013-06-27 15:25 +0000
                Re: issues with POD Ben Morrow <ben@morrow.me.uk> - 2013-06-27 22:21 +0100
                [OT] PostScript Ivan Shmakov <oneingray@gmail.com> - 2013-06-28 11:58 +0000
                Re: issues with POD Ivan Shmakov <oneingray@gmail.com> - 2013-06-28 12:04 +0000
                Re: issues with POD Shmuel (Seymour J.) Metz <spamtrap@library.lspace.org.invalid> - 2013-06-30 08:37 -0400
                Re: issues with POD Ivan Shmakov <oneingray@gmail.com> - 2013-06-30 17:57 +0000
                Re: issues with POD Shmuel (Seymour J.) Metz <spamtrap@library.lspace.org.invalid> - 2013-07-01 17:38 -0400
                Re: issues with POD Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-06-30 19:44 +0100
                Re: issues with POD Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-06-28 14:29 +0100
                [OT] non-issues with non-solutions Ivan Shmakov <oneingray@gmail.com> - 2013-06-28 13:45 +0000
                Re: [OT] non-issues with non-solutions Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-06-28 15:13 +0100
                Re: [OT] non-issues with non-solutions Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-06-29 19:37 +0100
                a-Moose-ing CGI Ivan Shmakov <oneingray@gmail.com> - 2013-06-30 07:56 +0000
                Re: a-Moose-ing CGI Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-06-30 14:05 +0100
                Re: a-Moose-ing CGI Ben Morrow <ben@morrow.me.uk> - 2013-07-01 13:26 +0100
                Re: a-Moose-ing CGI Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-07-01 18:12 +0100
                [OT] CGI: "Fast" vs. "classic" Ivan Shmakov <oneingray@gmail.com> - 2013-07-01 17:27 +0000
                Re: [OT] CGI: "Fast" vs. "classic" Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-07-01 18:45 +0100
                Re: a-Moose-ing CGI Ben Morrow <ben@morrow.me.uk> - 2013-07-01 18:52 +0100
                Re: issues with POD Ben Morrow <ben@morrow.me.uk> - 2013-07-01 13:29 +0100
                Re: issues with POD "Peter J. Holzer" <hjp-usenet3@hjp.at> - 2013-07-01 17:19 +0200
                Re: issues with POD Ben Morrow <ben@morrow.me.uk> - 2013-07-01 18:38 +0100
                Re: issues with POD Mart van de Wege <mvdwege@mail.com> - 2013-07-02 10:13 +0200
                Re: issues with POD "Dave Saville" <dave@invalid.invalid> - 2013-07-02 08:54 +0000
                Re: issues with POD Ben Morrow <ben@morrow.me.uk> - 2013-07-02 11:42 +0100
                perldoc and perl-doc Ivan Shmakov <oneingray@gmail.com> - 2013-07-02 11:17 +0000
                Re: perldoc and perl-doc Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-07-02 12:37 +0100
                Re: perldoc and perl-doc Ivan Shmakov <oneingray@gmail.com> - 2013-07-02 14:34 +0000
                Re: perldoc and perl-doc Jürgen Exner <jurgenex@hotmail.com> - 2013-07-02 08:18 -0700
                Re: perldoc and perl-doc Ivan Shmakov <oneingray@gmail.com> - 2013-07-02 15:23 +0000
                Re: perldoc and perl-doc Eric Pozharski <whynot@pozharski.name> - 2013-07-03 09:41 +0300
                Re: perldoc and perl-doc "Peter J. Holzer" <hjp-usenet3@hjp.at> - 2013-07-02 17:38 +0200
                Re: perldoc and perl-doc Ben Morrow <ben@morrow.me.uk> - 2013-07-02 16:37 +0100
                Re: perldoc and perl-doc Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-07-02 17:20 +0100
                Re: perldoc and perl-doc Charlton Wilbur <cwilbur@chromatico.net> - 2013-07-02 12:08 -0400
                [OT] MIME adoption in Usenet Ivan Shmakov <oneingray@gmail.com> - 2013-07-03 12:59 +0000
                Re: [OT] MIME adoption in Usenet Ben Morrow <ben@morrow.me.uk> - 2013-07-03 17:49 +0100
                Re: issues with POD tmcd@panix.com (Tim McDaniel) - 2013-06-27 18:43 +0000

csiph-web