2008-02-10 Benjamin Kosnik <bkoz@redhat.com>

	Convert documentation to DocBook.
	* doc/Makefile.am (doc-doxygen-html): Changed to doc-html-doxygen.
	(doc-doxygen-man): Changed to doc-man-doxygen.
	(doc-performance): Changed to doc-html-performance.
	(doc-xml-doxygen): New.
	(doc-xml-single): New.
	(doc-xml-validate): New.
	(doc-html): New.
	(doc-html-single): New.
	(doc-fo): New.
	(doc-pdf): New.
	(doc-pdf-fop-xml): New.
	(doc-pdf-fop-fo): New.
	(doc-pdf-xmlto): New.
	(doc-pdf-xmlroff): New.
	(doc-pdf-prince): New.
	* doc/xml: New directory.
	* doc/xml/authors.xml: New.
	* doc/xml/images: New directory.
	* doc/xml/images/confdeps.png: Add.
	* doc/xml/images/confdeps.dot: Add.
	* doc/xml/faq.xml: New.
	* doc/xml/api.xml: New.
	* doc/xml/gnu: New directory.
	* doc/xml/gnu/gpl-3.0.xml: New.
	* doc/xml/gnu/fdl-1.2.xml: New.
	* doc/xml/gnu/gpl-2.0.xml: New.
	* doc/xml/manual: New directory.
	* doc/xml/manual/mt_allocator.xml: New.
	* doc/xml/manual/allocator.xml: New.
	* doc/xml/manual/ctype.xml: New.
	* doc/xml/manual/numerics.xml: New.
	* doc/xml/manual/codecvt.xml: New.
	* doc/xml/manual/concurrency.xml: New.
	* doc/xml/manual/backwards_compatibility.xml: New.
	* doc/xml/manual/intro.xml: New.
	* doc/xml/manual/shared_ptr.xml: New.
	* doc/xml/manual/abi.xml: New.
	* doc/xml/manual/status_cxxtr1.xml: New.
	* doc/xml/manual/auto_ptr.xml: New.
	* doc/xml/manual/build.xml: New.
	* doc/xml/manual/internals.xml: New.
	* doc/xml/manual/parallel_mode.xml: New.
	* doc/xml/manual/status_cxx1998.xml: New.
	* doc/xml/manual/containers.xml: New.
	* doc/xml/manual/io.xml: New.
	* doc/xml/manual/appendix_porting.xml: New.
	* doc/xml/manual/utilities.xml: New.
	* doc/xml/manual/bitmap_allocator.xml: New.
	* doc/xml/manual/support.xml: New.
	* doc/xml/manual/configure.xml: New.
	* doc/xml/manual/build_hacking.xml: New.
	* doc/xml/manual/evolution.xml: New.
	* doc/xml/manual/using.xml: New.
	* doc/xml/manual/debug.xml: New.
	* doc/xml/manual/localization.xml: New.
	* doc/xml/manual/strings.xml: New.
	* doc/xml/manual/debug_mode.xml: New.
	* doc/xml/manual/locale.xml: New.
	* doc/xml/manual/extensions.xml: New.
	* doc/xml/manual/appendix_contributing.xml: New.
	* doc/xml/manual/messages.xml: New.
	* doc/xml/manual/diagnostics.xml: New.
	* doc/xml/manual/appendix_free.xml: New.
	* doc/xml/manual/algorithms.xml: New.
	* doc/xml/manual/iterators.xml: New.
	* doc/xml/manual/spine.xml: New.
	* doc/xml/manual/test.xml: New.
	* doc/xml/manual/status_cxx200x.xml: New.
	* doc/xml/spine.xml: New.

	* doc/xml/book.txml: New. Template file.
	* doc/xml/chapter.txml: Same.
	* doc/xml/class.txml: Same.

	* doc/doxygen/guide.html: Removed, integrated into other docs.
	* doc/doxygen/user.cfg.in: Clean up XML generation.
	* doc/doxygen/run_doxygen: Move to..	
	* scripts/run_doxygen: ...here.
	
	* configure: Regenerate.
	* Makefile.in: Regenerate.
	* src/Makefile.in: Regenerate.
	* doc/Makefile.in: Regenerate.	
	* po/Makefile.in: Regenerate.
	* libmath/Makefile.in: Regenerate.
	* include/Makefile.in: Regenerate.
	* libsupc++/Makefile.in: Regenerate.
	* testsuite/Makefile.in: Regenerate.
	* aclocal.m4: Regenerate.



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

1 files changed, 133 insertions, 0 deletions

diff --git a/libstdc++-v3/doc/xml/manual/auto_ptr.xml b/libstdc++-v3/doc/xml/manual/auto_ptr.xml
new file mode 100644
index 00000000000..a7a0e97bc6c
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/auto_ptr.xml
@@ -0,0 +1,133 @@
+<sect1 id="manual.util.memory.auto_ptr" xreflabel="auto_ptr">
+<?dbhtml filename="auto_ptr.html"?>
+ 
+<sect1info>
+  <keywordset>
+    <keyword>
+      ISO C++
+    </keyword>
+    <keyword>
+      auto_ptr
+    </keyword>
+  </keywordset>
+</sect1info>
+
+<title>auto_ptr</title>
+
+<sect2 id="auto_ptr.limitations" xreflabel="auto_ptr.limitations">
+<title>Limitations</title>
+
+   <para>Explaining all of the fun and delicious things that can
+   happen with misuse of the <classname>auto_ptr</classname> class
+   template (called <acronym>AP</acronym> here) would take some
+   time. Suffice it to say that the use of <acronym>AP</acronym>
+   safely in the presence of copying has some subtleties.
+   </para>
+   <para>
+     The AP class is a really
+      nifty idea for a smart pointer, but it is one of the dumbest of
+      all the smart pointers -- and that's fine.
+   </para>
+   <para>
+     AP is not meant to be a supersmart solution to all resource
+      leaks everywhere.  Neither is it meant to be an effective form
+      of garbage collection (although it can help, a little bit).
+      And it can <emphasis>not</emphasis>be used for arrays!
+   </para>
+   <para>
+     <acronym>AP</acronym> is meant to prevent nasty leaks in the
+     presence of exceptions.  That's <emphasis>all</emphasis>.  This
+     code is AP-friendly:
+   </para>
+   <programlisting>
+    // Not a recommend naming scheme, but good for web-based FAQs.
+    typedef std::auto_ptr&lt;MyClass&gt;  APMC;
+
+    extern function_taking_MyClass_pointer (MyClass*);
+    extern some_throwable_function ();
+
+    void func (int data)
+    {
+        APMC  ap (new MyClass(data));
+
+        some_throwable_function();   // this will throw an exception
+
+        function_taking_MyClass_pointer (ap.get());
+    }
+   </programlisting>
+   <para>When an exception gets thrown, the instance of MyClass that's
+      been created on the heap will be <function>delete</function>'d as the stack is
+      unwound past <function>func()</function>.
+   </para>
+   <para>Changing that code as follows is not <acronym>AP</acronym>-friendly:
+   </para>
+   <programlisting>
+        APMC  ap (new MyClass[22]);
+   </programlisting>
+   <para>You will get the same problems as you would without the use
+      of <acronym>AP</acronym>:
+   </para>
+   <programlisting>
+        char*  array = new char[10];       // array new...
+        ...
+        delete array;                      // ...but single-object delete
+   </programlisting>
+   <para>
+     AP cannot tell whether the pointer you've passed at creation points
+      to one or many things.  If it points to many things, you are about
+      to die.  AP is trivial to write, however, so you could write your
+      own <code>auto_array_ptr</code> for that situation (in fact, this has
+      been done many times; check the mailing lists, Usenet, Boost, etc).
+   </para>
+</sect2>
+ 
+<sect2 id="auto_ptr.using" xreflabel="auto_ptr.using">
+<title>Use in Containers</title>
+
+  <para>
+  </para>
+  <para>All of the <ulink url="../23_containers/howto.html">containers</ulink>
+      described in the standard library require their contained types
+      to have, among other things, a copy constructor like this:
+  </para>
+   <programlisting>
+    struct My_Type
+    {
+        My_Type (My_Type const&amp;);
+    };
+   </programlisting>
+   <para>
+     Note the const keyword; the object being copied shouldn't change.
+     The template class <code>auto_ptr</code> (called AP here) does not
+     meet this requirement.  Creating a new AP by copying an existing
+     one transfers ownership of the pointed-to object, which means that
+     the AP being copied must change, which in turn means that the
+     copy ctors of AP do not take const objects.
+   </para>
+   <para>
+     The resulting rule is simple: <emphasis>Never ever use a
+     container of auto_ptr objects</emphasis>. The standard says that
+     <quote>undefined</quote> behavior is the result, but it is
+     guaranteed to be messy.
+   </para>
+   <para>
+     To prevent you from doing this to yourself, the
+      <ulink url="../19_diagnostics/howto.html#3">concept checks</ulink> built
+      in to this implementation will issue an error if you try to
+      compile code like this:
+   </para>
+   <programlisting>
+    #include &lt;vector&gt;
+    #include &lt;memory&gt;
+    
+    void f()
+    {
+        std::vector&lt; std::auto_ptr&lt;int&gt; &gt;   vec_ap_int;
+    }
+   </programlisting>
+   <para>
+Should you try this with the checks enabled, you will see an error.
+   </para>
+</sect2>
+
+</sect1>
\ No newline at end of file