[% PROCESS header.html title="FAQ" %] [% PROCESS login_form.html %] [% PROCESS form.html %]

## Frequently Asked Questions

1. What is AnnoCPAN?
2. Who's behind it?
3. How does it work?
4. How does this site relate with CPAN::Forum, CPANRatings, search.cpan.org, PerlMonks...?
5. How do I add a note?
6. How can I format my notes?
7. Can I edit my notes?
8. Can I edit other people's notes?
9. What's the difference between "hiding" and "deleting" a note?
10. How do I unhide a note?
11. How can I know when someone posts a note to one of my modules?
12. What happens if I upgrade my documentation, making a note obsolete?
13. What's the %confidence?
14. A note is in an absurd place! Why's that?
15. What are the browser requirements?
16. What does AnnoCPAN run on?
17. Who can I contact?
18. Why is X distribution missing, or module Y in the wrong place?
19. Can I get the code?
20. What are the technical requirements for installation?
21. What's the license for the notes?
22. Can I get RSS feeds?

## 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.

### 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 expenses.

### 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 [% link_perldoc_name('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 `[% root_uri_abs %]/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?

You can subscribe to an RSS feed at `[% root_uri_abs %]/~pauseid/recent.rss` or view the notes directly at `[% root_uri_abs %]/~pauseid/recent.html`. There are plans for setting up an email notification system as well.

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

The notes can be hidden from the new versions, while keeping them for the old versions of the documentation (if it's still on CPAN). If the change to the document was big enough, this might happen automatically; if note, 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?

Linux/Apache/MySQL/Perl. Some of the most notable modules used include the [% link_dist_name("Template-Toolkit") %], [% link_dist_name("Class-DBI") %], [% link_dist_name("Archive-Tar") %], and [% link_dist_name("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 [% link_dist_name("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 `[% root_uri_abs %]/~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.

[% PROCESS footer.html %]