Version 1.2 of ais/ai-00440.txt

Unformatted version of ais/ai-00440.txt version 1.2
Other versions for file ais/ai-00440.txt

!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 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)
Insert new clause:
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)
Insert new clause:
This clause lists all language-defined packages.
!corrigendum Q.2(01)
Insert new clause:
This clause lists all language-defined types and subtypes.
!corrigendum Q.3(01)
Insert new clause:
This clause lists all language-defined subprograms.
!corrigendum Q.4(01)
Insert new clause:
This clause lists all language-defined exceptions.
!corrigendum Q.5(01)
Insert new clause:
This clause lists all language-defined constants, variables, named numbers, and enumeration literals.
!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.  :)

*************************************************************


Questions? Ask the ACAA Technical Agent