[v3] doc updates

[v3] doc updates

[Benjamin Kosnik]

[-- Attachment #1: Type: text/plain, Size: 71 bytes --]


Regerate the html docs included in the source distribution.

-benjamin

[-- Attachment #2: 20120117-2.patch.bz2 --]
[-- Type: application/x-bzip, Size: 37989 bytes --]

[v3] doc updates

[Jonathan Wakely]

[-- Attachment #1: Type: text/plain, Size: 262 bytes --]

        * doc/xml/manual/extensions.xml: Improve markup and note that some
        extensions are included in C++11.
        * doc/xml/manual/concurrency_extensions.xml: Likewise.

Tested with 'make doc-xml-validate-docbook doc-html-docbook'

Committed to trunk

[-- Attachment #2: docs.txt --]
[-- Type: text/plain, Size: 10157 bytes --]

Index: doc/xml/manual/extensions.xml
===================================================================
--- doc/xml/manual/extensions.xml	(revision 182724)
+++ doc/xml/manual/extensions.xml	(working copy)
@@ -160,7 +160,7 @@ extensions, be aware of two things:
 <para>There are
    versions of single-bit test, set, reset, and flip member functions which
    do no range-checking.  If we call them member functions of an instantiation
-   of "bitset&lt;N&gt;," then their names and signatures are:
+   of <code>bitset&lt;N&gt;</code>, then their names and signatures are:
 </para>
    <programlisting>
    bitset&lt;N&gt;&amp;   _Unchecked_set   (size_t pos);
@@ -173,14 +173,10 @@ extensions, be aware of two things:
    no present plans to do so (and there doesn't seem to be any immediate
    reason to).
 </para>
-<para>The semantics of member function <code>operator[]</code> are not specified
-   in the C++ standard.  A long-standing defect report calls for sensible
-   obvious semantics, which are already implemented here:  <code>op[]</code>
-   on a const bitset returns a bool, and for a non-const bitset returns a
-   <code>reference</code> (a nested type).  However, this implementation does
-   no range-checking on the index argument, which is in keeping with other
-   containers' <code>op[]</code> requirements.  The defect report's proposed
-   resolution calls for range-checking to be done.  We'll just wait and see...
+<para>The member function <code>operator[]</code> on a const bitset returns
+   a bool, and for a non-const bitset returns a <code>reference</code> (a
+   nested type).  No range-checking is done on the index argument, in keeping
+   with other containers' <code>operator[]</code> requirements.
 </para>
 <para>Finally, two additional searching functions have been added.  They return
    the index of the first "on" bit, and the index of the first
@@ -214,16 +210,20 @@ extensions, be aware of two things:
      &lt;rb_tree&gt;
    </programlisting>
    <para>are all here;
-      <code>&lt;hash_map&gt;</code> and <code>&lt;hash_set&gt;</code>
+      <filename class="headerfile">&lt;backwards/hash_map&gt;</filename> and
+      <filename class="headerfile">&lt;backwards/hash_set&gt;</filename>
       are deprecated but available as backwards-compatible extensions,
-      as discussed further below.  <code>&lt;rope&gt;</code> is the
-      SGI specialization for large strings ("rope,"
-      "large strings," get it? Love that geeky humor.)
-      <code>&lt;slist&gt;</code> is a singly-linked list, for when the
-      doubly-linked <code>list&lt;&gt;</code> is too much space
-      overhead, and <code>&lt;rb_tree&gt;</code> exposes the red-black
-      tree classes used in the implementation of the standard maps and
-      sets.
+      as discussed further below.
+      <filename class="headerfile">&lt;ext/rope&gt;</filename> is the SGI
+      specialization for large strings ("rope," "large strings," get it? Love
+      that geeky humor.)
+      <filename class="headerfile">&lt;ext/slist&gt;</filename> (superseded in
+      C++11 by <filename class="headerfile">&lt;forward_list&gt;</filename>)
+      is a singly-linked list, for when the doubly-linked <code>list&lt;&gt;</code>
+      is too much space overhead, and
+      <filename class="headerfile">&lt;ext/rb_tree&gt;</filename> exposes the
+      red-black tree classes used in the implementation of the standard maps
+      and sets.
    </para>
    <para>Each of the associative containers map, multimap, set, and multiset
       have a counterpart which uses a
@@ -256,6 +256,13 @@ extensions, be aware of two things:
      </para>
    </blockquote>
 
+   <para>
+      The deprecated hash tables are superseded by the standard unordered
+      associative containers defined in the ISO C++ 2011 standard in the
+      headers <filename class="headerfile">&lt;unordered_map&gt;</filename>
+      and <filename class="headerfile">&lt;unordered_set&gt;</filename>.
+   </para>
+
   </section>
 </chapter>
 
@@ -264,36 +271,37 @@ extensions, be aware of two things:
 <?dbhtml filename="ext_utilities.html"?>
 
   <para>
-    The &lt;functional&gt; header contains many additional functors
+    The <filename class="headerfile">&lt;functional&gt;</filename> header
+    contains many additional functors
     and helper functions, extending section 20.3.  They are
     implemented in the file stl_function.h:
   </para>
   <itemizedlist>
   <listitem>
-  <para><code>identity_element</code> for addition and multiplication. *
+  <para><code>identity_element</code> for addition and multiplication.
   </para>
   </listitem>
   <listitem>
     <para>The functor <code>identity</code>, whose <code>operator()</code>
-      returns the argument unchanged. *
+      returns the argument unchanged.
   </para>
   </listitem>
   <listitem>
     <para>Composition functors <code>unary_function</code> and
       <code>binary_function</code>, and their helpers <code>compose1</code>
-      and <code>compose2</code>. *
+      and <code>compose2</code>.
     </para>
   </listitem>
   <listitem>
-  <para><code>select1st</code> and <code>select2nd</code>, to strip pairs. *
+  <para><code>select1st</code> and <code>select2nd</code>, to strip pairs.
   </para>
   </listitem>
-  <listitem><para><code>project1st</code> and <code>project2nd</code>. * </para></listitem>
+  <listitem><para><code>project1st</code> and <code>project2nd</code>. </para></listitem>
   <listitem><para>A set of functors/functions which always return the same result.  They
       are <code>constant_void_fun</code>, <code>constant_binary_fun</code>,
       <code>constant_unary_fun</code>, <code>constant0</code>,
-      <code>constant1</code>, and <code>constant2</code>. * </para></listitem>
-  <listitem><para>The class <code>subtractive_rng</code>. * </para></listitem>
+      <code>constant1</code>, and <code>constant2</code>. </para></listitem>
+  <listitem><para>The class <code>subtractive_rng</code>. </para></listitem>
   <listitem><para>mem_fun adaptor helpers <code>mem_fun1</code> and
       <code>mem_fun1_ref</code> are provided for backwards compatibility. </para></listitem>
 </itemizedlist>
@@ -320,11 +328,11 @@ you can also use
 get_temporary_buffer(5, (int*)0);
 </programlisting>
 <para>
-  A class <code>temporary_buffer</code> is given in stl_tempbuf.h. *
+  A class <code>temporary_buffer</code> is given in stl_tempbuf.h.
 </para>
 <para>
   The specialized algorithms of section 20.4.4 are extended with
-  <code>uninitialized_copy_n</code>. *
+  <code>uninitialized_copy_n</code>.
 </para>
 
 </chapter>
@@ -371,25 +379,30 @@ get_temporary_buffer(5, (int*)0);
 <chapter xml:id="manual.ext.numerics" xreflabel="Numerics"><info><title>Numerics</title></info>
 <?dbhtml filename="ext_numerics.html"?>
 
-<para>26.4, the generalized numeric operations such as accumulate, are extended
-   with the following functions:
+<para>26.4, the generalized numeric operations such as <code>accumulate</code>,
+   are extended with the following functions:
 </para>
    <programlisting>
    power (x, n);
-   power (x, n, moniod_operation);</programlisting>
-<para>Returns, in FORTRAN syntax, "x ** n" where n&gt;=0.  In the
-   case of n == 0, returns the identity element for the
+   power (x, n, monoid_operation);</programlisting>
+<para>Returns, in FORTRAN syntax, "<code>x ** n</code>" where
+   <code>n &gt;= 0</code>.  In the
+   case of <code>n == 0</code>, returns the identity element for the
    monoid operation.  The two-argument signature uses multiplication (for
    a true "power" implementation), but addition is supported as well.
    The operation functor must be associative.
 </para>
 <para>The <code>iota</code> function wins the award for Extension With the
-   Coolest Name.  It "assigns sequentially increasing values to a range.
-   That is, it assigns value to *first, value + 1 to *(first + 1) and so
-   on."  Quoted from SGI documentation.
+   Coolest Name (the name comes from Ken Iverson's APL language.)  As
+   described in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/iota.html">SGI
+   documentation</link>, it "assigns sequentially increasing values to a range.
+   That is, it assigns <code>value</code> to <code>*first</code>,
+   <code>value + 1</code> to<code> *(first + 1)</code> and so on."
 </para>
    <programlisting>
    void iota(_ForwardIter first, _ForwardIter last, _Tp value);</programlisting>
+<para>The <code>iota</code> function is included in the ISO C++ 2011 standard.
+</para>
 </chapter>
 
 <!-- Chapter 12 : Iterators -->
Index: doc/xml/manual/concurrency_extensions.xml
===================================================================
--- doc/xml/manual/concurrency_extensions.xml	(revision 182661)
+++ doc/xml/manual/concurrency_extensions.xml	(working copy)
@@ -21,7 +21,8 @@
   <section xml:id="manual.ext.concurrency.design.threads" xreflabel="Threads API"><info><title>Interface to Locks and Mutexes</title></info>
     
 
-<para>The file &lt;ext/concurrence.h&gt; contains all the higher-level
+<para>The file <filename class="headerfile">&lt;ext/concurrence.h&gt;</filename>
+contains all the higher-level
 constructs for playing with threads. In contrast to the atomics layer,
 the concurrence layer consists largely of types. All types are defined within <code>namespace __gnu_cxx</code>.
 </para>
@@ -65,14 +66,14 @@ host environment and the current compila
 interface: <code>__mutex</code>, and <code>__scoped_lock</code>.
 </para>
 
-<para>
-</para>
-
 <para>The scoped lock idiom is well-discussed within the C++
 community. This version takes a <code>__mutex</code> reference, and
-locks it during construction of <code>__scoped_locke</code> and
+locks it during construction of <code>__scoped_lock</code> and
 unlocks it during destruction. This is an efficient way of locking
 critical sections, while retaining exception-safety.
+These types have been superseded in the ISO C++ 2011 standard by the
+mutex and lock types defined in the header
+<filename class="headerfile">&lt;mutex&gt;</filename>.
 </para>
   </section>
 

[v3] doc updates

[Benjamin Kosnik]

[-- Attachment #1: Type: text/plain, Size: 81 bytes --]


Missed this doxygen update on the last check-in.

tested x86_64/linux

-benjamin

[-- Attachment #2: 20090810-3.patch.bz2 --]
[-- Type: application/x-bzip, Size: 23374 bytes --]

[v3] doc updates

[Benjamin Kosnik]

[-- Attachment #1: Type: text/plain, Size: 72 bytes --]


Bits from last week that fell through the cracks...

tested x86/linux


[-- Attachment #2: p.20040301-1.patch --]
[-- Type: text/plain, Size: 3182 bytes --]

2004-03-01  Benjamin Kosnik  <bkoz@redhat.com>

	* docs/html/test.html: Add multilib RUNTESTFLAGS example.

	* docs/html/18_support/howto.html: Add bit about writing to
	stderr, mostly by Zack.

Index: docs/html/test.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/test.html,v
retrieving revision 1.8
diff -c -p -r1.8 test.html
*** docs/html/test.html	22 Dec 2003 20:09:21 -0000	1.8
--- docs/html/test.html	1 Mar 2004 17:40:03 -0000
*************** or
*** 477,487 ****
  make check-target-libstdc++-v3 RUNTESTFLAGS="-v -v"
  </pre>
  
  There are two ways to run on a simulator: set up DEJAGNU to point to a
  specially crafted site.exp, or pass down --target_board flags.
  
  Example flags to pass down for various embedded builds are as follows:
- 
  <pre>
  --target=powerpc-eabism (libgloss/sim)
  make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=powerpc-sim"
--- 477,487 ----
  make check-target-libstdc++-v3 RUNTESTFLAGS="-v -v"
  </pre>
  
+ 
  There are two ways to run on a simulator: set up DEJAGNU to point to a
  specially crafted site.exp, or pass down --target_board flags.
  
  Example flags to pass down for various embedded builds are as follows:
  <pre>
  --target=powerpc-eabism (libgloss/sim)
  make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=powerpc-sim"
*************** make check-target-libstdc++-v3 RUNTESTFL
*** 492,498 ****
  --target=xscale-elf (newlib/sim)
  make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim"
  </pre>
!    
    <p> To run a subset of the library tests, simply edit the generated
    file, <em>testsuite_files </em>, to include only the files that are
    desired instead of all available test cases.
--- 492,505 ----
  --target=xscale-elf (newlib/sim)
  make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim"
  </pre>
! 
! <p> Also, here is an example of how to run the libstdc++ testsuite for a
! multilibed build directory with different ABI settings:
! </p>
! <pre>
! make check-target-libstdc++-v3 RUNTESTFLAGS='--target_board \"unix{-mabi=32,,-mabi=64}\"'
! </pre>
!  
    <p> To run a subset of the library tests, simply edit the generated
    file, <em>testsuite_files </em>, to include only the files that are
    desired instead of all available test cases.
Index: docs/html/18_support/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/18_support/howto.html,v
retrieving revision 1.17
diff -c -p -r1.17 howto.html
*** docs/html/18_support/howto.html	3 Feb 2004 01:26:12 -0000	1.17
--- docs/html/18_support/howto.html	1 Mar 2004 17:40:03 -0000
***************
*** 284,289 ****
--- 284,296 ----
        <a href="../faq/index.html">to the FAQ</a>.
     </p>
  
+ <p>
+    This function will attempt to write to stderr.  If your application
+     closes stderr or redirects it to an inappropriate location,
+     <code>__verbose_terminate_handler</code> will behave in an
+     unspecified manner.
+ </p>
+ 
  <hr />
  <h2><a name="5">Dynamic memory management</a></h2>
     <p>There are six flavors each of <code>new</code> and

[v3] doc updates

[Benjamin Kosnik]

[-- Attachment #1: Type: text/plain, Size: 72 bytes --]


Bits from last week that fell through the cracks...

tested x86/linux


[-- Attachment #2: p.20040301-1.patch --]
[-- Type: text/plain, Size: 3182 bytes --]

2004-03-01  Benjamin Kosnik  <bkoz@redhat.com>

	* docs/html/test.html: Add multilib RUNTESTFLAGS example.

	* docs/html/18_support/howto.html: Add bit about writing to
	stderr, mostly by Zack.

Index: docs/html/test.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/test.html,v
retrieving revision 1.8
diff -c -p -r1.8 test.html
*** docs/html/test.html	22 Dec 2003 20:09:21 -0000	1.8
--- docs/html/test.html	1 Mar 2004 17:40:03 -0000
*************** or
*** 477,487 ****
  make check-target-libstdc++-v3 RUNTESTFLAGS="-v -v"
  </pre>
  
  There are two ways to run on a simulator: set up DEJAGNU to point to a
  specially crafted site.exp, or pass down --target_board flags.
  
  Example flags to pass down for various embedded builds are as follows:
- 
  <pre>
  --target=powerpc-eabism (libgloss/sim)
  make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=powerpc-sim"
--- 477,487 ----
  make check-target-libstdc++-v3 RUNTESTFLAGS="-v -v"
  </pre>
  
+ 
  There are two ways to run on a simulator: set up DEJAGNU to point to a
  specially crafted site.exp, or pass down --target_board flags.
  
  Example flags to pass down for various embedded builds are as follows:
  <pre>
  --target=powerpc-eabism (libgloss/sim)
  make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=powerpc-sim"
*************** make check-target-libstdc++-v3 RUNTESTFL
*** 492,498 ****
  --target=xscale-elf (newlib/sim)
  make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim"
  </pre>
!    
    <p> To run a subset of the library tests, simply edit the generated
    file, <em>testsuite_files </em>, to include only the files that are
    desired instead of all available test cases.
--- 492,505 ----
  --target=xscale-elf (newlib/sim)
  make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim"
  </pre>
! 
! <p> Also, here is an example of how to run the libstdc++ testsuite for a
! multilibed build directory with different ABI settings:
! </p>
! <pre>
! make check-target-libstdc++-v3 RUNTESTFLAGS='--target_board \"unix{-mabi=32,,-mabi=64}\"'
! </pre>
!  
    <p> To run a subset of the library tests, simply edit the generated
    file, <em>testsuite_files </em>, to include only the files that are
    desired instead of all available test cases.
Index: docs/html/18_support/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/18_support/howto.html,v
retrieving revision 1.17
diff -c -p -r1.17 howto.html
*** docs/html/18_support/howto.html	3 Feb 2004 01:26:12 -0000	1.17
--- docs/html/18_support/howto.html	1 Mar 2004 17:40:03 -0000
***************
*** 284,289 ****
--- 284,296 ----
        <a href="../faq/index.html">to the FAQ</a>.
     </p>
  
+ <p>
+    This function will attempt to write to stderr.  If your application
+     closes stderr or redirects it to an inappropriate location,
+     <code>__verbose_terminate_handler</code> will behave in an
+     unspecified manner.
+ </p>
+ 
  <hr />
  <h2><a name="5">Dynamic memory management</a></h2>
     <p>There are six flavors each of <code>new</code> and

[v3] doc updates

[Benjamin Kosnik]

[-- Attachment #1: Type: text/plain, Size: 256 bytes --]

This updates the TODO list, as per 2003-01-01 and 2003-07-01 list
discussions. If I've left something out, please just add it.

I cannot figure out how to link to ../doxygen/guide.html, so I just
showed the path instead of linking. Second best.

-benjamin

[-- Attachment #2: 20031023.patch --]
[-- Type: text/plain, Size: 13282 bytes --]

2003-10-23  Benjamin Kosnik  <bkoz@redhat.com>

	* docs/html/documentation.html: Add a pointer to the doxygen style
	guide.
	* docs/html/17_intro/TODO: Update.
	* docs/html/test.html: Add instructions for running a subset of
	tests, update.

Index: docs/html/documentation.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/documentation.html,v
retrieving revision 1.36
diff -c -p -r1.36 documentation.html
*** docs/html/documentation.html	24 Jun 2003 20:33:28 -0000	1.36
--- docs/html/documentation.html	23 Oct 2003 20:34:25 -0000
***************
*** 245,250 ****
--- 245,252 ----
         - names to avoid because of potential collisions</li>
     <li><a href="17_intro/C++STYLE">C++STYLE</a>
         - coding style by example</li>
+    <li> In the libstdc++-v3/docs/doxygen directory, see guide.html, a
+        doxygen markup style guide</li>
     <li><a href="17_intro/CHECKLIST">CHECKLIST</a>
         - a list of required features and their status.</li>
     <li><a href="17_intro/DESIGN">DESIGN</a>
Index: docs/html/test.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/test.html,v
retrieving revision 1.5
diff -c -p -r1.5 test.html
*** docs/html/test.html	5 Aug 2003 01:20:15 -0000	1.5
--- docs/html/test.html	23 Oct 2003 20:34:25 -0000
*************** data		  Sample text files for testing in
*** 126,132 ****
        All new tests should be written with the policy of one test
        case, one file in mind. At some point the entire testsuite will
        be converted: the current status is that the 21_string,
!       22_locale, 27_io, and demangle directories have all been
        transitioned.
     </p>
  
--- 126,132 ----
        All new tests should be written with the policy of one test
        case, one file in mind. At some point the entire testsuite will
        be converted: the current status is that the 21_string,
!       22_locale, 23_containers, 27_io, and demangle directories have all been
        transitioned.
     </p>
  
*************** make check-target-libstdc++-v3 RUNTESTFL
*** 486,491 ****
--- 486,496 ----
  make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim"
  </pre>
     
+   <p> To run a subset of the library tests, simply edit the generated
+   file, <em>testsuite_files </em>, to include only the files that are
+   desired instead of all available test cases.
+   </p>
+ 
     <p> In addition, there are some testing options that are mostly of
     interest to library maintainers and system integrators. As such,
     these tests may not work on all cpu and host combinations, and must
Index: docs/html/17_intro/TODO
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/17_intro/TODO,v
retrieving revision 1.7
diff -c -p -r1.7 TODO
*** docs/html/17_intro/TODO	15 Aug 2002 22:25:37 -0000	1.7
--- docs/html/17_intro/TODO	23 Oct 2003 20:34:25 -0000
***************
*** 1,62 ****
! - audit for places where __builtin_expect can be used.
  
! - coordinate with "C" library people the "C" compatibility headers.
!   Explain why an ISO-14882-conformant solution is hopeless, with the current
!   twisted morass of "C" headers.
  
! - do more doxygen manpages
  
! - implement __convert_to_v and __convert_from_v without "C" library
! functions and and LANG environment variable dependencies.
  
! - use localedata to implement generic named (non-MT-safe) locales?
! Figure out a way to use ICU data, like libjava?
  
! - tuning for executable size, compilation speed, startup allocation,
! executable speed.
  
! - benchmarking addition to the testsuite that does the above.
  
! - implement testing for symbol versioning for ELF targets.
  
! - review streambuf, filebuf, stringbuf to optimize data member
! placement.  Do pback bits need to be in streambuf? How about
! _M_set_indeterminate, etc?
  
  - Think about naming all member data and member functions consistently
! as per
! funtions: _M_verb_adverb
! data: _M_noun_adjective
  
  - exception specifications need to be reviewed for all parts of the
! library support and utility areas, particularly <new>. 
  
  - scoping/linking issues WRT to C structs need to be worked out. See
  Nathan's commentary on cantrip, http://www.cantrip.org/cheaders.html
  
- - triglyphs/ciso646: and, and_eq, bitand, bitor, compl, not, not_eq,
- or, or_eq, xor, xor_eq, true && 45, true and false, true or 45, etc.
- (bool and int), etc.
- 
- - operator!= and utility/rel_ops operators need to be made safe with
- string and vector iterator classes. basic_string::reverse_iterator may
- be implemented incorrectly, or need things like
- operator==(__normal_iterator, const char*&), and swap(vector)
- 
  - auto_ptr: seems to be some disagreement on what is
  standards-conformant behavior, specially on conversion operators.
  
- - header optimizations to keep compile times reasonable are most
- certainly detracting from full conformance, as many templatized
- definitions are squired away and pre-instantiated, so that the
- compiler doesn't have to parse them. Areas effected: valarray, string,
- all of iostreams and locales.
- 
- - C-related issues WRT to libio and filepos, mbstate_t. Need to
- straighten this stuff out with the glibc-2.2 libio. Also may need to
- define operators for mbstate_t so that 'mbstate_t& == mbstate_t' is
- something that can be done.
- 
  - looks like deque::get_allocator not standards conformant or deque
  allocator non-standard.
  
--- 1,133 ----
! std::allocator
  
!   - switch to mt_allocator with --enable-threads=posix. 
  
!   - Try to figure out a way to switch allocators in a more elegant
!     manner, and make the default allocator configurable.
! 
!   - persistent allocator
! 
!   - global/extern allocator
! 
! std::string 
! 
!   - re-design for multi-paradigm, meta string class solution incorporating COW
!     vs. deep copy issues, MT scalability
!     See Andrei Alexandrescu, June 2001, C/C++ Users Journal
!     "Generic<Programming>: A Policy-Based basic_string Implementation"
!     http://www.cuj.com/documents/s=7994/cujcexp1906alexandr/
! 
!   - operator!= and utility/rel_ops operators need to be made safe with
!     string and vector iterator classes. basic_string::reverse_iterator may
!     be implemented incorrectly, or need things like
!     operator==(__normal_iterator, const char*&), and swap(vector)
! 
!   - 'do the right thing' ctor fixing needs to be done for string. This
!     is still subject to some debate on the library issues list, so I
!     suggest punting till the dust clears.
! 
!   - fix template members of basic_string<> to overload iterators and
!     non-iterators properly.  (This is the infamous hack as in vector<> etc
!     23.1.1 para 10.)
! 
! std::locale  
! 
!   - implement __convert_to_v and __convert_from_v without "C" library
!     functions and and LANG environment variable dependencies.
! 
!   - use localedata to implement generic named (non-MT-safe) locales?
!     Figure out a way to use ICU data, like libjava? Need a generic locale
!     model that does something besides the "C" locale.
! 
!   - make locale::classic() separate from named locale code. This will
!     improve the static linkage situation, but will require new
!     initialization code.
! 
!   - Jerry(?)/Paolo(?) work on __float_to_char.
! 
!   - minimize ctype convertion in data facets, see numpunct/num_put/num_get
! 
!   - finish caching data facets and using the caches
! 
! std::basic_filebuf, 27_io
! 
!   - wfilebuf, get variable-encoding working and tested, including
!     positioning and seeking.
! 
!   - wfilebuf testsuite
! 
!   - look ahead for unbuffered io, so know when multiple putc's can be
!     coalesced.
! 
!   - unlocked __basic_file + new mutext class
! 
!   - optimized the sentries for istream/ostream
! 
!   - v2 vs. v3 speed
! 
!   - add optimization hooks (esp. whitespace eating) to streambuf
!   - add _M_begin() and _M_end() to streambuf
!   - add algorithm specializations for [io]streambuf_iterator (copy find etc.)
! 
! testsuite
! 
!   - valgrind hooks into make check so can tell memory leakage
!     Some commentary on the valgrind users list
! 
!   - add hooks for qmtest for visual diffs 
! 
!   - automatic testing of interactive tests
! 
!   - diffing generated output files
! 
!   - make check-abi needs to have full symbol checking. Scope the LSB
!     testsuite, see what's going on with the typeinfo etc. bits.
  
!   - provide testsuites for numerics.
  
!   - try to do a better job of ABI testing, with instantiations of all
!     standard-specified types checked, not just exported symbols.
  
! g++/binutils
  
!   - compression for wide versions of basic types
  
! - get Apple's debug mode, or something with equivalent functionality, in.
  
! - audit for places where __builtin_expect can be used.
! 
! - relocations, work on getting these down
! 
! - issues with __builtin_memcpy and std::copy from Jerry Quinn
!   http://gcc.gnu.org/ml/libstdc++/2003-02/msg00076.html
! 
! - fix dependency tracking for includes (.h, .tcc) during build process.
! 
! - coordinate with "C" library people the "C" compatibility headers.
  
  - Think about naming all member data and member functions consistently
!   as per
!   funtions: _M_verb_adverb
!   data: _M_noun_adjective
! 
! - A C++STYLE guide that deals with nested namespaces, and that
! everybody can live with.
  
  - exception specifications need to be reviewed for all parts of the
! library support and utility areas, particularly <new>. Part of this is
! a standards issue, where the 27_io bugs/standard is really in an odd
! spot.
! 
! - C-related issues WRT to io and filepos, mbstate_t. Seeking in wide
! streams. May need to define operators for mbstate_t so that
! 'mbstate_t& == mbstate_t' is something that can be done.
  
  - scoping/linking issues WRT to C structs need to be worked out. See
  Nathan's commentary on cantrip, http://www.cantrip.org/cheaders.html
  
  - auto_ptr: seems to be some disagreement on what is
  standards-conformant behavior, specially on conversion operators.
  
  - looks like deque::get_allocator not standards conformant or deque
  allocator non-standard.
  
*************** needs to be drawn throughout the entire 
*** 67,113 ****
  
  - priority_queue conversions may be non-conformant
  
- - 'do the right thing' ctor fixing needs to be done for string. This
- is still subject to some debate on the library issues list, so I
- suggest punting till the dust clears.
- 
  - Protect valarray::result_type (not Standard) and make it work with
    the various helper classes.
  
  - Make sure `valarray<bool> & == _Expr<_BinClos<logical_or,_ValArray,_ValArray,double,double>,bool>' 
    is defined
  
- - known issues WRT to io and corner cases with the buffers. This is
- still subject to interpretation, and I think the current
- implementation is credible.
- 
  - All of the Library working group closed issues need to be
  addressed. Some of them proposed resolutions are already in the v-3
! sources, with macro-guards.
  
  - add deprecated features from Annex D
    - add #ifdef wrappers for all of them, including in each
      C <xxx.h> header
    - replace typedef'd non-deprecated types with more type-safe equivalents.
  
- - add optimization hooks (esp. whitespace eating) to streambuf
-   - add _M_begin() and _M_end() to streambuf
-   - add algorithm specializations for [io]streambuf_iterator (copy find etc.)
- 
- - fix template members of basic_string<> to overload iterators and
-   non-iterators properly.  (This is the infamous hack as in vector<> etc
-   23.1.1 para 10.)
- 
- - write filebuf for wide characters
- 
  - add feature-test macros for non-standard extensions
  
! - create MT abstraction layer
  
  - add MT support for locale, string, istream, ostream
  
! - provide testsuites for numerics.
  
  - add FAQ entries -- improve the install instructions
  
  - add HOWTO entries
--- 138,172 ----
  
  - priority_queue conversions may be non-conformant
  
  - Protect valarray::result_type (not Standard) and make it work with
    the various helper classes.
  
  - Make sure `valarray<bool> & == _Expr<_BinClos<logical_or,_ValArray,_ValArray,double,double>,bool>' 
    is defined
  
  - All of the Library working group closed issues need to be
  addressed. Some of them proposed resolutions are already in the v-3
! sources, with macro-guards. Also, same with the TR.
  
  - add deprecated features from Annex D
    - add #ifdef wrappers for all of them, including in each
      C <xxx.h> header
    - replace typedef'd non-deprecated types with more type-safe equivalents.
  
  - add feature-test macros for non-standard extensions
  
! - create MT abstraction layer for atomicity to pthreads.
  
  - add MT support for locale, string, istream, ostream
  
! - need to think about doing a .texi or DocBook manual, instead of all
! these HTML pages. In addition, it would be nice to have a full manual,
! instead of a lot of ad-hoc pages. Weaknesses include numerics, locale,
! and io.
  
  - add FAQ entries -- improve the install instructions
  
  - add HOWTO entries
+ 
+ - do more doxygen manpages
+ 

[v3] doc updates

[Benjamin Kosnik]

Simple

2002-03-19  Benjamin Kosnik  <bkoz@redhat.com>

	* docs/html/faq/index.html: Add OS X workaround.
	* docs/html/17_intro/TODO: Update.


Index: docs/html/17_intro/TODO
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/17_intro/TODO,v
retrieving revision 1.5
diff -c -p -r1.5 TODO
*** TODO	2002/01/31 02:05:17	1.5
--- TODO	2002/03/19 17:14:32
***************
*** 1,4 ****
--- 1,8 ----
+ - audit for places where __builtin_expect can be used.
+ 
  - coordinate with "C" library people the "C" compatibility headers.
+   Explain why an ISO-14882-conformant solution is hopeless, with the current
+   twisted morass of "C" headers.
  
  - do more doxygen manpages
  
Index: docs/html/faq/index.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/faq/index.html,v
retrieving revision 1.32
diff -c -p -r1.32 index.html
*** index.html	2002/03/06 21:22:50	1.32
--- index.html	2002/03/19 17:14:35
***************
*** 61,66 ****
--- 61,67 ----
           <li><a href="#3_4">I can't use 'long long' on Solaris</a>
           <li><a href="#3_5"><code>_XOPEN_SOURCE</code> /
                              <code>_GNU_SOURCE</code> / etc is always defined</a>
+          <li><a href="#3_6">OS X ctype.h is  broken! How can I hack around it?
        </ol>
  
     <li><a href="#4_0">Known Bugs and Non-Bugs</a>
*************** which is no longer available, thanks dej
*** 466,471 ****
--- 467,480 ----
        </p>
        <p>This method is something of a wart.  We'd like to find a cleaner
           solution, but nobody yet has contributed the time.
+       </p>
+ 
+ <hr>
+    <h2><a name="3_6">3.6 OS X ctype.h is broken! How can I hack around it?</h2>
+       <p>This is a long-standing bug in the OS X support. Fortunately,
+       the patch is quite simple, and well-known. Here's a link to the
+       solution:
+       <a href="http://gcc.gnu.org/ml/gcc/2002-03/msg00817.html">yay!</a>
        </p>
  
  <hr>

[v3] doc updates

[Benjamin Kosnik]

Before I tell someone else to RTFM I should make sure it's formatted
correctly...

:)

2002-01-22  Benjamin Kosnik  <bkoz@redhat.com>

	* docs/html/22_locale/messages.html: Remove angle brackets.
	* docs/html/17_intro/TODO: Add.

Index: docs/html/17_intro/TODO
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/17_intro/TODO,v
retrieving revision 1.3
diff -c -p -r1.3 TODO
*** TODO	2001/12/18 22:01:20	1.3
--- TODO	2002/01/23 02:00:59
***************
*** 1,3 ****
--- 1,20 ----
+ - do doxygen manpages
+ 
+ - implement __convert_to_v and __convert_from_v without "C" library
+ functions and and LANG environment variable dependencies.
+ 
+ - use localedata to implement generic named (non-MT-safe) locales?
+ Figure out a way to use ICU data, like libjava?
+ 
+ - tuning for executable size, compilation speed, startup allocation,
+ executable speed.
+ 
+ - benchmarking addition to the testsuite that does the above.
+ 
+ - thread testing addition to the testsuite.
+ 
+ - implement symbol versioning for ELF targets.
+ 
  - exception specifications need to be reviewed for all parts of the
  library support and utility areas, particularly <new>. 
  
*************** needs to be drawn throughout the entire 
*** 41,56 ****
  is still subject to some debate on the library issues list, so I
  suggest punting till the dust clears.
  
- - complex<float> seems to be the single largest source of internal
- compiler errors when compiling the c++ library across non-x86
- platforms. Somebody needs to make sure the complex support builtin to
- gcc is actually working. Just as a "for-instance" these things give ICEs:
- class complex<float>& complex<float>::operator-=<float>(const complex<float> &)
- class complex<float>& complex<float>::operator/=<float>(const complex<float> &)
- class complex<float>& complex<float>::operator+=<float>(const complex<float> &)
- class complex<float>& complex<float>::operator-=<float>(const complex<float> &)
- class complex<float>& complex<float>::operator*=<float>(const complex<float> &)
- 
  - Protect valarray::result_type (not Standard) and make it work with
    the various helper classes.
  
--- 58,63 ----
*************** sources, with macro-guards.
*** 81,88 ****
  - write filebuf for wide characters
  
  - add feature-test macros for non-standard extensions
- 
- - move major extensions into separate namespace (e.g. stl::)
  
  - create MT abstraction layer
  
--- 88,93 ----
Index: docs/html/22_locale/messages.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/22_locale/messages.html,v
retrieving revision 1.2
diff -c -p -r1.2 messages.html
*** messages.html	2001/09/17 23:24:39	1.2
--- messages.html	2002/01/23 02:00:59
*************** correspond to three protected virtual me
*** 39,45 ****
  The public member functions are:
  
  <p>
! <code>catalog open(const basic_string<char>&, const locale&) const</code>
  
  <p>
  <code>string_type get(catalog, int, int, const string_type&) const</code>
--- 39,45 ----
  The public member functions are:
  
  <p>
! <code>catalog open(const string&, const locale&) const</code>
  
  <p>
  <code>string_type get(catalog, int, int, const string_type&) const</code>
*************** The public member functions are:
*** 51,57 ****
  While the virtual functions are:
  
  <p>
! <code>catalog do_open(const basic_string<char>&, const locale&) const</code>
  <BLOCKQUOTE>
  <I>
  -1- Returns: A value that may be passed to get() to retrieve a
--- 51,57 ----
  While the virtual functions are:
  
  <p>
! <code>catalog do_open(const string&, const locale&) const</code>
  <BLOCKQUOTE>
  <I>
  -1- Returns: A value that may be passed to get() to retrieve a