From PerlNet

Thank you for your interest in helping index Perl's core documentation! This guide lists the steps you should follow to become a POD Indexer (tm).

Contents 1 Getting the source 2 Indexing 3 Patching example 4 Coordination 5 Project Snapshots 6 Original Author

Getting the source

All patches we provide should be against the latest development perl, also known as bleadperl or perl-current. You can read "perlhack" for more details, but to summarize:

You can browse perl-current at

   http://public.activestate.com/gsar/APC/perl-current/

If you just want to get one file at a time, that's the easiest way, and may be enough for our documentation purposes.

If you want to mirror the whole thing, the recommended way is to use rsync:

   rsync -avz rsync://ftp.linux.activestate.com/perl-current/ perl-current

Indexing

Basically you need to go through each document you are interested in, and add keywords using the POD X<> code. The conventions are described in more detail in the documentation for POD::Index, which you can find at

   http://annocpan.org/perldoc?Pod::Index
   http://search.cpan.org/~itub/Pod-Index/lib/Pod/Index.pm

The idea of these conventions is to aim for consistency and make it as simple as possible for parsing software to handle.

Please add all the X<> entries at the end of the relevant paragraph, on a separate line(s). This makes the patches easier to read, because the only changes will be addition of lines, rather than modified lines.

To get the best results, we need to add just the "right" amount of X<> marks. Try to mark only the places that could be considered definitive for a topic, or that add useful information. That is, don't add X<$_> every time you see $_ appear in the documentation; the entry in perlvar, and maybe a couple of other places, such as the discussion of the implicit localization of $_ in perlsyn should be enough. The idea is that the user should be able to find the relevant documentation for a keyword, without getting swamped by lots of results. Just use your best judgment. That's why we are doing this with humans and not with a search engine. :-)

Patching example

This examples are for a Unix-like command shell, but you can probably figure it out for your system.

1) Let's say you are modifying perlop.pod. First, save a copy as perlop.pod.old or something to that effect:

   cp perlop.pod perlop.pod.old

2) Edit perlop.pod.

   myfavorite_editor perlop.pod

3) Create a patch using diff -u

   diff -u perlop.pod.old perlop.pod > perlop.pat

If you don't have F<diff> and don't want to figure out how to get it, just send me the modified file and I can make the patch from it.

A sample patch for perlop.pod was attached to the message at

   http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2005-07/msg01215.html

Coordination

So that everyone knows what everyone is doing, and to avoid duplication of effort, please subscribe to the perl-documentation mailing list by sending a blank email to

   perl-documentation-subscribe@perl.org

If you decide to "take" a document, just send an email to the list. When you are done, send an email with the patch.

Project Snapshots

If you want to see the PODS that have been indexed so far, and want to have fun testing the new modified perldoc with POD::Index support, download the latest POD indexing snapshot from

   http://pod-indexing.annocpan.org/

Original Author

Ivan Tubert-Brohman <itub@cpan.org>