Frequently Asked Questions
- General questions
- Creating and modifying notes
- For module authors
- Contact; bugs & features
- AnnoCPAN code and data
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:
- search.cpan.org has a better search engine, useful tools such as diff and grep, download links, and browsing.
- cpan.uwinnipeg.ca (also known as Kobes's search) provides an alternative search engine, and other features such as automatic module classification.
- CPAN::Forum has discussion forums categorized by module. This can be a good place for general discussions about specific modules whenever a module doesn't have designated discussion places such as mailing lists already.
- CPANRatings is a good place to post short reviews and rate modules.
- PerlMonks is a community for learning and discussing all kinds of issues related to Perl.
- AnnoCPAN has the goal of letting the post short comments, corrections, or suggestions about very specific parts of the documentation.
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
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.
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?
What does AnnoCPAN run on?
Contact, Bugs & Features
Who can I contact?
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?
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?
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
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.