Section A.8.2 ought to appear in the Ada RM Index for the operations described

[sttaft]

Section A.8.2, File Management, has useful descriptions of several operations applicable to almost all kinds of files. But these appear nowhere in the Index of the RM. That seems like an oversight.

[ARG-Editor]

This isn't really a "bug report", since the index is non-normative. Rather, it is handled through the informal AARM update process. I've added this topic to AI22-0005-1 where all of the AARM fixes live, and closed this topic.

[ARG-Editor]

Having looked at this more carefully, this isn't an "oversight" but rather a consequence of how the language-defined subprograms are indexed.

In particular, language-defined entities are indexed when they appear as language-defined specifications. For instance, "Create" is indexed where it appears in the specification of Text_IO. Language-defined entities are NEVER indexed where the descriptive text is located.

That doesn't make a lot of difference for most subprograms, since those things are found in the same clause, but there are some cases (like most of the I/O operations, not just A.8.2, but also all of the other operations of Sequential_IO, Direct_IO, and Text_IO; it also happens for the shared operations for map and set containers) where the descriptive text is found in a different subclause.

I believe the original indexing was chosen as not all language-defined packages have full descriptive text including a specification (for instance, the Ada.Strings packages do not repeat the subprogram definitions with the descriptive text), while all language-defined packages certainly have a specification. Additionally, the indexing operations use the surrounding package to give a reference to the associated package, that isn't reliably available for descriptions and wouldn't be available at all for operations that have shared descriptions, such as those in A.8.2 and the map and set containers.

It would make sense to change the indexing to primarily work from the descriptions rather than the specifications. But that would be a lot of work, as there are more than 1500 subprograms defined, and one would have to decide which ones could be moved and which ones could not (certainly, they all cannot be moved to the descriptions because we want to index complete specifications). And as noted above, not all of the descriptions can used the existing indexing operations; either additional operations would have to be defined or one would have to figure out ways to use existing operations. The fact that a number of different operations would be needed would also prevent any rote changes; everything would have to be considered carefully.

Given that a general change is too expensive to do (especially in our new reality of unfunded work), the only remaining question is whether A.8.2 should be handled in some special way. We could do that, but I don't see any reason to treat it differently than A.10.6 or A.18.4 or A.18.6 (or, for that matter, the one package sections of A.8.3, A.8.5, and A.10.3-A.10.12). All of those cannot be found directly from the existing indexes, you have to do some sort of search to find the descriptive material. (And really, you have to do that for all subprograms, but most are on the same page.) That puts us back to the "too much work" answer.

As such, I'm not going to do anything with this issue (other than record it as noted above).

        Randy Brukardt, ARG Editor

[sttaft]

I guess I am not totally convinced, since it is not uncommon for the same term to appear in the index with multiple page numbers, so there is no need to make a massive shift, but rather just add some additional index entries for descriptions that are separated from their specs. But I do understand the lack of funding issue, but I would hate for that to become the general reason for not making presentation improvements to the RM. I would like to keep this as a low priority presentation improvement, and we can see when or if we actually get around to implementing it.

[ARG-Editor]

... rather just add some additional index entries for descriptions that are separated from their specs.

There are likely to be at least 300 of those, and as I noted the existing indexing shortcut commands can't be used, so that would be a LOT of work. (And it really should be done for all descriptions if it is done for any.)

Moreover, I don't know how to appropriately index the items (like A.8.2) which are shared amongst multiple packages. (Including subpackages, each of these items is incorporated into the definition of 12 subprograms!). Adding an index item for each relevant package would be a substantial maintenance hazard (if any new packages ever are added), using the subprogram name alone is insufficient and inconsistent, and I can't find a phrase that works to qualify these entries.

Currently, the index contains: create, in Ada.Direct_IO

We could use something like:

create, general description

but that's not specific enough as there are other routines named Create not covered by this description. (That's even more of a problem for the Map and Set containers where there are many routines defined for all of the kinds of containers.)

Something like:

create, general description of procedures in IO packages

would be specific enough. But "IO packages" isn't a defined thing and could be confusing. Listing the packages brings back the maintenance hazard. (A.8.2 itself starts with a maintenance hazard, listing the packages involved. But that's one, visible place, not dozens of places hidden in the text.)

Moreover, this subterm is too long; these items have to fit in a 3 column format, so the length has to be quite short.

There's also the question of whether these items should appear in the Q indexes ("Language-defined entities"). If so, then additional commands are needed to put them both in the main index and in the Q index. (There are no commands specifically for adding things to the Q indexes; those are implicit in the existing short index commands, which as noted would not work here because there is no way to define the enclosing package.) Adding commands isn't hard, but it time-consuming (especially as it would be necessary to figure out exactly what would be needed before implementing anything).

Anyway, all of these things make it impractical to index these items. That probably would be true even if we had a budget (since it likely would be earmarked for more visible tasks), and is certainly true without one.

I don't see any volunteers spending multiple weeks on something that provides a fairly small benefit (after, most users search for definitions, either with Google or with our own search pages). So I don't see much point in leaving this open - there are plenty of other "nice-to-haves" that will never happen. Don't want to clutter our work list with such things.