!topic LSN on Annex Organization !key LSN-1073 on Annex Organization !reference RM9X-A;4.0 !from Bob Duff $Date: 94/01/31 14:48:59 $ $Revision: 1.4 $ !discussion We have gotten several comments on the organization of the annexes and the content of the "summary" annexes A, B, D, E, and F. The latter issue was discussed at the recent DR/XRG meeting in the UK. This LSN discusses these issues. Currently, the summary annexes only contain summaries of information in the core language. Annex A does not contain any of the attributes defined in the Real-Time Annex, for example. It was agreed at the UK meeting that it should. In addition, annexes A, B, and D should be in alphabetical order. It is customary to place summary material at the end of a document, just before the index. This was of course done in RM83. However, RM9X puts the summary annexes *before* a whole bunch of non-summary material (annexes G through N). This makes the document more difficult to use. The summary annexes should be moved toward the end. If the summary annexes summarize information from annexes G..N, this is even more important -- it makes no sense to summarize something you haven't seen yet. The only argument against a more sensible organization is that people have gotten used to the annex letters. However, there are several counter-arguments: - For the annexes that are new to Ada 9X, the number of people that are intimately familiar with the lettering is small compared to the number of eventual users of the document. (If that's not true, this whole project is failure!) - For the annexes that already existed in Ada 83, I think it is likely that the main thing people are "used to" is finding the summary material near the end. It's annoying to get used to the fact that Ada 83 put them at the end, and then have that property broken by Ada 9X. That expectation is increased by the fact that most books other than the Ada RM also do it that way. (After all, there are very few people who read *only* the Ada RM, and no other books!) - There's little harm in moving the Predefined Language Environment annex elsewhere. It has changed so much from the Ada 83 version that it's hard to believe anybody is used to what it now contains. Now is our last chance to have a sensible organization for the RM -- let's do it. If we don't, we will be stuck with a bad organization for the next decade. Many people currently think that Annex M is one of the Specialized Needs Annexes. It is not. However, it looks like it is, because it appears near the other S.N. Annexes (G..L). This confusion could be alleviated by a better organization. Here's a concrete proposal, which has the core-language annexes, followed by the S.N. annexes, followed by the obsolescent features annex, followed by the summary annexes, followed by the index. A. Predefined Language Environment (was C) B. Interface to Other Languages (was M) C. Systems Programming (was G) D. Real-Time Systems (was H) E. Distributed Systems (was I) F. Information Systems (was J) G. Numerics (was K) H. Safety and Security (was L) I. Obsolescent Features (was N) J. Language-Defined Attributes (was A) K. Language-Defined Pragmas (was B) L. Glossary (was D) M. Syntax Summary and Cross Reference (was E) N. Implementation-Defined Characteristics (was F) Index I think the above order is a logical one. One will easily be able to flip to the reference material at the end (J..N and the Index). It will be easy to remember that A..I are normative, whereas J..N are non-normative. It will be easy to remember that (of the normative ones), A..B are core, whereas C..I are Specialized Needs. Easier, at least, than in the version 4.0 organization. Some minor details: The Attributes Annex should include a single alphabetical list of attributes -- they should not be split up by core vs. S.N. annex, because the person looking up an attribute might not know whether it's a core attribute or not. The entry for that attribute, once found, will specify core vs. S.N. annex (via the "see..." phrase that currently appears at the end of the entry). The same comment (single alphabetical list) applies to the Pragmas and Glossary annexes. Currently, the floating- and fixed-point attributes are split out into A.1 and A.2, which seems like a bad idea. The reason is that this is the only place these are defined -- it's not a summary. We should change these attributes to the way all the others are done -- definition in one place, summary in the Attributes annex. If this proves to be too verbose, we can easily shorten the descriptions in the summary version, and point to the real definitions for the gory details. (There are a lot of details in those attributes!) The "real" definitions could be moved to 3.5.8 and 3.5.10. A.1 and A.2 currently comprise just under 4 pages. The "picture" of the hierarchy of predefined library units shown at the beginning of the Predef. Lang. Env. annex could be alphabetized, if people think that would be a better organization. So far, I've heard one opinion in favor of that, and none against. The Glossary currently duplicates just about everything in 1.3, Definitions. I think the Definitions section is less useful, because it hits you with a bunch of daunting stuff at the front, before you're ready, and it is in a non-traditional place for a reference section. We should substantially shorten 1.3, and beef up the Glossary. (We can't get rid of 1.3 -- it's required by ISO. But ISO rules allow it to be very short.) The cover of the RM9X currently says: Ada 9X Reference Manual The Language The Standard Libraries It's nice to split things up between the Language and the Standard Libraries -- a given piece of functionality in a Standard Library is usually far simpler than the same piece of functionality as a built-in language feature. In general, people see big languages as bad (complex), but big libraries as good (a rich set of features). In Ada, the "libraries" basically consist of the language-defined library units, pragmas, and attributes. (These are the things that implementations are also allowed to define, and that we allow ourselves to define in the S.N. Annexes.) The Standard Libraries thus comprise everything in chapter 14, and annexes A..I above. There should be a divider page between chapters 13 and 14 announcing that one is entering the "Standard Libraries". This amounts to about half of the document. Some people have suggested making chapter 14 into an annex (either its own annex, or part of the Predefined Language Environment annex. This would achieve the nice property that "Language" is numbered chapters, whereas "Libraries" is lettered annexes. I think it's a good idea, but I fear that this may be going too far. If we do it, I prefer making it a separate annex (immediately following Predef. Lang. Env.), since it is so big. Also, it avoids problems with too-deeply-nested section numbers. While I'm at it, I might as well say that I think the Design Goals and Language Summary (which appear before the table of contents) seems unhelpful to me -- it merely increases the size of the RM without imparting much useful information. Perhaps we could be shorten it, and bury it somewhere in chapter 1. (IMHO, part I, section 3 of that Rationale, titled "Overview of the Ada Language" is a better introduction to Ada.)