ChangeLogTag:Thu Nov 15 12:43:31 2001 Nanbor Wang <nanbor@cs.wustl.edu>

1 files changed, 31 insertions, 21 deletions

diff --git a/docs/wchar.txt b/docs/wchar.txt
index d0137598c7a..14c0d9e5ce0 100644
--- a/docs/wchar.txt
+++ b/docs/wchar.txt
@@ -16,21 +16,21 @@ the best names I can come up with for now).
 
 @subsection wchar_nosupport No Support
 
-By default, ACE will not use wchar_t at all.  This is for platforms where 
-wchar_t does not exist or support for it is pretty flakey.  
+By default, ACE will not use wchar_t at all.  This is for platforms where
+wchar_t does not exist or support for it is pretty flakey.
 
 @subsection wchar_regular Regular Support
 
 If ACE_HAS_WCHAR is defined, then ACE classes will be expanded to have extra
 methods which take in wchar_t strings.  Note that all the methods available
-with No Support are also available here.  This is the default in Windows 
+with No Support are also available here.  This is the default in Windows
 right now, and has been tested to work on Linux and VxWorks (well, only been
-tested to compile/link of VxWorks).  
+tested to compile/link of VxWorks).
 
 @subsection wchar_full Full Support
 
 Full support is turned on if ACE_HAS_WCHAR and ACE_USES_WCHAR are defined.
-Like Regular Support, both char and wchar_t versions of some methods are 
+Like Regular Support, both char and wchar_t versions of some methods are
 available, but unlike Regular Support, other methods that have char arguments
 or return values may have wchar_t arguments or return values.
 
@@ -43,18 +43,28 @@ are several other macros that are important when using wide character support
 in ACE.
 
 These other macros are used in code to conditionally switch between char and
-wchar_t.  ACE_TCHAR is a char normally and wchar_t when ACE_USES_WCHAR is 
-defined.  ACE_TEXT ("foo") expands to "foo" normally and L"foo" when 
-ACE_USES_WCHAR is defined.  
+wchar_t.  ACE_TCHAR is a char normally and wchar_t when ACE_USES_WCHAR is
+defined.  ACE_TEXT ("foo") expands to "foo" normally and L"foo" when
+ACE_USES_WCHAR is defined.
 
-ACE_TEXT_CHAR_TO_TCHAR and ACE_TEXT_WCHAR_TO_TCHAR are used when a string 
+ACE_TEXT_CHAR_TO_TCHAR and ACE_TEXT_WCHAR_TO_TCHAR are used when a string
 that is always a char or wchar_t string needs to be converted to a ACE_TCHAR
 string.  On the same note, ACE_TEXT_ALWAYS_CHAR is used when a string is
-ACE_TCHAR * and needs to be a char * string.  
+ACE_TCHAR * and needs to be a char * string.
 
 ACE_TEXT_WIDE ("foo") is unique in that it always maps to L"foo".  It is not
 a conditional macro.
 
+For string constants in code, ACE_TEXT and ACE_LIB_TEXT are used to put the
+Unicode prefix (Usually 'L') before the string when needed.  By default both
+are controlled by ACE_USES_WCHAR.
+
+All ACE code except for the ACE library should use ACE_TEXT.  ACE_LIB_TEXT
+was introduced as a short-term fix for backwards compatibility purposes.
+This allows ACE_TEXT to be overriden to act just like TEXT in Microsoft
+Windows while not affecting ACE's interface.  In the future ACE_LIB_TEXT and
+this backwards compatibility will be deprecated and removed.
+
 Finally, on Windows there are a bunch of ACE_TEXT_Apicall type macros which
 are used to choose the correct version of a Win32 API function depending on
 ACE_USES_WCHAR.  I'm hoping to remove these by adding a new ACE_OS_Win32
@@ -65,15 +75,15 @@ done.
 
 One of the more troublesome aspect of supporting wide and Ansi strings is
 the fact that the format strings for ACE_DEBUG and family always had to have
-ACE_TEXT (or ACE_LIB_TEXT) around them.  
+ACE_TEXT (or ACE_LIB_TEXT) around them.
 
 Now this should not be the case, since ACE_Log_Msg was extended to support
 both types of format strings concurrently.  This is okay, but when strings
 are printed out via the format_string, care has to be taken.
 
-It is interesting how Unix and Windows treats the format specifiers 
+It is interesting how Unix and Windows treats the format specifiers
 differently, based on their history.  Win32 uses %s, %c, %S and %C, whereas
-Linux seems to use %s, %c, %ls, and %lc.  And they even treat %s and %c 
+Linux seems to use %s, %c, %ls, and %lc.  And they even treat %s and %c
 differently.  The route ACE takes is a bit of a mixture of both:
 
 - %c: prints out an Ansi character
@@ -82,16 +92,16 @@ differently.  The route ACE takes is a bit of a mixture of both:
 - %w: prints out a Wide character
 - %W: prints out a Wide string
 
-An example, which will also function correctly even when ACE_USES_WCHAR is 
+An example, which will also function correctly even when ACE_USES_WCHAR is
 defined:
 
 @verbatim
 void print (char *a_str, wchar_t *w_str, ACE_TCHAR *t_str)
 {
-    ACE_DEBUG ((LM_DEBUG, 
-                "%C %s %W\n", 
-                a_str, 
-                t_str, 
+    ACE_DEBUG ((LM_DEBUG,
+                "%C %s %W\n",
+                a_str,
+                t_str,
                 w_str));
 }
 @endverbatim
@@ -109,10 +119,10 @@ The way I'd recommend doing this is to add the typdefs to config.h.
 
 @subsection wchar_legacy Legacy Support
 
-Most of the old macros (ACE_HAS_UNICODE, ACE_HAS_MOSTLY_UNICODE_APIS) are 
-ignored by default by ACE, since the new macros replaced them.  If 
+Most of the old macros (ACE_HAS_UNICODE, ACE_HAS_MOSTLY_UNICODE_APIS) are
+ignored by default by ACE, since the new macros replaced them.  If
 ACE_LEGACY_MODE is defined, there is an attempt to map them to the new scheme
 by just ACE_HAS_UNICODE == ACE_HAS_WCHAR and ACE_HAS_MOSTLY_UNICODE_APIS ==
-ACE_USES_WCHAR.  
+ACE_USES_WCHAR.
 
 */