autodoc: Add an Index section

[khwilliamson]

perlapi and perlintern are divided into sections that partition the API elements into rough major categories of related functions. This causes an Index to be generated, a mapping from function name to the section it's documented in.

[tonycoz]

This produces pod like:

 Atof                                             Numeric Functions
 AV                                               AV Handling
 av_clear                                         AV Handling
 av_count                                         AV Handling
 av_create_and_push                               AV Handling
 av_create_and_unshift_one                        AV Handling
 av_delete                                        AV Handling
 av_dump                                          Debugging
 av_exists                                        AV Handling
 av_extend                                        AV Handling
 av_fetch                                         AV Handling
 av_fill                                          AV Handling
 AV_FROM_REF                                      SV Handling
 av_len                                           AV Handling
 av_make                                          AV Handling
 av_pop                                           AV Handling
 av_push                                          AV Handling

but in many cases this will be viewed as HTML, it would be nice if:

• each API name linked to its entry
• each section name linked to that section.

This would require switching away from verbatim text, but I think that would be a positive, with the massive indentation caused by some[1] names it's difficult to track across from any vaguely short API name to the section name.

Your typical book index doesn't attempt to line up the page numbers.

[1] mostly the WARN_DEPRECATED|EXPERIMENTAL macros

[jkeenan]

@tonycoz, while I'm sympathetic to some of your concerns, I don't think the output generated from the latest force-commit is an improvement. When I either view pod/perlapi.pod via perldoc or first convert it to text with pod2text and look at it in an editor, I see this:

INDEX
    Below is an alphabetical list of all API elements in this file, cross
    referenced to the section in which they are documented.

    "alloccopstash"    "Optrees"
    "amagic_call"    "GV Handling and Stashes"
    "amagic_deref_call"    "GV Handling and Stashes"
    "aMY_CXT"    "XS"
    "aMY_CXT_"    "XS"
    "_aMY_CXT"    "XS"
    "apply_builtin_cv_attributes"    "Source Filters"
    "ARCHLIB"    "Site configuration"

An admittedly crude processing of the output via pod2html produces similarly ugly results. If we're to have this index at all (and I'm not convinced it's worth it), I'd go with @khwilliamson's original approach.

[tonycoz]

Yeah, I'm not sure it's worth having an index.

Where does the user use an index? Do they have better options.

Use case: finding an API by name.

Using perldoc or man, I'd expect the user to just /api_name

For the web, the user could also {Ctrl-F} name, but there's still some likelihood of the user seeing an INDEX in the Contents and following that to the list of APIs. It was this use case that led to me suggesting making links.

Use case: browsing APIs

This seems to me to be much less likely than searching for an API by name, but I can see someone trying to find an API that does X, where X is a synonym for the term that the Perl API uses to document the API.

The index collects all of the names in the one place, and a user could browse the list hoping to spot a likely API, if the user does find such an API, and for the browser making it linkable would save a step in jumping to the documentation for the API, and would allow the user to use the back button to get back to the index.

The unlinked index is probably more useable (more readable) for man/perldoc users.

Are there other use cases for the index I haven't noticed?

[khwilliamson]

Another use case is to just look around to see what is available. After I looked at this generated index, I learned several useful things existed that I hadn't known about.

I consider the "browsing APIs" use case sufficient to want to put this in core. We have a number of too clever by half API names, where the name and purpose aren't so obvious. One that has been in our news lately is GIMMME. I had need to find what context I had been called in, wasn't sure that functionality for that existed at the C level, and found this by scanning the index. And it clicked; I knew this years ago, but had forgotten it existed. (For the record, GIMME_V is the preferred form.)

The index comes at the end of a long document, and I don't see how it interferes with the current uses of the document. You just don't get that far into the document to notice it.

I think it would be a lot easier to read if the pod formatting didn't put in those unnecessary double quote characters. I can't figure out a way to avoid them.

As a side note, the GIMME forms are particularly egregious examples of poor naming. I would have thought the term was slang, but looking it up just now, it isn't. It is less than 100 years old in English. Nonetheless, it is likely a word that a non-native English speaker would have to look up. It is kind of cheeky (another word I would have thought to be slang) and hence kind of appealing, but isn't all that close to the intended functionality. There is a tension between short and clever terms whose meaning is lost on some, and the longer tedious ones that I tend to come up with, that more precisely describe things, but occupy too many characters in the line. I think these go too far towards the obscure