Re: Linking to a POD document in POD
On Fri, 18 Nov 2005, John Siracusa wrote: On 11/17/05 11:08 PM, Ken Williams wrote: On Nov 17, 2005, at 7:16 PM, John Siracusa wrote: How do I link to a POD document form within my POD in such a way that search.cpan.org will make the correct link? I tried doing this: LMy::Foo to link to My/Foo.pod in my module, but that doesn't work. `perldoc perlpod` seems to suggest that you've got the correct syntax. Is My::Foo in this case actually found at all by search.cpan.org? Where does the generated link go to? Well, here's the non-version-specific link: http://search.cpan.org/dist/Rose-DB-Object/lib/Rose/DB/Object/Tutorial.pod But if you click on the instance of LRose::DB::Object::Tutorial near the start of the DESCRIPTION section on this page: http://search.cpan.org/~jsiracusa/Rose-DB-Object/lib/Rose/DB/Object.pm you'll see that it doesn't work. It takes me here: http://search.cpan.org/perldoc?Rose%3A%3ADB%3A%3AObject%3A%3ATutorial which is a 404. What looks like is happening is that search.cpan.org (sometimes) converts links in the docs into things of the form http://search.cpan.org/perldoc?Module::Name This seems to work if Module::Name is a registered name (eg, a query in CPAN.pm turns up some information on it), but doesn't for modules (or pure pod files) like Rose::DB::Object::Tutorial for which CPAN.pm doesn't know anything about (ie, it doesn't appear in the CPAN/PAUSE indices). -- best regards, randy kobes
Re: Linking to a POD document in POD
On 11/18/05, Randy Kobes [EMAIL PROTECTED] wrote: What looks like is happening is that search.cpan.org (sometimes) converts links in the docs into things of the form http://search.cpan.org/perldoc?Module::Name This seems to work if Module::Name is a registered name (eg, a query in CPAN.pm turns up some information on it), but doesn't for modules (or pure pod files) like Rose::DB::Object::Tutorial for which CPAN.pm doesn't know anything about (ie, it doesn't appear in the CPAN/PAUSE indices). Hm, okay, two questions. First, what do I do about it? Make the .pod into a .pm instead? That seems...icky. Second, why does this kind of linking work elsewhere? Example: The page: http://search.cpan.org/dist/Catalyst/lib/Catalyst.pm The source: http://search.cpan.org/src/MRAMBERG/Catalyst-5.56/lib/Catalyst.pm which contains the text: See LCatalyst::Manual::Intro for additional information. Which correctly links to: http://search.cpan.org/~mramberg/Catalyst-5.56/lib/Catalyst/Manual/Intro.pod Puzzling... -John
Re: Linking to a POD document in POD
On Fri, 18 Nov 2005, John Siracusa wrote: On 11/18/05, Randy Kobes [EMAIL PROTECTED] wrote: What looks like is happening is that search.cpan.org (sometimes) converts links in the docs into things of the form http://search.cpan.org/perldoc?Module::Name This seems to work if Module::Name is a registered name (eg, a query in CPAN.pm turns up some information on it), but doesn't for modules (or pure pod files) like Rose::DB::Object::Tutorial for which CPAN.pm doesn't know anything about (ie, it doesn't appear in the CPAN/PAUSE indices). Hm, okay, two questions. First, what do I do about it? Make the .pod into a .pm instead? That seems...icky. Second, why does this kind of linking work elsewhere? Example: The page: http://search.cpan.org/dist/Catalyst/lib/Catalyst.pm The source: http://search.cpan.org/src/MRAMBERG/Catalyst-5.56/lib/Catalyst.pm which contains the text: See LCatalyst::Manual::Intro for additional information. Which correctly links to: http://search.cpan.org/~mramberg/Catalyst-5.56/lib/Catalyst/Manual/Intro.pod Puzzling... It is puzzling ... One difference between the example of Catalyst::Manual::Intro and Rose::DB::Object::Tutorial is that Catalyst::Manual::Intro has a =head1 NAME Catalyst::Manual::Intro - Introduction to Catalyst section, whereas Rose::DB::Object::Tutorial doesn't. Perhaps inserting such a section would help - what seems to happen is that, within a distribution, direct links to docs will be formed for modules within that distribution; otherwise, http://search.cpan.org/perdoc? will be used. Although a NAME section alone isn't enough to register a module in the CPAN/PAUSE indices (a package declaration would also be needed, for example), perhaps such a section is enough for search.cpan.org in the context of forming links. -- best regards, randy
Re: Linking to a POD document in POD
A. Pagaltzis [EMAIL PROTECTED] wrote: * Randy Kobes [EMAIL PROTECTED] [2005-11-18 17:10]: Perhaps inserting such a section would help - what seems to happen is that, within a distribution, direct links to docs will be formed for modules within that distribution; otherwise, http://search.cpan.org/perdoc? will be used. Hmm, isnât the search.cpan.org code available somewhere? I seem to remember so, but canât find if and where saw mention of that. AFAIK, the source code of search.cpan.org is not available, although it uses many CPAN modules itself. As noted by Graham Barr on the Perl NOC blog, the site may migrate its full text search engine from WAIT to Swish-e: http://log.perl.org/cpansearch/ -- Sébastien Aperghis-Tramoni Close the world, txEn eht nepO.
Re: Linking to a POD document in POD
Randy Kobes [EMAIL PROTECTED] wrote: It is puzzling ... One difference between the example of Catalyst::Manual::Intro and Rose::DB::Object::Tutorial is that Catalyst::Manual::Intro has a =head1 NAME Catalyst::Manual::Intro - Introduction to Catalyst section, whereas Rose::DB::Object::Tutorial doesn't. Perhaps inserting such a section would help - what seems to happen is that, within a distribution, direct links to docs will be formed for modules within that distribution; otherwise, http://search.cpan.org/perdoc? will be used. Although a NAME section alone isn't enough to register a module in the CPAN/PAUSE indices (a package declaration would also be needed, for example), perhaps such a section is enough for search.cpan.org in the context of forming links. Andreas Koenig and Graham Barr confirmed me that this is the way the indexer works: the .pm files must contain a corresponding =head1 NAME, otherwise it is added in the documentation section. You can find more information about this in this thread: http://xrl.us/ihei [groups.google.com] -- Sébastien Aperghis-Tramoni Close the world, txEn eht nepO.
Linking to a POD document in POD
How do I link to a POD document form within my POD in such a way that search.cpan.org will make the correct link? I tried doing this: LMy::Foo to link to My/Foo.pod in my module, but that doesn't work. OTOH, that syntax seems to work fine in some other modules I see on CPAN. What am I doing wrong? Also, it there an easy way to see how search.cpan.org will treat my POD without actually uploading to CPAN? -John
Re: Linking to a POD document in POD
On Nov 17, 2005, at 7:16 PM, John Siracusa wrote: How do I link to a POD document form within my POD in such a way that search.cpan.org will make the correct link? I tried doing this: LMy::Foo to link to My/Foo.pod in my module, but that doesn't work. `perldoc perlpod` seems to suggest that you've got the correct syntax. Is My::Foo in this case actually found at all by search.cpan.org? Where does the generated link go to? -Ken
