CVS difference for ai12s/ai12-0021-1.txt

Differences between 1.4 and version 1.5
Log of other versions for file ai12s/ai12-0021-1.txt

--- ai12s/ai12-0021-1.txt	2018/12/06 00:47:18	1.4
+++ ai12s/ai12-0021-1.txt	2018/12/07 06:51:06	1.5
@@ -1,7 +1,7 @@
-!standard 11.4.1(19)                                 18-11-13    AI12-0021-1/03
+!standard 11.4.1(19)                                 18-12-06    AI12-0021-1/04
 !standard A.8.1(15)
 !standard A.8.2(1)
-!standard A.8.2(29)
+!standard A.8.2(28.3/4)
 !standard A.8.4(18)
 !standard A.8.4(20)
 !standard A.10.1(85)
@@ -39,8 +39,9 @@
 
 Add after 11.4.1(19):
 
-It is recommended that exception messages requiring non-ASCII use UTF-8
-encoding.
+NOTES
+It is recommended that exception messages requiring non-ASCII characters use 
+UTF-8 encoding.
 
 Add after A.8.1(15):
 
@@ -71,7 +72,7 @@
    -- File management
 
    procedure Create(File : in out File_Type;
-                    Mode : in File_Mode := InOut_File;
+                    Mode : in File_Mode := Out_File;
                     Name : in Wide_Wide_String := "";
                     Form : in Wide_Wide_String := "");
 
@@ -96,7 +97,7 @@
 effects described in subclause A.10.2.
 
 
-Add at the end of A.8.2:
+Add after A.8.2(28.3/4):
 
 The nested package Wide_File_Names provides operations equivalent to those in
 regular Sequential_IO except that Wide_String is used instead of String for the
@@ -153,7 +154,7 @@
 end Wide_Wide_File_Names;
 
 
-Add at the end of A.8.4:
+Add after A.8.4(20):
 
 The nested package Wide_File_Names provides operations that are the equivalent
 of those for regular Direct_IO except that Wide_String is used instead of String
@@ -209,7 +210,7 @@
 end Wide_Wide_File_Names;
 
 
-Add at the end of A.10.2:
+Add after A.10.2(5):
 
 The nested package Wide_File_Names provides operations equivalent to those in
 regular Text_IO except that Wide_String is used instead of String for the name
@@ -229,7 +230,7 @@
    -- File management
 
    procedure Create (File : in out File_Type;
-                     Mode : in File_Mode := Inout_File;
+                     Mode : in File_Mode := Out_File;
                      Name : in Wide_String := "";
                      Form : in Wide_String := "");
 
@@ -249,7 +250,7 @@
    -- File management
 
    procedure Create (File : in out File_Type;
-                     Mode : in File_Mode := Inout_File;
+                     Mode : in File_Mode := Out_File;
                      Name : in Wide_Wide_String := "";
                      Form : in Wide_Wide_String := "");
 
@@ -303,12 +304,13 @@
 Static Semantics
 
 The specification of package Wide_Directories is the same as for Directories
-(including its optional child package Hierarchical_File_Names), except that each
-occurrence of String is replaced by Wide_String.
+(including its optional child packages Information and Hierarchical_File_Names),
+except that each occurrence of String is replaced by Wide_String.
 
 The specification of package Wide_Wide_Directories is the same as for
-Directories (including its optional child package Hierarchical_File_Names),
-except that each occurrence of String is replaced by Wide_Wide_String.
+Directories (including its optional child packages Information and 
+Hierarchical_File_Names), except that each occurrence of String is replaced by 
+Wide_Wide_String.
 
 
 Add section A.17.1:
@@ -340,12 +342,11 @@
 
 The crux of this problem is that the semantics and representation of strings
 have become co-mingled. What we really need to do is to separate these; the
-problem with that mostly with retaining adequate performance.
+difficulty with that is mostly with retaining adequate performance.
 
 The way-out solution would be to declare a semi-magic Root_String interface (or
-perhaps an abstract type); the magic would be string literals (since "lvalue"s
-and indexing already can be supported with existing Ada 2012 facilities).
-Something on the line of:
+perhaps an abstract type); string literals, "lvalue"s and indexing already can 
+be supported with existing Ada 2020 facilities). Something on the line of:
 
         package General_Strings is
             type Root_String is interface with
@@ -422,11 +423,24 @@
 It was considered useful though to add child packages Wide_File_Names and
 Wide_Wide_File_Names for each I/O package, containing just those operations that
 take a filename as a parameter, and Wide_ and Wide_Wide_ versions of
-Ada.Directories, Ada.Command_Line and Ada.Environment_Variables. Also, UTF-8
-encoding should be recommended for exception messages.
+Ada.Directories, Ada.Command_Line and Ada.Environment_Variables.
 
-!ACATS test
+We do not try to add wide versions of exception messages. We want existing
+code to work unmodified. However, A wide exception would either make existing 
+syntax incompatible by making it ambiguous, or would make it painful to use 
+wide messages by not having syntax as an option. Having implementations use 
+multiple formats for exception messages would break techniques where the 
+values of objects are streamed as part of the message (a common work-around to
+attach values to a raised exception). Instead, we recommend that projects that
+require Wide_Wide_Character messages use UTF-8 encoding.
+
+Note that UTF-8 encoding needs to be applied by projects, not implementations;
+if an implementation was to use UTF-8 encoding for messages, streamed values
+would possibly be destroyed (as upper-128 characters are expanded into two 
+octets).
 
+ACATS test
+
 ACATS C-Tests are needed for the new packages (nested and otherwise).
 
 !appendix
@@ -803,5 +817,185 @@
 because it is rarely true. "identical except blah" is *not* identical, after
 all! I left the wording Jeff had.
 
+[Editor's note: These comments apply to version /03 as posted.]
+
+****************************************************************
+
+From: Jeff Cousins
+Sent: Wednesday, November 14, 2018  12:13 PM
+
+Thanks again Justin.
+
+11.4.1.(19) “non-ASCII” seems a bit too colloquial, I still prefer “non-ASCII 
+characters”.
+
+A.15.1, A.16.2 “is the same as”  seems to be the more normal RM-speak than “is 
+identical to”, e.g. A.11.
+
+Otherwise fine.
+
 ****************************************************************
 
+From: Randy Brukardt
+Sent: Wednesday, November 14, 2018  6:07 PM
+
+> 11.4.1.(19) "non-ASCII" seems a bit too colloquial, I still prefer
+"non-ASCII characters".
+
+It doesn't matter, as the term "ASCII" isn't defined for a normative 
+description of characters as it is not an ISO standard, so you shouldn't
+use it here (or anywhere in normative wording; it's OK in AARM notes).
+
+You could tie this text to the contents of the package ASCII, something 
+like "characters not present in package ASCII". But since the package ASCII 
+is obsolescent, I'd recommend against that.
+
+Ada.Characters.Handling uses "ISO_646" for this purpose (that being the ISO 
+standard in question), so you could say something like "characters not in ISO
+646" or you could even reference the subtype directly "characters not in 
+Characters.Handling.ISO_646".
+
+Finally, you could simply say what you really mean and talk about character 
+code points: "characters whose code point is greater than 127".
+
+Moral: everything about characters is harder than it seems. :-)
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Wednesday, December 5, 2018  7:10 PM
+
+Here are my technical comments on this AI:
+[Aside: "you" in most of these cases was originally Jeff, but both authors 
+share responsibility.]
+
+>Add after 11.4.1(19):
+>
+>It is recommended that exception messages requiring non-ASCII use UTF-8 
+>encoding.
+
+You have this in an Implementation Advice section. But this is advice to the 
+programmer -- the implementation cannot and must not do this on its own. (How
+would the user of Exception_Message know that it is encoded in UTF-8 if the 
+implementation did that itself? Moreover, what would that do to messages that
+include a streamed [binary] portion? Only a project can decide to use UTF-8 
+encoding universally for messages.)
+
+So this should be a user note. If it is a user note, we can be less rigorous, 
+so saying "non-ASCII" arguably would be better than "non ISO-646".
+
+Additionally, the discussion needs an explanation of why this cannot be 
+changed. (Answer: it appears in existing syntax and pragmas that would become 
+ambiguous or illegal if the definition of the message changed. That would be a
+substantial compatibility problem. Similarly, existing code that does not 
+assume UTF-8 encoding must continue to work unmodified, including code that
+encodes values into the messages; silently breaking code would be an even 
+worse compatibility problem.)
+
+---
+
+>Add at the end of A.8.2:
+
+You need to provide the paragraph number. If you had done that, you might 
+have seen that the end of this subclause is an Implementation Permissions 
+section, in which this text is totally inappropriate.
+
+---
+
+In A.16.2:
+
+>The specification of package Wide_Directories is the same as for 
+>Directories (including its optional child package 
+>Hierarchical_File_Names), except that each occurrence of String is replaced 
+>by Wide_String.
+
+I think you need to mention it's not-optional child of Information as well. 
+The contents of Information are not specified by the language, but it needs 
+to be present. (And suggested contents are given in the AARM for Windows and 
+Linux implementations.) See A.16(124/2). We don't want 
+Wide_Directories.Information to be any different than Directories.Information.
+
+****************************************************************
+
+From: Jeff Cousins
+Sent: Thursday, December 6, 2018  10:46 AM
+
+(3) You changed the default mode for Create to "InOut_File" for most of
+these packages. Jeff did have the wrong for Direct_IO and Stream_IO, but you
+have it spelled wrong (the 'o' should be in lower case). And you added it to
+Text_IO, but Text_IO doesn't even have that mode. Another change I ignored.
+
+??  The Modes I used were as per the parents, i.e. Out_File for Sequential_IO,
+InOut_File (though, as Randy says, I should have said Inout_File) for 
+Direct_IO, and Out_File for Text_IO and Stream_IO.
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Friday, December 7, 2018  12:49 AM
+
+>(3) You changed the default mode for Create to "InOut_File" for most of
+>these packages. Jeff did have the wrong for Direct_IO and Stream_IO, but you
+>have it spelled wrong (the 'o' should be in lower case). And you added it to
+>Text_IO, but Text_IO doesn't even have that mode. Another change I ignored.
+
+>??  The Modes I used were as per the parents, i.e. Out_File for Sequential_IO,
+>InOut_File (though, as Randy says, I should have said Inout_File) for 
+>Direct_IO, and Out_File for Text_IO and Stream_IO.
+
+You're right, your version was originally correct. Justin's version confused
+me enough to get them all messed up. I corrected them in a new AI version.
+
+...
+>> You have this in an Implementation Advice section ...
+>> Additionally, the discussion needs an explanation ...
+...
+>Good points.
+
+I've done both of these things.
+
+>>>Add at the end of A.8.2:
+
+>>You need to provide the paragraph number. If you had done that, you might
+>>have seen that the end of this subclause is an Implementation Permissions
+>>section, in which this text is totally inappropriate
+
+>Agreed, I don’t know how I missed it.
+
+I fixed this, too, in a new draft.
+
+>>>The specification of package Wide_Directories is the same as for Directories
+>>>(including its optional child package Hierarchical_File_Names), except that
+>>>each occurrence of String is replaced by Wide_String.
+
+>>I think you need to mention it's not-optional child of Information as well.
+>>The contents of Information are not specified by the language, but it needs
+>>to be present. (And suggested contents are given in the AARM for Windows and
+>>Linux implementations.) See A.16(124/2). We don't want
+>>Wide_Directories.Information to be any different than
+>>Directories.Information.
+
+>I must admit that the existence of child package Information had totally passed 
+>me by. Though if the underlying OS doesn’t provide any additional information, 
+>than won’t the child package not exist, or are you saying that it will exist 
+>but be empty?  If the latter, then I think it should be shown in the Static 
+>Semantics section, even if it just contains a “    ... -- not specified by the
+>language” type of comment.
+
+Restriction No_Implementation_Identifiers treats this package as 
+language-defined with implementation-defined contents, just like Machine_Code.
+That's probably the model that we should use here.
+
+This package is hidden as much as it is because we can't mention Windows or 
+Linux in the normative Standard - if we could have, we would have required
+minimum contents on those systems and allowed implementations to add to them.
+
+It's presence had escaped Robert Dewar, too, probably because he famously 
+refused to look in the AARM. Not sure if AdaCore ever fixed this oversight.
+(If I could think of a sane way to test this in the ACATS I would.)
+
+Anyway, I added it to your existing text by mentioning "optional child packages 
+Information and Hierarchical_File_Names". It's in the index, people can find 
+it if they have to.
+
+****************************************************************

Questions? Ask the ACAA Technical Agent