[DBIx-Class-Devel] Pull Request: topic/docs-pod-inherit

[Brendan Byrd]

On Fri, Dec 14, 2012 at 11:01 AM, Peter Rabbitson <rabbit+dbic at rabbit.us> wrote:
>
> Yes, but the "indexing" (this is not an entirely correct term, because
> it has to do with the PAUSE indexes) is based on filename, not only
> on contents.

Only if it has to fallback on that.  SCO/MC uses =NAME, and "package" as well.

>> 1. Separate .generated_pod/lib.  Already tried that.
> s.c.o. has problems with that, metacpan is just not yet fixed

Depends on what you mean by "fixed".  Moritz pointed out something
that I forgot about MC: MetaCPAN separates the Modules from
Documentation as two different sections.  So, even if the
/module/DBIx::Class::* links work right, they will always put the PMs
in Modules and the PODs in Documentation on the main index page.
That's not a bug, but exactly how it's supposed to work, unless we can
argue some sort of design solution.

Current issue here: https://github.com/CPAN-API/metacpan-web/issues/724

>> 3. Combined directory with pod/pm together.  Doesn't change anything.
> On the contrary - http://search.cpan.org/~ribasushi/DBIx-Class-0.08204_02/
> Now all you need to do is press the metacpan folks to fix their stuff
> to match how s.c.o. (correctly) behaves.
>
> The list of issues comparing:
> http://search.cpan.org/~ribasushi/DBIx-Class-0.08204_02/ and
> https://metacpan.org/release/RIBASUSHI/DBIx-Class-0.08204_02/

SCO is slow; still can't see it yet.

> * Documentation section has duplicate entries for stuff existing in
> the Modules section (a simple exclusion needs to run before compiling
> the list of files)

As pointed out above, this is by design.

> * If a x.pod and x.pm exist, a web UI must link to the .pod, devrel
> or no devrel.

As of right now, this it the only thing we can "fix" in MC.  However,
we can't test it without a prod release because /module/ links always
point to the latest stable release.  I was planning on putting out an
Acme::CPAN::PodDisplay distro to test things out.

> * Metacpan puts DBIx::Class::Optional::Dependencies in the Provides
> section for no reason (it is a proper .pm, ought to be in Modules)

It's a proper PM with no internal pod, thus it's in Provides.  This
can be hidden with anti-PAUSE tricks.

> * DBIx::Class::Carp is in Modules, even though it is explicitly
> no_index-ed

That actually sounds like a bug.

>> 5. Add the dupe PMs to no_index.  Might work, but not sure if this
>> causes adverse effects to CPAN, installs, and perldoc.
> Yes it does - no_index is general for "hide from any search index"

Anti-PAUSE tricks might be able to do the same thing as well.

-- 
Brendan Byrd <Perl at ResonatorSoft.org>
Brendan Byrd <BBYRD at CPAN.org>