This project started with the discussion at
http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2005-07/msg01215.html
.
I'm attaching a copy of the "Perldoc indexer's HOWTO", for those who
need more information.
This is a thread where people who volunteer to do the indexing can
coordinate their efforts. Maybe we can use a wiki or something like that
at some point but, for now, this is the situation:
* perlop - almost done
* perlsyn - I'm starting it
Post to the list when you start working on a document. Post the patch
when done.
Good luck!
Ivan
PERLDOC INDEXER'S GUIDE
Thanks for your interest in helping index Perl's core documentation!
This guide lists the steps you should follow to become a Perldoc Indexer (tm).
I - 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
II - 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://search.cpan.org/perldoc?Pod::Index
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. ;-)
III - 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 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
IV - 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
[EMAIL PROTECTED]
If you decide to "take" a document, just send an email to the list. When you
are done, send an email with the patch.
AUTHOR
Ivan Tubert-Brohman <[EMAIL PROTECTED]>
