!standard Q (00) 05-10-21 AI95-00440/01 !standard Q.1 (00) !standard Q.2 (00) !standard Q.3 (00) !standard Q.4 (00) !standard Q.5 (00) !standard Q.6 (00) !class amendment 05-10-21 !status Amendment 200Y 05-10-21 !status WG9 Approved 06-06-09 !status ARG Approved 11-0-0 05-11-19 !status work item 05-10-21 !status received 05-10-17 !priority Medium !difficulty Easy !subject Index of language-defined entities !summary A new Annex is defined to contain the lists of language-defined entities. !problem There is a main index entry entitled "Language-Defined Subprograms", followed by a list of every subprogram defined in the language. This list is very long, and it makes the index hard to use. A list like this will necessarily take many pages, and someone who is flipping through the index to try to find a particular entry, and who comes across this sublist with many entries beginning with different letters, will have no idea that they're in the L section of the index. This just seems like a bad thing to do to an index. !recommendation (See summary.) !wording Annex Q {informative} Language-Defined Entities This annex lists the language-defined entities of the language. A list of language-defined library units can be found in Annex A, "Predefined Language Environment". Q.1 Language-Defined Packages This clause lists all language-defined packages. Q.2 Language-Defined Types and Subtypes This clause lists all language-defined types and subtypes. Q.3 Language-Defined Subprograms This clause lists all language-defined subprograms. Q.4 Language-Defined Exceptions This clause lists all language-defined exceptions. Q.5 Language-Defined Objects This clause lists all language-defined constants, variables, named numbers, and enumeration literals. !discussion !corrigendum Q(01) @dinsc This annex lists the language-defined entities of the language. A list of language-defined library units can be found in Annex A, "Predefined Language Environment". !corrigendum Q.1(01) @dinsc This clause lists all language-defined packages. @xbullet<[list of packages]> !corrigendum Q.2(01) @dinsc This clause lists all language-defined types and subtypes. @xbullet<[list of types]> !corrigendum Q.3(01) @dinsc This clause lists all language-defined subprograms. @xbullet<[list of subprograms]> !corrigendum Q.4(01) @dinsc This clause lists all language-defined exceptions. @xbullet<[list of exceptions]> !corrigendum Q.5(01) @dinsc This clause lists all language-defined constants, variables, named numbers, and enumeration literals. @xbullet<[list of objects]> !ACATS test This is an informative annex, and as such does not require any tests. !appendix !topic Huge sublists in index !reference RM05 index !from Adam Beneschan 05-09-07 !discussion In the currently available version of RM05 (www.adaic.com/standards/rm-amend/html/AA-TOC.html), the first paragraph in the Index says, "A list of all language-defined subprograms may be found under Language-Defined Subprograms." Later on, there is a main index entry entitled "Language-Defined Subprograms", followed by a list of every subprogram defined in the language. When I saved this to a text file from the web site, this list contained 1149 lines. (Some of the entries take two lines.) I really question whether it's a good idea to put this entire list in the index in this form. My feeling is that doing so will make the index unusable when the manual is printed. A list like this will necessarily take many pages, and someone who is flipping through the index to try to find a particular entry, and who comes across this sublist with many entries beginning with different letters, will have no idea that they're in the L section of the index. This just seems like a bad thing to do to an index. May I humbly suggest that this list of subprograms be put somewhere else? (Maybe Language-Defined Library Units and Language-Defined Types---154 and 216 lines respectively---should be moved also.) ************************************************************* From: Adam Beneschan Sent: Wednesday, September 7, 2005 3:28 PM > In the currently available version of RM05 > (www.adaic.com/standards/rm-amend/html/AA-TOC.html) Minor correction: I meant www.adaic.com/standards/ada06.html, but if you go to that web page and then to "Annotated Ada 2006 Reference Manual", the above link is the "Contents" link. ************************************************************* From: Pascal Leroy Sent: Thursday, September 8, 2005 1:13 AM > May I humbly suggest that this list of subprograms be put > somewhere else? (Maybe Language-Defined Library Units and > Language-Defined Types---154 and 216 lines > respectively---should be moved also.) I must say that I agree with Adam. I have always found these long lists of predefined units/subprograms annoying in the Ada 95 index, but with the addition of numerous new predefined units in Ada 2005, the lists seem to be getting out of hand. I am not really concerned about saving paper, but Adam is right in pointing out that this is likely to make the entire index very hard to use, which is a pity. It's also worth pointing out that the subprogram Foo in package Bar shows up not only under "Language-Defined Subprogram" but also in its own right as "Foo in Bar". Lots of noise for someone flipping through the index. It seems to me that the best approach would be to remove all references to predefined units and subprograms from the normal index, and have a second index (say "Index of Language-Defined Entities") where all these references would be gathered. Unfortunately, this probably requires quite a bit of work on the tools used to produce the RM, and that may not be feasible at this late date. We'll see what Randy thinks. ************************************************************* From: Jean-Pierre Rosen Sent: Thursday, September 8, 2005 2:10 AM I strongly support that. People looking for where "get_line" is defined are not the same as the ones who want all references to "freezing rules" ... ************************************************************* From: Bob Duff Sent: Thursday, September 8, 2005 8:54 AM > I must say that I agree with Adam. I have always found these long lists > of predefined units/subprograms annoying in the Ada 95 index, but with the > addition of numerous new predefined units in Ada 2005, the lists seem to > be getting out of hand. I think these long lists would be easy to read if there were column headers at the top of each column, so you know you're in the middle of a long list. Without column headers, I agree that it's hard to find things -- I find myself doing a binary search within the long list, when I _think_ I'm searching the whole index. Or maybe headers like most dictionaries, telephone books, etc have, so you can search for the page first, and then search within a page. If this is too much for Randy's tools, then I wouldn't mind deleting the "Language-Defined Subprograms" entry. It's not all that useful. But I have found some of the other "long lists" to be quite useful. E.g., I'm trying to design, say, the freezing rules, and I need a list of all the "gizmos" so I can make sure I covered them all. Same thing when I'm trying to implement something, and want to cover all the cases. > I am not really concerned about saving paper, but Adam is right in > pointing out that this is likely to make the entire index very hard to > use, which is a pity. It's also worth pointing out that the subprogram > Foo in package Bar shows up not only under "Language-Defined Subprogram" > but also in its own right as "Foo in Bar". Lots of noise for someone > flipping through the index. > > It seems to me that the best approach would be to remove all references to > predefined units and subprograms from the normal index, and have a second > index (say "Index of Language-Defined Entities") where all these > references would be gathered. You mean remove the "Foo in Bar" entries, too? I don't like that idea. I really hate books that have multiple indices. The index should be useful to people who don't understand what they're looking for. Somebody who has never programmed in Ada, and wants to find out how to free memory might look up "free". That person should not have to know whether freeing memory in Ada is done by a predefined subprogram, or built in syntax, or whatever else. I find that when I use a book with multiple indices, I end up having to look the same thing up in each index. Very annoying. ************************************************************* From: Georg Bauhaus Sent: Thursday, September 8, 2005 1:36 PM > I think these long lists would be easy to read if there were column > headers at the top of each column, so you know you're in the middle of a > long list. The TeX book distinguishes index entries by using fixed-width type for control sequence names and the like, and roman type for everything else. Primitives of TeX have a '*' before them in addition to the fixed-width type. ************************************************************* From: Randy Brukardt Sent: Wednesday, September 21, 2005 10:55 PM > It seems to me that the best approach would be to remove all references to > predefined units and subprograms from the normal index, and have a second > index (say "Index of Language-Defined Entities") where all these > references would be gathered. Unfortunately, this probably requires quite > a bit of work on the tools used to produce the RM, and that may not be > feasible at this late date. We'll see what Randy thinks. I don't think ISO would let us have two indexes. But I suppose we could add another Annex (Annex Q) that would have the same effect. (After all, Annex P is essentially a dedicated index.) That would take some work in the tools, of course, but these things all have dedicated commands already. So it would only take (1) a new command to create the new Annex; and (2) redoing the implementations of the existing commands to write into that Annex (those implementations are pretty short - a page or so each - so changing them shouldn't be bad). Probably a couple of days work (mainly to figure out what it should look like). I do think we'd need a consensus to add such an Annex. Is there anyone here that would *oppose* such an Annex??? > I think these long lists would be easy to read if there were column > headers at the top of each column, so you know you're in the middle of a > long list. Without column headers, I agree that it's hard to find > things -- I find myself doing a binary search within the long list, > when I _think_ I'm searching the whole index. > Or maybe headers like most dictionaries, telephone books, etc have, > so you can search for the page first, and then search within a page. The Index is just a long list of entries, which Word then formats into the result that you see. I don't think Word has the capabilities that you mention (we're using the existing one to put the section name into the footer, but of course in this case, that's "Index"). > If this is too much for Randy's tools, then I wouldn't mind deleting the > "Language-Defined Subprograms" entry. It's not all that useful. I guess I'd like to get rid of them from the main index: A separate Annex containing this material would be more useful, and we probably could format it better as well (certainly we wouldn't need to use the very narrow columns of the main index). > You mean remove the "Foo in Bar" entries, too? > I don't like that idea. I really hate books that have multiple > indices. The index should be useful to people who don't understand what > they're looking for. Somebody who has never programmed in Ada, and > wants to find out how to free memory might look up "free". That person > should not have to know whether freeing memory in Ada is done by a > predefined subprogram, or built in syntax, or whatever else. I think you've used a bad example, because if you look up "free" in the Ada index, you won't get to Unchecked_Deallocation. :-) > I find that when I use a book with multiple indices, I end up having to > look the same thing up in each index. Very annoying. But I agree with your point. Moreover, we repeat the syntax in this index, even though it also has a dedicated index. The same should be true of language-defined entities. It's the list of Language-Defined xxxx that is very annoying, because they're out of the normal order. I've wanted to get rid of them ever since I first saw them (back when I was originally creating the tools), even through they can be useful at times. So I propose: --- Adding Annex Q to index language-defined items (probably in a similar format to the existing lists, except with longer lines); --- Removing the "Language-Defined xxx" headers and all of their contents from the main index. But leave the "xxx in yyy" entries, just like we index "exit_statement". Comments? Brickbats? ************************************************************* From: Christoph Grein Sent: Thursday, September 22, 2005 12:17 AM >So I propose: > --- Adding Annex Q to index language-defined items (probably in a similar >format to the existing lists, except with longer lines); > --- Removing the "Language-Defined xxx" headers and all of their contents >from the main index. But leave the "xxx in yyy" entries, just like we index >"exit_statement". > >Comments? Brickbats? > Randy, I think these are two excellent ideas. I always feel annoyed by the "out of order" entries when browsing the index. ************************************************************* From: Tucker Taft Sent: Thursday, September 22, 2005 9:06 AM Sounds good to me. And I hope your vacation was nice... ************************************************************* From: Bob Duff Sent: Thursday, September 22, 2005 10:02 AM > I do think we'd need a consensus to add such an Annex. Is there anyone here > that would *oppose* such an Annex??? Yes, I think it would be better to simply delete the long lists that people are griping about. Annex Q would cost Randy's time, which is scarce enough, and add pages to an already-too-thick book. I doubt if I would ever look in Annex Q. But I don't feel strongly about that. > The Index is just a long list of entries, which Word then formats into the > result that you see. I don't think Word has the capabilities that you > mention (we're using the existing one to put the section name into the > footer, but of course in this case, that's "Index"). Yeah. If MS-Word can't do that, I'd do all the work in earlier tools, which generate semi-formatted input to Word. But I suspect that's too much trouble for you. > I think you've used a bad example, because if you look up "free" in the Ada > index, you won't get to Unchecked_Deallocation. :-) Actually, I think I will. ;-) I'll glance down the page a few lines, and I'll see "freeing storage", which points to 13.11.2(1). There are also entries for "Deallocate" and "deallocation of storage". > So I propose: > --- Adding Annex Q to index language-defined items (probably in a similar > format to the existing lists, except with longer lines); > --- Removing the "Language-Defined xxx" headers and all of their contents > from the main index. But leave the "xxx in yyy" entries, just like we index > "exit_statement". I agree with the second bullet (whether or not you add Annex Q). ************************************************************* From: Dan Eilers Sent: Thursday, September 22, 2005 10:59 AM > Yes, I think it would be better to simply delete the long lists that > people are griping about. Annex Q would cost Randy's time, which is > scarce enough, and add pages to an already-too-thick book. I doubt if I > would ever look in Annex Q. I would like to second this point about the already-too-thick book. Draft 13 is 790 pages (in 7x9 format), which is 141% of the Ada95 RM. Can publishers even handle paperbacks that large without the spine breaking or not opening flat? Annex Q seems like a good thing to jettison since we would be retaining the "Foo in Bar" entries, and we will have the online version for easy text searches. I would much rather jettison Annex Q than have to reduce the font size enough to save the same number of pages. ************************************************************* From: Pascal Leroy Sent: Friday, September 23, 2005 4:07 AM Why not let the publishers deal with the publishing issues and mind our own business? The inclusion of Annex Q should be stand on its own merit, not on imaginary difficulties with the book production. I am looking at my bookshelves at the moment and I have quite a few paperbacks in the 800-page range that seem to be doing OK. The largest paperback I have is The Mathematica Book published by Cambridge University Press, it has 1400+ pages and is in excellent condition after 7 years of pretty intense use. The next time you visit your local technical bookstore, take a look at the Java or Windows shelves and you'll see that publishers know how to make really huge books these days. ************************************************************* From: Marius Amado Alves Sent: Friday, September 23, 2005 8:22 AM My opinion is: include Annex Q, or improve the existing index, or both. Improve the existing index by printing the two entry levels more differently. As indicated before, indentation only is not enough. Use different fonts, font sizes, line heights. Or draw a vertical line at the left so indentation stands out. Or both. ************************************************************* From: Randy Brukardt Sent: Friday, September 23, 2005 1:18 PM > Why not let the publishers deal with the publishing issues and mind our > own business? The inclusion of Annex Q should be stand on its own merit, > not on imaginary difficulties with the book production. And in any case we're talking about a net change in pages of -4..+4. Out of 790 pages, that isn't going to make the slightest impact on a publisher (especially as books are generally printed 16 or 32 pages at a time). ************************************************************* From: Dan Eilers Sent: Friday, September 23, 2005 1:55 PM > And in any case we're talking about a net change in pages of -4..+4. Out of > 790 pages, that isn't going to make the slightest impact on a publisher > (especially as books are generally printed 16 or 32 pages at a time). Maybe you could print annex Q on the spine. It sounds like there will be plenty of room. :) *************************************************************