perl5 icon indicating copy to clipboard operation
perl5 copied to clipboard

perlapi/perlintern: Allow alphabetical browsing

Open khwilliamson opened this issue 1 year ago • 1 comments

It is a lot easier for a user to choose which function to use out of multiple similar ones when all such are combined into a single group and the pod compares and contrasts them, highlighting the nuances. The alternative is individual functions documented as silos, and the user has to jump back and and forth between them; the nuances are lost.

The problem is that this grouping can leave the document out of alphabetical order when the names of related functions don't start with the same letters. Someone who is browsing it alphabetically can easily miss things.

This commit remedies that by creating placeholder entries that are inserted in alphabetical order and point to the real documentation for the functions that aren't in alphabetical order.

It turns out that there aren't very many of these. Though that in part is because I have avoided combining some alphabetically far-away functions with their brethern for the very reason that it would make them hard to find. Examples include the functions that differ from others only in that they take an encapsulated argument list and their names begin with 'v'. vform() has not been combined with form() and its kin, but they all really belong together.

This commit means that perlapi/perlintern maintainers no longer have to consider the sorting effect of their changes.

khwilliamson avatar Aug 22 '24 11:08 khwilliamson

1 porting test failure, which should be easy to fix. Otherwise looks good, as the revisions mostly are insertions of "redirects" rather than moving chunks of text around.

Since there have been a lot of changes to the generated output in pod/perlapi.pod since perl-5.40.0, I recommend that someone take a look at comparing the before/after endpoints for readability and usability.

jkeenan avatar Aug 22 '24 13:08 jkeenan