Version 1.2 of si99s/si99-0030-1.txt

Unformatted version of si99s/si99-0030-1.txt version 1.2
Other versions for file si99s/si99-0030-1.txt

!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.

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



Questions? Ask the ACAA Technical Agent