s-wchcnv.adb: Document handling of [ on output (we do not change this to ["5B"] and the new...

2006-02-17  Robert Dewar  <dewar@adacore.com>

	* s-wchcnv.adb: Document handling of [ on output (we do not change
	this to ["5B"] and the new comments say why not.

	* gnat_ugn.texi: 
	Add note for -gnatVo that this now includes the cases of type
	conversions and qualified expressions.
	Add comments on handling of brackets encoding for Text_IO

From-SVN: r111198

gcc/ada/gnat_ugn.texi

@@ -5275,7 +5275,8 @@ Arguments for predefined operators and attributes are validity checked.
 This includes all operators in package @code{Standard},
 the shift operators defined as intrinsic in package @code{Interfaces}
 and operands for attributes such as @code{Pos}. Checks are also made
-on individual component values for composite comparisons.
+on individual component values for composite comparisons, and on the
+expressions in type conversions and qualified expressions.
 
 @item -gnatVp
 @emph{Validity checks for parameters.}

gcc/ada/s-wchcnv.adb

@@ -6,7 +6,7 @@
 --                                                                          --
 --                                 B o d y                                  --
 --                                                                          --
---          Copyright (C) 1992-2005, Free Software Foundation, Inc.         --
+--          Copyright (C) 1992-2006, Free Software Foundation, Inc.         --
 --                                                                          --
 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
 -- terms of the  GNU General Public License as published  by the Free Soft- --
@@ -411,9 +411,26 @@ package body System.WCh_Cnv is
             end if;
 
          when WCEM_Brackets =>
+
+            --  Values in the range 0-255 are directly output. Note that there
+            --  is some issue with [ (16#5B#] since this will cause confusion
+            --  if the resulting string is interpreted using brackets encoding.
+
+            --  One possibility would be to always output [ as ["5B"] but in
+            --  practice this is undesirable, since for example normal use of
+            --  Wide_Text_IO for output (much more common than input), really
+            --  does want to be able to say something like
+
+            --     Put_Line ("Start of output [first run]");
+
+            --  and have it come out as intended, rather than contaminated by
+            --  a ["5B"] sequence in place of the left bracket.
+
             if Val < 256 then
                Out_Char (Character'Val (Val));
 
+            --  Otherwise use brackets notation for vales greater than 255
+
             else
                Out_Char ('[');
                Out_Char ('"');