I've re-ordered bits of your message to group parts
On Tue, Jul 26, 2005 at 02:52:47PM -0400, Ivan Tubert-Brohman wrote:
> First, a definition. By "scope", I mean the part of the document that is
> deemed relevant to an index entry, and that may be extracted and shown
> in isolation by a processing or display tool. For example, perldoc -f
> considers the scope of a function to end at the beginning of the next
> =item, or at the end of the enclosing =over.
> * There's no limitation as to the number of times that a given entry can
> appear in a document or collection of documents. That is, it is not an
> error to have X<whatever> appear twice in the same file.
This means that if two or more adjacent paragraphs are needed to make sense,
it's no problem under the scope rules - just mark both.
> Currently it is used in only *one* place in the perl documentation:
> pod/perlfunc.pod uses it for the "-X" filetest operators.
> * It should be considered case-insensitive.
This would lead to some ambiguities:
-b File is a block special file.
-B File is a "binary" file (opposite of -T).
-c File is a character special file.
-C Same for inode change time (Unix, may differ for other platforms)
-s File has nonzero size (returns size in bytes).
-S File is a socket.
-t Filehandle is opened to a tty.
-T File is an ASCII text file (heuristic guess).
I'm not sure if this is really a problem
> Perl comes with over 100 files in the pod/ directory, totaling over
> 100,000 lines of POD. Obviously, indexing all of it by hand is a very
> large task, so the question arises as to who will do it. If people agree
> that this is a good idea and are willing to apply the patches, I could
> lead the project, and hope to attracting volunteers. In the worst case
> (no one else is willing to help), I believe that even if I can't index
> *all* of the pods, a partial index is better than no index at all. I
> would start with the documents that I consider more important, such as
> perlop, perlsub, perlre, perlobj, etc. Documents such as perldelta* and
> the faqs probably don't need indexing that much.
Potentially the faqs do. The deltas might benefit from it, particularly if
searching for a topic on a recent set of documentation brings up an important
bug fix in a specific version of perl, and the user realises that there perl
is older than this.
The proposal seems very well thought through, and I'd be very happy to see
you start on this soon. I'd hope that you'd soon attract volunteers to help,
but as you rightly say, only time will tell.
Nicholas Clark
