[v3] update docs

[Jonathan Wakely]

The attached patch makes a few (I hope) improvements to the libstdc++ docs:

Change link text from "here" to something more descriptive that works
better in printed documentation.
Link from the FAQ about LD_LIBRARY_PATH to the related section of the manual.
Fix a typo (?) in that section of the manual, GNU ld uses -rpath not --rpath.
Expand that section of the manual to cover LD_RUN_PATH and ldconfig/crle.
Mention string::shrink_to_fit() when talking about shrink to fit strings.
Document the prerequisites for generating html docs.

I won't check this in until I know how to regenerate the html
correctly, so I'll leave it here for comments in the meanwhile.

        * doc/xml/faq.xml: Link to manual.
        * doc/xml/manual/using.xml: Expand dynamic libraries section.
        * doc/xml/manual/strings.xml: Mention shrink_to_fit() member.
        * doc/xml/manual/prerequisites.xml: List requirements for generating
        html docs.
-------------- next part --------------
Index: doc/xml/faq.xml
===================================================================
--- doc/xml/faq.xml	(revision 158621)
+++ doc/xml/faq.xml	(working copy)
@@ -387,6 +387,11 @@
     linker has different names on different platforms but the man page
     is usually called something such as <filename>ld.so/rtld/dld.so</filename>.
     </para>
+    <para>
+    Using LD_LIBRARY_PATH is not always the best solution, <link
+    linkend="manual.intro.using.linkage.dynamic">Finding Dynamic or Shared
+    Libraries</link> in the manual gives some alternatives.
+    </para>
   </answer>
 </qandaentry>
 
@@ -895,8 +900,9 @@
     </para>
     <para>
     More information, including how to optionally enable/disable the
-    checks, is available
-    <link linkend="std.diagnostics.concept_checking">here</link>.
+    checks, is available in the
+    <link linkend="std.diagnostics.concept_checking">Diagnostics</link>.
+    chapter of the manual.
     </para> 
   </answer>
 </qandaentry>
Index: doc/xml/manual/using.xml
===================================================================
--- doc/xml/manual/using.xml	(revision 158621)
+++ doc/xml/manual/using.xml	(working copy)
@@ -1176,22 +1176,42 @@ A quick read of the relevant part of the
 	<itemizedlist>
 	  <listitem>
 	    <para>
-	      GNU ld (default on Linux):<literal>-Wl,--rpath,<filename class="directory">destdir</filename>/lib</literal>
+	      GNU ld (default on Linux):
+              <literal>-Wl,-rpath,<filename class="directory">destdir</filename>/lib</literal>
 	    </para>
 	  </listitem>
 	  <listitem>
 	    <para>
-	      IRIX ld:<literal>
-	      -Wl,-rpath,<filename class="directory">destdir</filename>/lib</literal>
+	      IRIX ld:
+              <literal>-Wl,-rpath,<filename class="directory">destdir</filename>/lib</literal>
 	    </para>
 	  </listitem>
 	  <listitem>
 	  <para>
-	  Solaris ld:<literal>-Wl,-R<filename class="directory">destdir</filename>/lib</literal>
+	    Solaris ld:
+            <literal>-Wl,-R<filename class="directory">destdir</filename>/lib</literal>
 	  </para>
 	  </listitem>
 	</itemizedlist>
       </listitem>
+      <listitem>
+	<para>
+	  Some linkers allow you to specify the path to the library by
+	  setting <literal>LD_RUN_PATH</literal> in your environment
+	  when linking.
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  On some platforms the system administrator can configure the
+	  dynamic linker to always look for libraries in
+	  <filename class="directory">destdir/lib</filename>, for example
+	  by using the <command>ldconfig</command> utility on Linux
+	  or the <command>crle</command> utility on Solaris. This is a
+	  system-wide change which can make the system unusable so if you
+	  are unsure then use one of the other methods described above.
+	</para>
+      </listitem>
     </itemizedlist>
     <para>
       Use the <command>ldd</command> utility on the linked executable
Index: doc/xml/manual/strings.xml
===================================================================
--- doc/xml/manual/strings.xml	(revision 158621)
+++ doc/xml/manual/strings.xml	(working copy)
@@ -366,6 +366,10 @@ stringtok(Container &container, stri
       entry</link>) but the regular copy constructor cannot be used
       because libstdc++'s <code>string</code> is Copy-On-Write.
    </para>
+   <para>In <link linkend="status.iso.200x">C++0x</link> mode you can call
+      <code>s.shrink_to_fit()</code> to achieve the same effect as
+      <code>s.reserve(s.size())</code>.
+   </para>
 
 
   </sect2>
Index: doc/xml/manual/prerequisites.xml
===================================================================
--- doc/xml/manual/prerequisites.xml	(revision 158621)
+++ doc/xml/manual/prerequisites.xml	(working copy)
@@ -41,6 +41,12 @@
    </para>
 
    <para>
+   To generate the API documentation from the sources you will need
+   <ulink url="http://doxygen.org">Doxygen</ulink>, LaTeX, Docbook and
+   <ulink url="http://xmlsoft.org">xsltproc</ulink>.
+   </para>
+
+   <para>
    Finally, a few system-specific requirements:
    </para>