!standard M (1) 05-05-05 AI95-00425/02 !standard M.1(1) !standard M.2(1) !standard M.3(1) !class presentation 05-04-06 !status Amendment 200Y 05-04-06 !status ARG Approved 8-1-2 05-04-17 !status work item 05-04-06 !status received 05-04-06 !priority Medium !difficulty Easy !subject Organization of Annex M !summary Annex M needs a better organization. !question The purpose of Annex M is to list the documentation requirements for an Ada implementation, but it is is poorly organized for this purpose. First, the title is "Implementation-Defined Characteristics". But this is really about summarizing the documentation requirements, which cover more than just implementation-defined characteristics. For instance, some Documentation Requirements are mixed in with the implementation-defined characteristics, and others are just left out. It seems that Documentation Requirements are different than implementation-defined characteristics - some are more about characteristics of the target environment, for instance. Indeed, the requirement to document implementation-defined items is in fact a Documentation Requirement. Annex M is also very vague about some characteristics. For instance, M(54) requires documentation of "Implementation-defined aspects of storage pools." This sounds very scary. It turns out, however, that it is only a requirement to document the alignments required for a user-defined storage pool, and a requirement to document the behavior of the standard storage pool (all of the other issues were covered by other bullets in the list). That's a lot less scary. For another example, the Annex simply says that whether Implementation Advice is followed should be documented, leaving both the implementer and reader to look up all of the advice. The reader cannot tell if the information given by the implementer is complete without referring to the entire Standard. !recommendation Retitle Annex M as "Summary of Documentation Requirements"; then split it into three subclauses: M.1 Specific Documentation Requirements; M.2 Implementation-Defined Characteristics; and M.3 Implementation Advice. Add summaries of all of the Documentation Requirements and Implementation Advice to the appropriate sections. Remove any Documentation Requirements from the list of Implementation-Defined Characteristics, and improve summaries that are too vague. !wording (See corrigendum.) !discussion Some Documentation Requirements echo implementation-defined characteristics mentioned earlier in a clause. In this case, we only include the Documentation Requirements in the Annex, as these are usually more detailed. On the other hand, Implementation Advice which is similar to implementation-defined characteristics or Documentation Requirements is repeated. Usually, such Advice is adding additional suggestions to existing requirements, and it is necessary to document the suggestions as well as the requirements. Note that the detailed summaries are generated semi-automatically from the text of the AARM, and thus are not included here. !corrigendum M(01) @drepl The Ada language allows for certain machine dependences in a controlled manner. Each Ada implementation must document all implementation-defined characteristics. @dby The Ada language allows for certain target machine dependences in a controlled manner. Each Ada implementation must document many characteristics and properties of the target system. This International Standard contains specific documentation requirements. In addition, many characteristics that require documentation are identified throughout this International Standard as being implementation defined. Finally, this International Standard requires documentation of whether implementation advice is followed. The following clauses provide summaries of these documentation requirements. !corrigendum M.1(01) @dinsc In addition to implementation-defined characteristics, each Ada implementation must document various properties of the implementation: @xbullet<[List of documentation requirements here]> !corrigendum M.2(01) @dinsc The Ada language allows for certain machine dependences in a controlled manner. Each Ada implementation must document all implementation-defined characteristics: @xbullet<[List of characteristics here]> !corrigendum M.3(01) @dinsc This International Standard sometimes gives advice about handling certain target machine dependences. Each Ada implementation must document whether that advice is followed: @xbullet<[List of advice here]> !ACATS test None needed. !appendix ****************************************************************