[% PROCESS header.html title="FAQ" %] [% PROCESS login_form.html %] [% PROCESS form.html %]
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.
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 expenses. The annocpan.org site is currently generously hosted by BUU.
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!".
After you log in, click on the note icon next to the paragraph where you want to add the note
Yes, just click on the edit button. Make sure you are logged in first!
No, unless you somehow get moderator privileges.
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.
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 delete it if it no longer applies.
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.
Linux/Apache/MySQL/Perl. Some of the most notable modules used include the [% PROCESS link_dist_name name="Template-Toolkit" %], [% PROCESS link_dist_name name="Class-DBI" %], [% PROCESS link_dist_name name="Archive-Tar" %], and [% PROCESS link_dist_name name="Archive-Zip" %].
You can send general comments, suggestions, money, etc., to itub@cpan.org. For bug reports please use the request tracker.
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.
The code is available on CPAN as the [% PROCESS link_dist_name name="AnnoCPAN" %] distribution. It is also available on anonymous CVS, including a viewcvs web interface
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.
All the notes are available under the same terms as Perl itself. The entire note database can be downloaded as an XML Dump.
Yes, the sitewide recent notes are available as RSS 1.0: recent.rss. The notes for a given PAUSE ID are available at [% root_uri_abs %]/~pauseid/recent.rss . RSS feeds per module and per distribution are also being considered.
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.
[% PROCESS footer.html %]