Annotated CPAN


Frequently Asked Questions

General Questions

What is AnnoCPAN?

An "Annotated CPAN". This is a site where you can browse all the Perl documentation available on CPAN (including both the core perl distribution and the non-core modules), add your own annotations, and read the annotations left by other users.

Note, however, that this is not a substitute for sending a proper bug report to the author or maintainer of a module, if applicable (Read more...).

Who's behind it?

The site was conceived, designed and implemented by Ivan Tubert-Brohman (known as ITUB on CPAN). The Perl Foundation provided a grant to encourage him to finish and help pay for some of the initial expenses. Pair Networks is generously donating the server and bandwidth.

How does it work?

The AnnoCPAN site has the documentation for all the CPAN modules, and a database of "notes" that can be added through the web interface. When a user views a module's documentation, the POD is shown as HTML together with the notes. This allows users to write very short notes that fill gaps in the documentation; for example, it might be sufficient to say "warning: this method returns different things in scalar and in list context and the POD doesn't mention it!".

How does this site relate with CPAN::Forum, CPANRatings, search.cpan.org, PerlMonks...?

The goals of AnnoCPAN and all these sites overlap to varying degrees, but each one fills a different niche:

Since these websites complement each other, they are frequently linked to from AnnoCPAN.

Creating and modifying notes

How do I add a note?

After you log in, click on the note icon next to the paragraph where you want to add the note

How can I format my notes?

Currently a subset of POD is allowed. You can use formatting sequences such as L<> (link), B<> (bold), I<> (italic), C<> (code), etc, and verbatim paragraphs (lines that start with a space). What you can't use are the pod commands, such as =item, =head1, etc. For more information about the POD format, see perlpod.

Can I edit my notes?

Yes, just click on the edit button. Make sure you are logged in first!

Can I edit other people's notes?

No, unless you somehow get moderator privileges.

What's the difference between "hiding" and "deleting" a note?

Deletion is irreversible and global, meaning that the note will disappear from all versions of the POD; hiding is reversible and local, meaning that the note is hidden only for a specific version of the POD.

How do I unhide a note?

If you go to http://annocpan.org/note/note_id, you will see a list of where the note is listed for each version of a POD, along with checkboxes for hiding and unhiding notes.

For Module Authors

How can I know when someone posts a note to one of my modules?

Module authors receive an automated email notification (to their public address, as registered with the PAUSE) the first time someone posts a note to one of their modules. This email explains how to subscribe to receive further notifications.

You can also subscribe to an RSS feed at http://annocpan.org/~pauseid/recent.rss or view the notes directly at http://annocpan.org/~pauseid/recent.html.

What happens if I upgrade my documentation, making a note obsolete?

The notes can be hidden for the new versions of the document, while keeping them for the old versions (if it's still on CPAN). If the change to the document was big enough, this might happen automatically; if not, either the note author or a moderator can do it manually.

Technical

What's the %confidence?

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.

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.

A note is in an absurd place! Why's that?

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.

What are the browser requirements?

IE 6, Mozilla/Firefox, Netscape 7, Opera 7, etc., although it should degrade gracefully in text browsers such as Lynx. It will likely not look reasonable in browsers with severely broken CSS implementations. JavaScript is recommended but not strictly required. Cookies are required for authentication. A monitor resolution of 1024x768 or greater is recommended, especially if you want the notes to show on the margin.

What does AnnoCPAN run on?

FreeBSD/Apache (mod_perl)/MySQL/Perl. Some of notable modules used include the Template-Toolkit, Class-DBI, Archive-Tar, and Archive-Zip.

Contact, Bugs & Features

Who can I contact?

You can send general comments, suggestions, money, etc., to itub@cpan.org. For bug reports please use the request tracker.

Why is X distribution missing, or module Y in the wrong place?

Although most of the distributions on CPAN are packaged in reasonably standard ways, there are a few with strange variations that confuse the AnnoCPAN software. If you find one of these cases, please report it.

AnnoCPAN Code and Data

Can I get the code?

The code is available on CPAN under the same terms as Perl itself as the AnnoCPAN distribution. It is also available on anonymous CVS, including a viewcvs web interface

What are the technical requirements for installation?

Besides the modules and software listed above, it needs a local CPAN mirror and a lot of space for the database. 4 GB or more of free space are recommended.

What's the license for the notes?

All the notes are available under the same terms as Perl itself. The entire note database can be downloaded as an XML Dump.

Can I get RSS feeds?

Yes, the sitewide recent notes are available as RSS 1.0: recent.rss. The notes for a given PAUSE ID are available at http://annocpan.org/~pauseid/recent.rss . RSS feeds per module and per distribution are also being considered.

There is also a feed of new distributions at recent_dists.rss. Note that this feed includes only distributions that are completely new; it doesn't include the ones that are merely a new version of a previous distribution.