!standard 1.3 07-11-10 SI99-0030-1/01 !standard (all) !class binding interpretation 07-11-10 !status work item 07-11-10 !status received 07-11-10 !priority Medium !difficulty Easy !qualifier Omission !subject Add definition section to the standard !summary The ISO documentation drafting standard recommends (but doesn't require) a definition section. We should consider adding this section to the ASIS standard. !question Should we add a definition section to the ASIS standard? (Two options) !recommendation Update section 1.3 to reference the Ada 2005 standard versus the Ada95 standard. Add missing acronyms to the Glossary. There are then two possible options to complete this SI, listed below. !wording Change the first sentence of section 1.3 to: For the purposes of this International Standard, the terms and definitions given in ISO/IEC 8652:1995(E) and the following apply. (note that the Ada95 standard references should be updated globally for a few other instances.) Add the following definitions to the Annex A Glossary section: CASE, DII, IDL, IEC, ISO, JTC, and ORB. The existing ASIS definition will be reformatted as below along with any others added to this section in alphabetical order. ASIS - is used in reference to the acronym Ada Semantic Interface Specification. it is also used in reference to the Ada package Asis. Option 1: The above changes are the only changes to be made. This is the minimal change to the existing standard. Option 2: If we want a Terms and Definitions section, with all definitions, this should still be section 1.3. The changes outlined above will still be made. Additionally the Glossary annex would be moved to this section so that all terms and definitions are here versus in an annex. !discussion The drafting standard says that a definitions section is optional, but it doesn't make clear whether that is because to have definitions is optional or whether splitting them out is optional. (The Ada standard assumes the latter.) We agree that making a separate definitions section is important, ASIS doesn't have many definitions anyway. Which clause is it? Some standards have it in 2 and some in 4. Anyway, it should be a clause near the top. Actually, it could replace the current 1.3. Greg will decide (and create this section and an SI to match). Initially I decided that as section "1.3 Terms and Definitions" already has a single definition for ASIS itself this is where additional definitions should be added. Research of issue: Section 1.3 states: For the purposes of this International Standard, the terms and definitions given in ISO/IEC 8652:1995 and the following apply. (This needs to be updated to reference the Ada 2005 standard.) The next paragraph starts: Additional terms are defined throughout this International Standard, indicated by italic type.... I scanned the standard through Annex A (the Glossary) and found the following unique italicized items: ASIS, environment, context, unit, containers, element, explicit, implicit, erroneous, trait, ancestors, descendants, supporters and family. All but ASIS (as an acronym), erroneous and trait are defined in the Annex A Glossary. ASIS already exists in section 1.3. Trait is a secondary part of the Trait_Kind definition, of section 3.9.5 and does not appear to need a secondary definition. Erroneous is defined in the Ada standard and this is referenced as a source of term definitions in the first paragraph of section 1.3 Thus there is no need for a separate (new) definition section. Prior to section 1 the following acronyms are defined and used: ISO, IEC, JTC, ORB, DII, IDL and CASE. All but CASE are accompanied by their definition. CASE or all of these could be added to the existing glossary. !appendix From: Randy Brukardt Sent: Thursday, November 29, 2007 4:01 PM Greg sent the attached SI for posting (which hasn't been done yet, but I have assigned the number). [This is version /01 of the SI - ED] Greg mentioned that he would like to have ARG comments on it so that he might be able to have a final version in time for the next meeting. So please comment on it, especially on which of the two choices is preferred. **************************************************************** From: Randy Brukardt Sent: Thursday, November 29, 2007 4:08 PM Having removed my ARG administrator hat and put on my ARG member hat, here is my comments: My understanding of the ARG meeting decision was that we wanted a separate definitions section (and not an annex). So I think I would vote for option 2. But, I would be dubious that a glossary section (usually written for comprehension, not preciseness) would necessarily have the correct *formal* definitions. I would expect that each definition would need to be checked to see if it is precise enough for a formal definition (note that this is a problem with the existing ASIS standard as it is). **************************************************************** From: Tucker Taft Sent: Thursday, November 29, 2007 6:58 PM Option 2 works for me as well. **************************************************************** From: Robert A. Duff Sent: Thursday, November 29, 2007 7:09 PM I can't comment on the ISO rules and regulations, but I generally find documents easier to read if terms are defined at the "appropriate" place, rather than being dumped all near the front. I guess that's a vote mildly in favor of option 1. **************************************************************** From: Edmond Schonberg Sent: Thursday, November 29, 2007 8:42 PM I prefer 1 as well. I agree with Bob's "locality of reference" choice, but I also think that Randy's comment about the state of the glossary is relevant: the definitions there are relatively informal, and it will be additional work to make them rigorous enough. Let's keep to the simplest necessary changes here. **************************************************************** From: Greg Gicca Sent: Friday, November 30, 2007 9:37 AM Ok. We have a tie so far. I also vote for option 1 since this will leave the document more compatible with the previous version. Of course my vote doesn't count when we really vote. Any other opinions? **************************************************************** From: Tucker Taft Sent: Thursday, November 29, 2007 10:20 AM I'm convinced. I'll switch my vote to #1. **************************************************************** From: Randy Brukardt Sent: Friday, November 30, 2007 11:19 AM The original issue was whether we needed to separate the definitions out to meet the ISO rules. My understanding of the conclusion of the meeting discussion was that the ISO documents weren't crystal clear, but that we wanted to be on the safe side and make a separate definitions clause. I don't see how option (1) fulfills that understanding. It was plenty clear (to me at least) that in the absense of ISO issues we don't need to do anything (which is what option (1) does; there is no meaningful change to the existing clause); the ASIS Standard uses the style that the Ada Standard does, and it works fine. There is a definitions clause, but it doesn't contain any definitions. If we didn't want to change that, there was no reason to waste any time looking at this issue. (Yes, there is a minor issue with the broken reference to the Ada Standards, but since those occur throughout the ASIS standard, that's a separate issue that Greg needs to deal with -- and there are quite a bit more of these.) If we want to be on the safe side and follow typical ISO practice (and the one specified by the ISO templates, but not by the actual drafting standard - which is ambiguous), then we have to have all of the definitions in clause 1.3 (or some other non-Annex clause -- the Glossary does not count). If not, then we should simply vote SI-30 No Action, because no action is needed (or worthwhile). P.S. Here's the wording from the most recent ISO template that I have (2.1). The Terms and definitions clause is an optional element giving definitions necessary for the understanding of certain terms used in the document. The following introductory wording shall be used where all terms and definitions are given in the document itself: "For the purposes of this document, the following terms and definitions apply." In the case where terms defined in one of more other documents also apply (for example, in the case of a series of associated documents where Part 1 specifies the terms and definitions for several or all of the parts), the following introductory wording shall be used, altered as necessary: "For the purposes of this document, the terms and definitions given in . and the following apply." Rules for the drafting and presentation of terms and definitions are given in the ISO/IEC Directives, Part 2, 2001[1], annex C, and in ISO 10241[3]. **************************************************************** From: Erhard Ploedereder Sent: Saturday, December 1, 2007 7:49 AM It has been my understanding that the definitions clause is intended particularly/primarily to identify definitions that are taken from elsewhere (add citations) or are deemed to have multiple interpretations in common understanding. For "local" definitions, it is often too difficult to extract them into context-free space. To create a mix, some are here, some are in the text, would be the worst of all worlds. Count this as a vote in favor of Option 1. Clearly, at least a generic reference to the Ada Standard 2005 is needed in 1.3 to create the tie to the syntactic categories and semantic concepts. Maybe there are a few more needed. I certainly do not like the present haphazard composition of Annex A; there doesn't seem to be any rhyme or reason for what made it into the Glossary and what did not. **************************************************************** From: Robert A. Duff Sent: Saturday, December 1, 2007 9:53 AM >...but that we > wanted to be on the safe side and make a separate definitions clause. My advice, based on my Ada 9X experience, is don't try to be on the safe side. If you want to do something for good reason, see if you can get away with it, and fix it when and only when you get caught by the official ISO Nitpicker. Send the document to said Nitpicker ahead of time. I suspect they find errors no matter what you do. But the Nitpicker looks ONLY at the first few pages. If the Ada RM defines "task" in chap 9, the Nitpicker will not complain about it, because he doesn't read chap 9. The idea of defining "task" and "discriminant" and "dispatching operation" all together at the front (in alphabetical order?) is ludicrous -- and I'm sure a similar comment applies to ASIS. The ISO standards about standards are pretty silly. Does the reader of the International Standard for Tensile Strength of Steel Girders derive some benefit from the fact that the International Ada Standard is written in the same style? A foolish consistency is the hobgoblin of little minds. -- R. W. Emerson **************************************************************** From: John Barnes Sent: Sunday, December 2, 2007 2:03 AM Well I quite like an informal glossary with references to the proper local definition. It's helpful for a newcomer to a document. They should be in both places in my view. ****************************************************************