David Golden wrote: > On 9/21/07, Michael G Schwern <[EMAIL PROTECTED]> wrote: >> Michael G Schwern wrote: >> Hmm. I just noticed that I set 'no_index' for the src directory which >> contains the SVN:: modules which brings up the interesting question of which >> takes precedence, no_index or provides? >> >> Since provides is explicit, I'd say it should override the more general >> no_index. > > My understanding is that these serve two different purposes. > > "provides" indicates what modules are included in the tarball so that > tools don't have to unpack the tarball to understand the contents. > The specification says it "can be" used to build indexes -- it doesn't > say it must be. > > "no_index" indicates which modules "are not of interest" to an online > index (e.g. search.cpan.org). That is much more specific than > "provides" so it makes sense that "no_index" takes precedence over > "provides".
Here's the problem. "no_index" allows me to blot out whole directory trees and individual files. "provides" allows me to specify individual files. Trouble is I have an enormous subdirectory full of files. http://search.cpan.org/src/MSCHWERN/Alien-SVN-1.4.5.2/src/subversion-1.4.5/ Most of it should not be indexed, but buried deep down in there is a handful of Perl modules which should be. Crafting a "no_index" that excludes everything but these modules is a royal pain in the ass. So I've said: no_index: directory: src provides: SVN::Core: file: src/subversion-1.4.5/subversion/bindings/swig/perl/native/Core.pm version: 1.4.5 Which is to say "don't try to index inside src/ yourself, let me tell you what's in there". Since there's no reason why I'd want to specify specific files in 'provides' without their being indexed, 'provides' should take precedence over 'no_index' assuming the indexer in question is even paying attention to 'provides'. That's what I mean about provides being more explicit than no_index. > I don't see those as opposites -- and in fact I use them both together > for documentation using Pod::WikiDoc. For "pure" documentation files, > (e.g. CPAN::Reporter::API), I write documentation in WikiDoc in > API.pm. Pod::WikiDoc converts that during "Build dist" to ordinary > Pod in API.pod. In this case, "provides" shows API.pm (with its > version information), but I add "API.pm" to "no_index". > > The result is that search.cpan.org indexes only API.pod and it thus > shows up in the documentation section on search.cpan.org. I don't think setting no_index on API.pm is necessary as search will favor a Foo.pod over a Foo.pm for displaying docs, just like perldoc. In fact, since CPAN::Reporter::API should be in the 02module index, it is contradictory to say a file provides a package and also that file should not be indexed. -- Robrt: People can't win Schwern: No, but they can riot after the game.
