Refine the todo entry for install.html
authorNicholas Clark <nick@ccl4.org>
Thu, 29 Mar 2012 20:46:17 +0000 (22:46 +0200)
committerNicholas Clark <nick@ccl4.org>
Tue, 24 Apr 2012 08:51:55 +0000 (10:51 +0200)
Update the description of what needs doing. The splitting code exists, but
it's sub-optimal and not re-usable. Correct the name of the Makefile target -
it's 'install.html' with a period, not 'installhtml'.

Porting/todo.pod

index 3e02484..130f5fa 100644 (file)
@@ -176,7 +176,7 @@ base...
 
 =head2 make HTML install work
 
 
 =head2 make HTML install work
 
-There is an C<installhtml> target in the Makefile. It's marked as
+There is an C<install.html> target in the Makefile. It's marked as
 "experimental". It would be good to get this tested, make it work reliably, and
 remove the "experimental" tag. This would include
 
 "experimental". It would be good to get this tested, make it work reliably, and
 remove the "experimental" tag. This would include
 
@@ -190,19 +190,23 @@ and the core documentation (files in F<pod/>)
 
 =item 2
 
 
 =item 2
 
-Work out how to split C<perlfunc> into chunks, preferably one per function
-group, preferably with general case code that could be used elsewhere.
+Improving the code that split C<perlfunc> into chunks, preferably with
+general case code added to L<Pod::Functions> that could be used elsewhere.
+
 Challenges here are correctly identifying the groups of functions that go
 together, and making the right named external cross-links point to the right
 Challenges here are correctly identifying the groups of functions that go
 together, and making the right named external cross-links point to the right
-page. Things to be aware of are C<-X>, groups such as C<getpwnam> to
-C<endservent>, two or more C<=items> giving the different parameter lists, such
-as
-
-    =item substr EXPR,OFFSET,LENGTH,REPLACEMENT
-    =item substr EXPR,OFFSET,LENGTH
-    =item substr EXPR,OFFSET
-
-and different parameter lists having different meanings. (eg C<select>)
+page. Currently this works reasonably well in the general case, and correctly
+parses two or more C<=items> giving the different parameter lists for the
+same function, such used by C<substr>. However it fails completely where
+I<different> functions are listed as a sequence of C<=items> but share the
+same description. All the functions from C<getpwnam> to C<endprotoent> have
+individual stub pages, with only the page for C<endservent> holding the
+description common to all. Likewise C<q>, C<qq> and C<qw> have stub pages,
+instead of sharing the body of C<qx>.
+
+Note also the current code isn't ideal with the two forms of C<select>, mushing
+them both into one F<select.html> with the two descriptions run together.
+Fixing this may well be a special case.
 
 =back
 
 
 =back