[patch] Libstdc++ doc updates

[Jonathan Wakely <jwakely at redhat dot com>]

Mostly markup tweaks, with some additional info to help debug
docbook/latex errors.

Committed to trunk.

commit c3b82a04203fce3e4ee05fd3e544e146ffa60f3a
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Thu May 29 14:24:10 2014 +0100

    	* doc/xml/faq.xml (faq.stream_reopening_fails): Replace <quote> in
    	code example.
    	* doc/xml/manual/backwards_compatibility.xml
    	(backwards.second.stringstreams): Likewise.
    	* doc/xml/manual/configure.xml (--enable-libstdcxx-time): Document
    	change of default.
    	* doc/xml/manual/containers.xml (associative.bitset.type_string):
    	Replace <quote> in code example.
    	* doc/xml/manual/debug.xml: Clarify reference to ThreadSanitizer.
    	* doc/xml/manual/documentation_hacking.xml: Improve debugging tips,
    	fix typos, improve markup.
    	* doc/xml/manual/intro.xml (manual.intro.status.bugs.iso): Replace
    	<emphasis> with <replaceable>.
    	* doc/xml/manual/locale.xml (locale.impl.c): Remove backticks.
    	* doc/xml/manual/support.xml (std.support.memory): Replace <quote>
    	and remove newlines in string literal.

diff --git a/libstdc++-v3/doc/xml/faq.xml b/libstdc++-v3/doc/xml/faq.xml
index 69e2f90..154e610 100644
--- a/libstdc++-v3/doc/xml/faq.xml
+++ b/libstdc++-v3/doc/xml/faq.xml
@@ -801,12 +801,12 @@
     <literallayout class="normal">
     #include &lt;fstream&gt;
     ...
-    std::fstream  fs(<quote>a_file</quote>);
+    std::fstream  fs("a_file");
     // .
     // . do things with fs...
     // .
     fs.close();
-    fs.open(<quote>a_new_file</quote>);
+    fs.open("a_new_file");
     </literallayout>
     
     <para>
diff --git a/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml b/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml
index 89c7cc6..59da85e 100644
--- a/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml
+++ b/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml
@@ -412,7 +412,7 @@ erase(size_type __pos = 0, size_type __n = npos)
   std::ostrstream oss;
 #endif
 
-oss &lt;&lt; <quote>Name=</quote> &lt;&lt; m_name &lt;&lt; <quote>, number=</quote> &lt;&lt; m_number &lt;&lt; std::endl;
+oss &lt;&lt; "Name=" &lt;&lt; m_name &lt;&lt; ", number=" &lt;&lt; m_number &lt;&lt; std::endl;
 ...
 #ifndef HAVE_SSTREAM
   oss &lt;&lt; std::ends; // terminate the char*-string
diff --git a/libstdc++-v3/doc/xml/manual/configure.xml b/libstdc++-v3/doc/xml/manual/configure.xml
index 1c09972..717cca7 100644
--- a/libstdc++-v3/doc/xml/manual/configure.xml
+++ b/libstdc++-v3/doc/xml/manual/configure.xml
@@ -185,7 +185,8 @@
 	desirable because, in glibc, for example, in turn it triggers the
 	linking of libpthread too, which activates locking, a large overhead
 	for single-thread programs.  OPTION=no skips the tests completely.
-	The default is OPTION=no.
+	The default is OPTION=auto, which skips the checks and enables the
+	features only for targets known to support them.
     </para>
  </listitem></varlistentry>
 
diff --git a/libstdc++-v3/doc/xml/manual/containers.xml b/libstdc++-v3/doc/xml/manual/containers.xml
index 9fea0f7..ec2cb21 100644
--- a/libstdc++-v3/doc/xml/manual/containers.xml
+++ b/libstdc++-v3/doc/xml/manual/containers.xml
@@ -334,7 +334,7 @@
      constructor expression:
    </para>
    <programlisting>
-      std::bitset&lt;5&gt; b ( std::string(<quote>10110</quote>) );
+      std::bitset&lt;5&gt; b ( std::string("10110") );
    </programlisting>
 
    <para>
@@ -342,7 +342,7 @@
    </para>
 
     <programlisting>
-      std::bitset&lt;5&gt; b ( <quote>10110</quote> );    // invalid
+      std::bitset&lt;5&gt; b ( "10110" );    // invalid
     </programlisting>
     </section>
   </section>
diff --git a/libstdc++-v3/doc/xml/manual/debug.xml b/libstdc++-v3/doc/xml/manual/debug.xml
index 5e84495..923f6ab 100644
--- a/libstdc++-v3/doc/xml/manual/debug.xml
+++ b/libstdc++-v3/doc/xml/manual/debug.xml
@@ -235,7 +235,8 @@
   Helgrind</link>, and
   <link xmlns:xlink="http://www.w3.org/1999/xlink"; 
   xlink:href="http://code.google.com/p/data-race-test/";> 
-  ThreadSanitizer</link>.
+  ThreadSanitizer</link> (this refers to ThreadSanitizer v1, not the
+  new "tsan" feature built-in to GCC itself).
 </para>
 
 <para>
diff --git a/libstdc++-v3/doc/xml/manual/documentation_hacking.xml b/libstdc++-v3/doc/xml/manual/documentation_hacking.xml
index 59f8445..ba53721 100644
--- a/libstdc++-v3/doc/xml/manual/documentation_hacking.xml
+++ b/libstdc++-v3/doc/xml/manual/documentation_hacking.xml
@@ -274,7 +274,9 @@
 	<link xmlns:xlink="http://www.w3.org/1999/xlink"; xlink:href="http://www.graphviz.org";>Graphviz</link> package
 	will need to be installed. For PDF
 	output, <link xmlns:xlink="http://www.w3.org/1999/xlink"; xlink:href="http://www.tug.org/applications/pdftex/";>
-	pdflatex</link> is required.
+	pdflatex</link> is required as well as a number of TeX packages
+	such as <package>texlive-xtab</package> and
+	<package>texlive-tocloft</package>.
       </para>
 
       <para>
@@ -360,8 +362,8 @@
 	</para>
 	<para>
 	  Working on the doxygen path only, closely examine the
-	  contents of the following build directory:
-	  <filename>build/target/libstdc++-v3/doc/doxygen/latex</filename>.
+	  contents of the following build directory: <filename
+	  class="directory">build/target/libstdc++-v3/doc/doxygen/latex</filename>.
 	  Pay attention to three files enclosed within, annotated as follows.
 	</para>
 <itemizedlist>
@@ -375,18 +377,36 @@
     The actual latex file, or partial latex file. This is generated
     via <command>doxygen</command>, and is the LaTeX version of the
     Doxygen XML file <filename>libstdc++-api.xml</filename>. Go to a specific
-    line, and look at the genrated LaTeX, and try to deduce what
+    line, and look at the generated LaTeX, and try to deduce what
     markup in <filename>libstdc++-api.xml</filename> is causing it.
   </para>
 </listitem>
 
 <listitem>
   <para>
+   <emphasis>refman.log</emphasis>
+  </para>
+
+  <para>
+    A log created by <command>latex</command> as it processes the
+    <filename>refman.tex</filename> file. If generating the PDF fails
+    look at the end of this file for errors such as:
+    <screen>
+    ! LaTeX Error: File `xtab.sty' not found.
+    </screen>
+    This indicates a required TeX package is missing. For the example
+    above the <package>texlive-xtab</package> package needs to be
+    installed.
+  </para>
+</listitem>
+
+<listitem>
+  <para>
    <emphasis>refman.out</emphasis>
   </para>
 
   <para>
-    A log of the compilation of the converted LaTeX form to pdf. This
+    A log of the compilation of the converted LaTeX form to PDF. This
     is a linear list, from the beginning of the
     <filename>refman.tex</filename> file: the last entry of this file
     should be the end of the LaTeX file. If it is truncated, then you
@@ -436,9 +456,9 @@
 	<classname>deque</classname>/<classname>vector</classname>/<classname>list</classname>
 	and <classname>std::pair</classname> as examples.  For
 	functions, see their member functions, and the free functions
-	in <filename>stl_algobase.h</filename>. Member functions of
-	other container-like types should read similarly to these
-	member functions.
+	in <filename class="headerfile">stl_algobase.h</filename>. Member
+	functions of other container-like types should read similarly to
+	these member functions.
       </para>
 
       <para>
@@ -488,8 +508,8 @@
       <para>
 	Use either kind of grouping, as
 	appropriate. <filename>doxygroups.cc</filename> exists for this
-	purpose. See <filename>stl_iterator.h</filename> for a good example
-	of the <quote>other</quote> kind of grouping.
+	purpose. See <filename class="headerfile">stl_iterator.h</filename>
+	for a good example of the <quote>other</quote> kind of grouping.
       </para>
 
       <para>
@@ -500,8 +520,8 @@
       </para>
 
       <para>
-	Complicated math functions should use the multi-line
-	format. An example from <filename>random.h</filename>:
+	Complicated math functions should use the multi-line format.
+	An example from <filename class="headerfile">random.h</filename>:
       </para>
 
       <para>
@@ -535,9 +555,9 @@
       <para>
 	The other relevant detail for header files is the use of a
 	libstdc++-specific doxygen alias that helps distinguish
-	between public header files (like <filename>random</filename>)
+	between public header files (like <filename class="headerfile">random</filename>)
 	from implementation or private header files (like
-	<filename>bits/c++config.h</filename>.) This alias is spelled
+	<filename class="headerfile">bits/c++config.h</filename>.) This alias is spelled
 	<literal>@headername</literal> and can take one or two
 	arguments that detail the public header file or files that
 	should be included to use the contents of the file. All header
@@ -827,7 +847,7 @@ make <literal>XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</literal>
 	<para>
 	  Working on the docbook path only, closely examine the
 	  contents of the following build directory:
-	  <filename>build/target/libstdc++-v3/doc/docbook/latex</filename>.
+	  <filename class="directory">build/target/libstdc++-v3/doc/docbook/latex</filename>.
 	  Pay attention to three files enclosed within, annotated as follows.
 	</para>
 
@@ -842,7 +862,7 @@ make <literal>XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</literal>
     The actual latex file, or partial latex file. This is generated
     via <command>dblatex</command>, and is the LaTeX version of the
     DocBook XML file <filename>spine.xml</filename>. Go to a specific
-    line, and look at the genrated LaTeX, and try to deduce what
+    line, and look at the generated LaTeX, and try to deduce what
     markup in <filename>spine.xml</filename> is causing it.
   </para>
 </listitem>
diff --git a/libstdc++-v3/doc/xml/manual/intro.xml b/libstdc++-v3/doc/xml/manual/intro.xml
index cb14186..a71a9f9 100644
--- a/libstdc++-v3/doc/xml/manual/intro.xml
+++ b/libstdc++-v3/doc/xml/manual/intro.xml
@@ -825,11 +825,11 @@ requirements of the license of GCC.
    </para>
 
    <programlisting>
-   <emphasis>get gcc sources</emphasis>
-   <emphasis>extract into gccsrcdir</emphasis>
-   mkdir <emphasis>gccbuilddir</emphasis>
-   cd <emphasis>gccbuilddir</emphasis>
-   <emphasis>gccsrcdir</emphasis>/configure --prefix=<emphasis>destdir</emphasis> --other-opts...
+   <replaceable>get gcc sources</replaceable>
+   <replaceable>extract into gccsrcdir</replaceable>
+   mkdir <replaceable>gccbuilddir</replaceable>
+   cd <replaceable>gccbuilddir</replaceable>
+   <replaceable>gccsrcdir</replaceable>/configure --prefix=<replaceable>destdir</replaceable> --other-opts...
    make
    make check
    make install
diff --git a/libstdc++-v3/doc/xml/manual/locale.xml b/libstdc++-v3/doc/xml/manual/locale.xml
index 8a78095..01ea189 100644
--- a/libstdc++-v3/doc/xml/manual/locale.xml
+++ b/libstdc++-v3/doc/xml/manual/locale.xml
@@ -111,7 +111,7 @@ portability is an issue.
 <itemizedlist>
    <listitem>
      <para>
-       <code>`locale -a`</code> displays available locales.
+       <code>locale -a</code> displays available locales.
      </para>
 <blockquote>
 <programlisting>
diff --git a/libstdc++-v3/doc/xml/manual/support.xml b/libstdc++-v3/doc/xml/manual/support.xml
index 410f714..573869a 100644
--- a/libstdc++-v3/doc/xml/manual/support.xml
+++ b/libstdc++-v3/doc/xml/manual/support.xml
@@ -248,9 +248,9 @@
    void my_new_handler ()
    {
        delete[] safety;
-       popup_window ("Dude, you are running low on heap memory.  You
-		      should, like, close some windows, or something.
-		      The next time you run out, we're gonna burn!");
+       popup_window ("Dude, you are running low on heap memory.  You"
+		     " should, like, close some windows, or something."
+		     " The next time you run out, we're gonna burn!");
        set_new_handler (old_handler);
        return;
    }
@@ -384,7 +384,7 @@ int main(int argc)
 {
   std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
   if (argc &gt; 5)
-    throw argument_error(<quote>argc is greater than 5!</quote>);
+    throw argument_error("argc is greater than 5!");
   else
     throw argc;
 }