2002-10-10 Phil Edwards <pme@gcc.gnu.org>

	* docs/html/21_strings/howto.html:  Write #5, char_traits.
	* docs/html/17_intro/porting.texi:  Expand on os_include_dir.
	* docs/html/17_intro/porting.html:  Regenerate.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@58031 138bc75d-0d04-0410-961f-82ee72b054a4

4 files changed, 84 insertions, 15 deletions

diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index 5f1afaade75..d3e936ae1df 100644
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,3 +1,9 @@
+2002-10-10  Phil Edwards  <pme@gcc.gnu.org>
+
+	* docs/html/21_strings/howto.html:  Write #5, char_traits.
+	* docs/html/17_intro/porting.texi:  Expand on os_include_dir.
+	* docs/html/17_intro/porting.html:  Regenerate.
+
 2002-10-09  Benjamin Kosnik  <bkoz@redhat.com>	
 
 	* src/locale.cc: Fix comments, move ctors together.
diff --git a/libstdc++-v3/docs/html/17_intro/porting.html b/libstdc++-v3/docs/html/17_intro/porting.html
index e791f92dc74..c28f89f407f 100644
--- a/libstdc++-v3/docs/html/17_intro/porting.html
+++ b/libstdc++-v3/docs/html/17_intro/porting.html
@@ -68,12 +68,13 @@ directory.  The important information is that there needs to be a
 directory under <code>config/os</code> to store the files for your operating
 system.
 
-<p>You'll have to change the <code>configure.target</code> file to ensure that
-your new directory is activated.  Look for the switch statement that
-sets <code>os_include_dir</code>, and add a pattern to handle your operating
-system.  The switch statement switches on only the OS portion of the
-standard target triplet; e.g., the <code>solaris2.8</code> in
-<code>sparc-sun-solaris2.8</code>.
+<p>You might have to change the <code>configure.target</code> file to ensure that
+your new directory is activated.  Look for the switch statement that sets
+<code>os_include_dir</code>, and add a pattern to handle your operating system
+if the default will not suffice.  The switch statement switches on only
+the OS portion of the standard target triplet; e.g., the <code>solaris2.8</code>
+in <code>sparc-sun-solaris2.8</code>.  If the new directory is named after the
+OS portion of the triplet (the default), then nothing needs to be changed.
 
 <p>The first file to create in this directory, should be called
 <code>os_defines.h</code>.  This file contains basic macro definitions
diff --git a/libstdc++-v3/docs/html/17_intro/porting.texi b/libstdc++-v3/docs/html/17_intro/porting.texi
index 142a354a032..6c6ec1f7f48 100644
--- a/libstdc++-v3/docs/html/17_intro/porting.texi
+++ b/libstdc++-v3/docs/html/17_intro/porting.texi
@@ -102,12 +102,13 @@ directory.  The important information is that there needs to be a
 directory under @file{config/os} to store the files for your operating
 system.
 
-You'll have to change the @file{configure.target} file to ensure that
-your new directory is activated.  Look for the switch statement that
-sets @code{os_include_dir}, and add a pattern to handle your operating
-system.  The switch statement switches on only the OS portion of the
-standard target triplet; e.g., the @code{solaris2.8} in
-@code{sparc-sun-solaris2.8}.
+You might have to change the @file{configure.target} file to ensure that
+your new directory is activated.  Look for the switch statement that sets
+@code{os_include_dir}, and add a pattern to handle your operating system
+if the default will not suffice.  The switch statement switches on only
+the OS portion of the standard target triplet; e.g., the @code{solaris2.8}
+in @code{sparc-sun-solaris2.8}.  If the new directory is named after the
+OS portion of the triplet (the default), then nothing needs to be changed.
 
 The first file to create in this directory, should be called
 @file{os_defines.h}.  This file contains basic macro definitions
diff --git a/libstdc++-v3/docs/html/21_strings/howto.html b/libstdc++-v3/docs/html/21_strings/howto.html
index b1e61015474..4a8006d38e1 100644
--- a/libstdc++-v3/docs/html/21_strings/howto.html
+++ b/libstdc++-v3/docs/html/21_strings/howto.html
@@ -340,15 +340,76 @@
 
 <hr />
 <h2><a name="5">Making strings of arbitrary character types</a></h2>
-   <p>how to work with char_traits -- in the archives, just need to
-      go through and pull the examples together
+   <p>The <code>std::basic_string</code> is tantalizingly general, in that
+      it is parameterized on the type of the characters which it holds.
+      In theory, you could whip up a Unicode character class and instantiate
+      <code>std::basic_string&lt;my_unicode_char&gt;</code>, or assuming
+      that integers are wider than characters on your platform, maybe just
+      declare variables of type <code>std::basic_string&lt;int&gt;</code>.
+   </p>
+   <p>That's the theory.  Remember however that basic_string has additional
+      type parameters, which take default arguments based on the character
+      type (called CharT here):
+      <pre>
+      template &lt;typename CharT,
+                typename Traits = char_traits&lt;CharT&gt;,
+                typename Alloc = allocator&lt;CharT&gt; &gt;
+      class basic_string { .... };</pre>
+      Now, <code>allocator&lt;CharT&gt;</code> will probably Do The Right
+      Thing by default, unless you need to do something very strange with
+      memory allocation in your characters.
+   </p>
+   <p>But <code>char_traits</code> takes more work.  The char_traits
+      template is <em>declared</em> but not <em>defined</em>.
+      That means there is only
+      <pre>
+      template &lt;typename CharT&gt;
+        struct char_traits
+        {
+            static void foo (type1 x, type2 y);
+            ...
+        };</pre>
+      and functions such as char_traits&lt;CharT&gt;::foo() are not
+      actually defined anywhere for the general case.  The C++ standard
+      permits this, because writing such a definition to fit all possible
+      CharT's cannot be done.  (For a time, in earlier versions of GCC,
+      there was a mostly-correct implementation that let programmers be
+      lazy.  :-)  But it broke under many situations, so it was removed.
+      You are no longer allowed to be lazy and non-portable.)
+   </p>
+   <p>The C++ standard also requires that char_traits be specialized for
+      instantiations of <code>char</code> and <code>wchar_t</code>, and it
+      is these template specializations that permit entities like
+      <code>basic_string&lt;char,char_traits&lt;char&gt;&gt;</code> to work.
+   </p>
+   <p>If you want to use character types other than char and wchar_t,
+      such as <code>unsigned char</code> and <code>int</code>, you will
+      need to write specializations for them at the present time.  If you
+      want to use your own special character class, then you have
+      <a href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00163.html">a lot
+      of work to do</a>, especially if you with to use i18n features
+      (facets require traits information but don't have a traits argument).
+   </p>
+   <p>One example of how to specialize char_traits is given
+      <a href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00260.html">in
+      this message</a>.  We agree that the way it's used with basic_string
+      (scroll down to main()) doesn't look nice, but that's because
+      <a href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00236.html">the
+      nice-looking first attempt</a> turned out to
+      <a href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00242.html">not
+      be conforming C++</a>, due to the rule that CharT must be a POD.
+      (See how tricky this is?)
+   </p>
+   <p>Other approaches were suggested in that same thread, such as providing
+      more specializations and/or some helper types in the library to assist
+      users writing such code.  So far nobody has had the time...
+      <a href="../17_intro/contribute.html">do you?</a>
    </p>
    <p>Return <a href="#top">to top of page</a> or
       <a href="../faq/index.html">to the FAQ</a>.
    </p>
 
 
-
 <!-- ####################################################### -->
 
 <hr />