AnnoCPAN

 view release on metacpan or  search on metacpan

html/about.pod  view on Meta::CPAN

=head2 Where does AnnoCPAN fit in?

When I started working on this project, there were many modules on CPAN that
don't have mailing lists or other discussion places. Scattered discussions
could happen in various places, or some users could post general comments on
cpanratings.perl.org. However, there was no central place where users could help
each other by commenting on specific features, uses, gotchas, etc. for all Perl
modules. A limitation of sites such as CPANRatings (and to a certain degree
other sites that host reviews) is that the comments appear out of the context
of the module's documentation, so they are necessarily general unless the
comment's author decides to write a long review to establish context. AnnoCPAN
intends to fill this gap by allowing users to add public annotations on the
margin of the documentation of every module on CPAN.

The idea is not new, of course; MySQL and PHP already have something similar.
One difference is that notes in AnnoCPAN belong to specific paragraphs instead
of chapters, and they are shown on the margin (or between paragraphs, depending
on the style sheet) instead of at the bottom of the page.

=head2 How does it work?

html/about.pod  view on Meta::CPAN

similar to the last one. If it is a bugfix release, there might not be any
changes at all; otherwise functions are typically added but not removed. In
cases such as this, it would be a good idea to transfer the old notes to the
new version. The paragraph to which the note was originally attached can be
compared to the paragraphs in the new version and, if one is similar enough
(preferably identical), the note is transferred.

If the system can't figure out where to put the old note, the author or a
moderator can move it to a place in the new version if the note still applies.
Hopefully some of the good notes will become obsolete once the author of the
module decides to update the documentation to address the issues mentioned in
the note.

Users are able to edit, move, and delete their own notes. Moderators are be
able to move or delete any note. 

=head1 CURRENT STATUS

This test version already has essentially all the documentation found on CPAN,
except for occasional difficulties with the non-trivial problem of unpacking and
identifying the relevant content in distributions which were packed in many

lib/AnnoCPAN/Control.pm  view on Meta::CPAN

2) Returns a list ($vars, $template, $type). $vars is a hash reference of
variables that should be passed to the template; $template is the name of the
template that should be processed (sans the extension). $type is the MIME type
that should be given in the header. $type is optional; it defaults to
text/html. If $template is false, no headers will be printed and no template
will be processed.

3) Takes an optional parameter $vars. If given, it is expected to be a hash
reference which will be appended to the variables normally returned by the
method. It is used when one mode decides to fall back to another but wants to
add or override some variables of its own.

For example, the Main method could be:

    sub Main {
        my ($self, $vars) = @_;
        $vars ||= {};
        my @recent = AnnoCPAN::DBI::Note->search_recent;
        ({recent => \@recent, %$vars}, "main");
    }

lib/AnnoCPAN/Dist.pm  view on Meta::CPAN

=head1 DESCRIPTION

AnnoCPAN has to understand CPAN distribution packages, find all the relevant
documentation they contain, and figure out the versions and the correct
pathname for each document. This is not a trivial task given the inconsistent
ways in which CPAN distributions are packaged; there are several specific cases
to consider. Note that this module does not aim at 100.00% coverage (but at
least 99%, I hope); if a package does not comply with any of the standards
that this package understands, it will be silently excluded. One can only hope
the authors of the excluded package will some day decide to package their
modules in more standard ways.

This module claims to understand the following types of packages:

=over

=item *

Files in the .zip and .tar.gz file formats.

tt/faq.html  view on Meta::CPAN

<a name="conf"></a><h3>What's the %confidence?</h3>

<p>When a note is added to a document, the software tries to guess where
would the same note go in other versions of the same document. This is based
on a text similarity analysis which provides a quantitative estimate
expressed as a percentage.</p>

<p>For example, let's say that you add a note to My::Module in My-Dist-0.10,
next to a paragraph that says "this is a paragraph". When version 0.20 comes
out, let's say that the paragraph moved and was modified to say "this is
one paragraph". The similarity search decides that this is still the same
paragraph with a confidence of 95% and assigns the note accordingly.</p>

<a name="absurd"></a><h3>A note is in an absurd place! Why's that?</h3>

<p>The notes are assigned to other versions of the document by using the method
discussed above. As with all heuristics, there will be mistakes, especially
when a paragraph is completely deleted or modified very heavily. In these cases
it is necessary to move the note manually or hide it if it no longer
applies.</p>