[MacPerl-Porters] [PATCHES] BuildHelpIndex revisited

Chris,

I recently noticed that there's a problem in Shuck with the lookup of 
"-X", "-f", "-d" etc. (file tests). This lookup is expected to work, 
but Shuck regrets and displays an error message. I've tracked this 
problem down to the "MacPerl Help" index file, which doesn't contain 
a valid value for the key "-X" and its aliases "-f", "-d" etc.

Normally, the BuildHelpIndex script should create these entries, but 
it doesn't, because it gets confused by a formatting code. The file 
tests are documented in perlfunc.pod, and the raw pod looks like this


=item I<-X> FILEHANDLE

=item I<-X> EXPR

=item I<-X>

blah blah blah ...


Most likely, the I<> formatting code has been added to more recent 
versions of perlfunc.pod. But the BuildHelpIndex script doesn't 
expect and hence cannot handle these formatting codes. As a result, 
it creates a key "I", which causes the lookup problems. (You'll 
notice some

File ':BuildHelpIndex'; Line 189
# "-X" undefined, <INDEX> line 8385.

warnings, when BuildHelpIndex runs).

To fix this problem, formatting codes must be expanded (in the same 
way Shuck will expand them). Since parsing of formatting codes isn't 
trivial, I've written a subclass to Pod::Parser, which will do the 
job. The BuildHelpIndex script was written to look for lines 
beginning with "=index" and "=head[1234]", only these will go into 
the index. Hence, the subclass parser does some preprocessing: It 
parses the pod file (perlfunc, perlop etc.), strips all unnecessary 
textblocks, and then creates an "index" file which only contains the 
required "=index" and "=head[1234]" lines, where all formatting codes 
have been expanded. This "index" file is then used as input for the 
BuildHelpIndex algorithm. After preprocessing of the above example, 
it sees

=item -X FILEHANDLE

=item -X EXPR

=item -X

and does the right thing (tm), i.e. creates a key "-X".


Moreover, Shuck doesn't index bullet and numbered lists. While bullet 
list are excluded already, the new BuildHelpIndex script now also 
excludes numbered lists (this avoids keys like "1", "2", "0x10" etc.).

I've also  found a typo in MacPerl.podhelp.  perlop.pod contains a 
section "Range Operators", but not "Range Operator" (maybe this was 
changed recently). Hence, aliasing ".." to "Range Operator" doesn't 
work (you'll see a undefined warning).


While a patch for MacPerl.podhelp is included here, the patch for 
BuildHelpIndex comes attached as .sit, since it contains a lot of 
non-ASCII chars (send off-list only).


***MacPerl.podhelp

Note: Patched against MacPerl 5.7.3

diff -ru MacPerl.podhelp.orig MacPerl.podhelp
--- MacPerl.podhelp.orig	Sat May 25 18:12:19 2002
+++ MacPerl.podhelp	Mon Jun  3 20:42:53 2002
@@ -180,7 +180,7 @@
  @alias	^	Bitwise Or and Exclusive Or
  @alias 	&&	C-style Logical And
  @alias	||	C-style Logical Or
-@alias 	..	Range Operator
+@alias 	..	Range Operators
  @alias 	?	Conditional Operator
  @alias	:	Conditional Operator
  @alias	=	Assignment Operators

__END__ of patch



Best regards,

--Thomas