Fwd: Hiding docs from search.cpan.org

Hi folks,

I just sent this to cpansearch AT perl DOT org.  We'll see
if they  
come back with anything.  In the meantime, if any of you
have  
suggestions, I'd like to hear them.

Marvin Humphrey
Rectangular Research
http://www.rectangular.co
m/


Begin forwarded message:

From: Marvin Humphrey <marvinrectangular.com>
Date: February 26, 2007 7:22:11 PM PST
To: cpansearchperl.org
Subject: Hiding docs from search.cpan.org

Greets,

I have 2 requests:

1) Can search.cpan.org please treat files that have no
visible POD  
the same as files that have no POD at all?

2) Can files which contain visible POD but won't be
installed get  
linked under "Other Files" rather than
"Documentation" from the main  
distribution page?

(The first request is more important.)

My distribution KinoSearch has a bunch of private classes,
which are  
documented with "invisible POD" as per Damian's
Perl Best Practices:

     =begin devdocs

     =head1 PRIVATE CLASS

     Widget::Ordinary - Plain ol' widget.

     =head1 DESCRIPTION

     Blah blah blah.

     =end devdocs
     =cut

Unfortunately, search.cpan.org shows these classes despite
the fact  
that there is NO visible POD whatsoever.

     http://search.cpan.org/~creamyg/KinoSearch-0.20_01/lib/ 
KinoSearch/Store/OutStream.pm

They can still be found in a search.

     http://search.cpan.org/search?query=outstream&mode
=all

They are still linked rather than grayed out from the main
page of  
the distribution:

     h
ttp://search.cpan.org/~creamyg/KinoSearch-0.20_01/

With the latest release of KinoSearch, I changed all the...

     =head1 NAME

... blocks to...

     =head1 PRIVATE CLASS

... in the hope that that would keep them hidden.  While
that has  
stopped the synopsis sentence fragment following NAME from
showing  
up, it hasn't made them vanish as I'd hoped.

There's also a bunch of developer documentation outside of
$DIST_ROOT/ 
lib and $DIST_ROOT/bin that I don't want people to see.  For
 
instance, there's a Module::Build subclass 
--$DIST_ROOT/buildlib/ 
KinoSearchBuild.pm -- that I documented with POD, but not
for the  
benefit of ordinary users.  The file doesn't get installed,
and its  
documentation doesn't belong in the
"Documentation" section along  
with $DIST_ROOT/lib/KinoSearch/Docs/Tutorial.pod, which IS
crucial  
documentation.

     h
ttp://search.cpan.org/~creamyg/KinoSearch-0.20_01/

Please let me know whether you consider these reasonable
requests,  
and please suggest alternatives if you do not.  I'd like
these  
materials to have the greatest coherence and impact when
presented on  
your site, and right now, things are more messy and
confusing than I  
would like.

Cheers,

Marvin Humphrey
Rectangular Research
http://www.rectangular.co
m/








_______________________________________________
KinoSearch mailing list
KinoSearchrectangular.com
http://www.rectangular.com/mailman/listinfo/kinosearch

On Feb 26, 2007, at 7:33 PM, Marvin Humphrey wrote:

> I just sent this to cpansearch AT perl DOT org.

... and now I've heard back.

For the record, here are the answers.

> 1) Can search.cpan.org please treat files that have no
visible POD  
> the same as files that have no POD at all?

This seems to be a bug, and they're looking into it.

> 2) Can files which contain visible POD but won't be
installed get  
> linked under "Other Files" rather than
"Documentation" from the  
> main distribution page?

The META.yml spec includes a "no_index" directive
which will cause  
files/folders not to be indexed by PAUSE or
search.cpan.org.

   http://module-build.sourceforge.net/META-spec
-current.html#no_index

That will allow private items to be hidden from searches.

It's unclear whether a file filtered by the no_index list
will have  
its link disappear from the main distro page.  We'll just
have to see  
on the next dev release.

Marvin Humphrey
Rectangular Research
http://www.rectangular.co
m/



_______________________________________________
KinoSearch mailing list
KinoSearchrectangular.com
http://www.rectangular.com/mailman/listinfo/kinosearch