|CC:||rjbs [...] cpan.org|
|Subject:||[META] make installhtml a non-experimental target|
|Date:||Mon, 21 Jan 2013 11:25:52 -0500 (EST)|
|To:||perlbug [...] perl.org|
|From:||rjbs [...] cpan.org|
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 1. Checking that cross linking between various parts of the documentation works. In particular that links work between the modules (files with POD in F<lib/>) and the core documentation (files in F<pod/>) 2. 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 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.