Backport libstdc++ documentation improvements

* doc/xml/manual/abi.xml: Backport documentation improvements from
	mainline.
	* doc/xml/manual/configure.xml: Likewise.
	* doc/xml/manual/diagnostics.xml: Likewise.
	* doc/xml/manual/extensions.xml: Likewise.
	* doc/xml/manual/status_cxx2011.xml: Likewise.
	* doc/xml/manual/status_cxx2014.xml: Likewise.
	* doc/xml/manual/using.xml: Likewise.
	* doc/html/*: Regenerate.

From-SVN: r231409

libstdc++-v3/ChangeLog

@@ -1,3 +1,15 @@
+2015-12-08  Jonathan Wakely  <jwakely@redhat.com>
+
+	* doc/xml/manual/abi.xml: Backport documentation improvements from
+	mainline.
+	* doc/xml/manual/configure.xml: Likewise.
+	* doc/xml/manual/diagnostics.xml: Likewise.
+	* doc/xml/manual/extensions.xml: Likewise.
+	* doc/xml/manual/status_cxx2011.xml: Likewise.
+	* doc/xml/manual/status_cxx2014.xml: Likewise.
+	* doc/xml/manual/using.xml: Likewise.
+	* doc/html/*: Regenerate.
+
 2015-12-04  Jonathan Wakely  <jwakely@redhat.com>
 
 	PR libstdc++/56383

libstdc++-v3/doc/html/manual/abi.html

@@ -38,7 +38,7 @@
   documented
 <a class="link" href="configure.html" title="Configure">here</a>.
 </p><p> Putting all of these ideas together results in the C++ Standard
-library ABI, which is the compilation of a given library API by a
+Library ABI, which is the compilation of a given library API by a
 given compiler ABI. In a nutshell:
 </p><p>
   <span class="quote">“<span class="quote">

libstdc++-v3/doc/html/manual/concept_checking.html

@@ -35,8 +35,9 @@
      <code class="literal">-D_GLIBCXX_CONCEPT_CHECKS</code>.
  </p><p>
    Please note that the checks are based on the requirements in the original
-   C++ standard, some of which have changed in the new C++11 revision.
+   C++ standard, many of which were relaxed in the C++11 standard and so valid
-   Additionally, some correct code might be rejected by the concept checks,
+   C++11 code may be incorrectly rejected by the concept checks.  Additionally,
+   some correct C++03 code might be rejected by the concept checks,
    for example template argument types may need to be complete when used in
    a template definition, rather than at the point of instantiation.
    There are no plans to address these shortcomings.

libstdc++-v3/doc/html/manual/configure.html

@@ -174,10 +174,12 @@
 	Mostly useful together with shared memory allocators, see PR
 	libstdc++/16612 for details.
      </p></dd><dt><span class="term"><code class="code">--enable-concept-checks</code></span></dt><dd><p>This turns on additional compile-time checks for instantiated
-	library templates, in the form of specialized templates,
+	library templates, in the form of specialized templates described in
-	<a class="link" href="concept_checking.html" title="Concept Checking">described here</a>.  They
+        the <a class="link" href="concept_checking.html" title="Concept Checking">Concept
+        Checking</a> section.  They
 	can help users discover when they break the rules of the STL, before
-	their programs run.
+	their programs run. These checks are based on C++03 rules and some of
+	them are not compatible with correct C++11 code.
      </p></dd><dt><span class="term"><code class="code">--enable-symvers[=style]</code></span></dt><dd><p>In 3.1 and later, tries to turn on symbol versioning in the
 	shared library (if a shared library has been
 	requested). Values for 'style' that are currently supported
@@ -236,9 +238,10 @@
    </p></dd><dt><span class="term"><code class="code">--with-default-libstdcxx-abi=</code><em class="replaceable"><code>OPTION</code></em></span></dt><dd><p>
      Set the default value for the <span class="symbol">_GLIBCXX_USE_CXX11_ABI</span>
      macro (see <a class="xref" href="using_macros.html" title="Macros">Macros</a>).
-     The default is <code class="option">OPTION=c++11</code> which sets the macro to
+     The default is <code class="option">OPTION=new</code> which sets the macro to
      <code class="literal">1</code>,
-     use <code class="option">OPTION=c++98</code> to set it to <code class="literal">0</code>.
+     use <code class="option">OPTION=gcc4-compatible</code> to set it to
+     <code class="literal">0</code>.
      This option does not change the library ABI.
    </p></dd><dt><span class="term"><code class="code">--enable-vtable-verify</code>[default]</span></dt><dd><p>Use <code class="code">-fvtable-verify=std</code> to compile the C++
     runtime with instrumentation for vtable verification. All virtual
@@ -247,4 +250,8 @@
     <code class="classname">iostream</code>, and others.  Disabling means that
     the C++ runtime is compiled without support for vtable
     verification. By default, this option is off.
-     </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="setup.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="setup.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="make.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. Setup </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Make</td></tr></table></div></body></html>
+     </p></dd><dt><span class="term"><code class="code">--enable-libstdcxx-filesystem-ts</code>[default]</span></dt><dd><p>Build <code class="filename">libstdc++fs.a</code> as well
+      as the usual libstdc++ and libsupc++ libraries. This is enabled by
+      default on select POSIX targets where it is known to work and disabled
+      otherwise.
+    </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="setup.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="setup.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="make.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. Setup </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Make</td></tr></table></div></body></html>

libstdc++-v3/doc/html/manual/ext_compile_checks.html

@@ -29,7 +29,8 @@
       They can be enabled at configure time with
       <a class="link" href="configure.html" title="Configure"><code class="literal">--enable-concept-checks</code></a>.
       You can enable them on a per-translation-unit basis with
-      <code class="code">#define _GLIBCXX_CONCEPT_CHECKS</code> for GCC 3.4 and higher
+      <a class="link" href="using_macros.html" title="Macros"><code class="code">#define
+      _GLIBCXX_CONCEPT_CHECKS</code></a> for GCC 3.4 and higher
       (or with <code class="code">#define _GLIBCPP_CONCEPT_CHECKS</code> for versions
       3.1, 3.2 and 3.3).
    </p><p>Please note that the concept checks only validate the requirements

libstdc++-v3/doc/html/manual/using_dynamic_or_shared.html

@@ -102,4 +102,21 @@ A quick read of the relevant part of the GCC
       also installed, for use with Libtool.  If you use Libtool to
       create your executables, these details are taken care of for
       you.
+    </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.linkage.experimental"></a>Experimental Library Extensions</h3></div></div></div><p>
+      GCC 5.3 includes an implementation of the Filesystem library defined
+      by the technical specification ISO/IEC TS 18822:2015. Because this is
+      an experimental library extension, not part of the C++ standard, it
+      is implemented in a separate library,
+      <code class="filename">libstdc++fs.a</code>, and there is
+      no shared library for it. To use the library you should include
+      <code class="filename">&lt;experimental/filesystem&gt;</code>
+      and link with <code class="option">-lstdc++fs</code>. The library implementation
+      is incomplete on non-POSIX platforms, specifically Windows support is
+      rudimentary.
+    </p><p>
+      Due to the experimental nature of the Filesystem library the usual
+      guarantees about ABI stability and backwards compatibility do not apply
+      to it. There is no guarantee that the components in any
+      <code class="filename">&lt;experimental/xxx&gt;</code>
+      header will remain compatible between different GCC releases.
     </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_namespaces.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using_concurrency.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Namespaces </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Concurrency</td></tr></table></div></body></html>

libstdc++-v3/doc/html/manual/using_headers.html

@@ -74,12 +74,15 @@ of <code class="code">std::sinf</code>, <code class="code">std::sin</code>,
 and <code class="code">std::sinl</code>.
 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.headers.pre"></a>Precompiled Headers</h3></div></div></div><p>There are three base header files that are provided. They can be
 used to precompile the standard headers and extensions into binary
-files that may the be used to speed compiles that use these headers.
+files that may then be used to speed up compilations that use these headers.
 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>stdc++.h</p><p>Includes all standard headers. Actual content varies depending on
-language dialect.
+<a class="link" href="using.html#manual.intro.using.flags" title="Command Options">language dialect</a>.
 </p></li><li class="listitem"><p>stdtr1c++.h</p><p>Includes all of &lt;stdc++.h&gt;, and adds all the TR1 headers.
-</p></li><li class="listitem"><p>extc++.h</p><p>Includes all of &lt;stdtr1c++.h&gt;, and adds all the Extension headers.
+</p></li><li class="listitem"><p>extc++.h</p><p>Includes all of the Extension headers
-</p></li></ul></div><p>How to construct a .gch file from one of these base header files.</p><p>First, find the include directory for the compiler. One way to do
+(and in C++98 mode also adds all the TR1 headers by including all of
+&lt;stdtr1c++.h&gt;).
+</p></li></ul></div><p>To construct a .gch file from one of these base header files,
+first find the include directory for the compiler. One way to do
 this is:</p><pre class="programlisting">
 g++ -v hello.cc
 

libstdc++-v3/doc/html/manual/using_namespaces.html

@@ -2,8 +2,8 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Namespaces</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_dual_abi.html" title="Dual ABI" /><link rel="next" href="using_dynamic_or_shared.html" title="Linking" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Namespaces</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using_dual_abi.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="using_dynamic_or_shared.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.namespaces"></a>Namespaces</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.all"></a>Available Namespaces</h3></div></div></div><p> There are three main namespaces.
 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>std</p><p>The ISO C++ standards specify that "all library entities are defined
 within namespace std." This includes namespaces nested
-within <code class="code">namespace std</code>, such as <code class="code">namespace
+within namespace <code class="code">std</code>, such as namespace
-std::tr1</code>.
+<code class="code">std::chrono</code>.
 </p></li><li class="listitem"><p>abi</p><p>Specified by the C++ ABI. This ABI specifies a number of type and
 function APIs supplemental to those required by the ISO C++ Standard,
 but necessary for interoperability.

libstdc++-v3/doc/xml/manual/abi.xml

@@ -66,7 +66,7 @@
 </para>
 
 <para> Putting all of these ideas together results in the C++ Standard
-library ABI, which is the compilation of a given library API by a
+Library ABI, which is the compilation of a given library API by a
 given compiler ABI. In a nutshell:
 </para>
 

libstdc++-v3/doc/xml/manual/configure.xml

@@ -297,10 +297,12 @@
 
  <varlistentry><term><code>--enable-concept-checks</code></term>
  <listitem><para>This turns on additional compile-time checks for instantiated
-	library templates, in the form of specialized templates,
+	library templates, in the form of specialized templates described in
-	<link linkend="std.diagnostics.concept_checking">described here</link>.  They
+        the <link linkend="std.diagnostics.concept_checking">Concept
+        Checking</link> section.  They
 	can help users discover when they break the rules of the STL, before
-	their programs run.
+	their programs run. These checks are based on C++03 rules and some of
+	them are not compatible with correct C++11 code.
      </para>
  </listitem></varlistentry>
 
@@ -418,6 +420,15 @@
      </para>
  </listitem></varlistentry>
 
+ <varlistentry><term><code>--enable-libstdcxx-filesystem-ts</code>[default]</term>
+ <listitem>
+    <para>Build <filename class="libraryfile">libstdc++fs.a</filename> as well
+      as the usual libstdc++ and libsupc++ libraries. This is enabled by
+      default on select POSIX targets where it is known to work and disabled
+      otherwise.
+    </para>
+ </listitem></varlistentry>
+
 </variablelist>
 
 </section>

libstdc++-v3/doc/xml/manual/diagnostics.xml

@@ -114,8 +114,9 @@
 
  <para>
    Please note that the checks are based on the requirements in the original
-   C++ standard, some of which have changed in the new C++11 revision.
+   C++ standard, many of which were relaxed in the C++11 standard and so valid
-   Additionally, some correct code might be rejected by the concept checks,
+   C++11 code may be incorrectly rejected by the concept checks.  Additionally,
+   some correct C++03 code might be rejected by the concept checks,
    for example template argument types may need to be complete when used in
    a template definition, rather than at the point of instantiation.
    There are no plans to address these shortcomings.

libstdc++-v3/doc/xml/manual/extensions.xml

@@ -82,7 +82,8 @@ extensions, be aware of two things:
       They can be enabled at configure time with
       <link linkend="manual.intro.setup.configure"><literal>--enable-concept-checks</literal></link>.
       You can enable them on a per-translation-unit basis with
-      <code>#define _GLIBCXX_CONCEPT_CHECKS</code> for GCC 3.4 and higher
+      <link linkend="manual.intro.using.macros"><code>#define
+      _GLIBCXX_CONCEPT_CHECKS</code></link> for GCC 3.4 and higher
       (or with <code>#define _GLIBCPP_CONCEPT_CHECKS</code> for versions
       3.1, 3.2 and 3.3).
    </para>

libstdc++-v3/doc/xml/manual/status_cxx2011.xml

@@ -17,8 +17,8 @@ Final Draft International Standard, Standard for Programming Language C++
 </para>
 
 <para>
-In this implementation <literal>-std=gnu++11</literal> or
+In this implementation the <literal>-std=gnu++11</literal> or
-<literal>-std=c++11</literal> flags must be used to enable language
+<literal>-std=c++11</literal> flag must be used to enable language
 and library
 features. See <link linkend="manual.intro.using.flags">dialect</link>
 options. The pre-defined symbol
@@ -642,10 +642,8 @@ particular release.
       <entry>Class template <code>shared_ptr</code></entry>
       <entry>Y</entry>
       <entry>
-	<para>
 	  Uses code from
 	  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">boost::shared_ptr</link>.
-	</para>
       </entry>
     </row>
     <row>
@@ -2673,7 +2671,10 @@ particular release.
       <emphasis>30.2.3 [thread.req.native]/1</emphasis>
       <classname>native_handle_type</classname> and
       <methodname>native_handle</methodname> are provided. The handle types
-      are defined in terms of the Gthreads abstraction layer.
+      are defined in terms of the Gthreads abstraction layer, although this
+      is subject to change at any time. Any use of
+      <classname>native_handle</classname> is inherently non-portable and
+      not guaranteed to work between major releases of GCC.
       <itemizedlist>
          <listitem><para><classname>thread</classname>: The native handle type is
             a typedef for <code>__gthread_t</code> i.e. <code>pthread_t</code>

libstdc++-v3/doc/xml/manual/status_cxx2014.xml

@@ -10,8 +10,8 @@
 </info>
 
 <para>
-In this implementation <literal>-std=gnu++1y</literal> or
+In this implementation the <literal>-std=gnu++14</literal> or
-<literal>-std=c++1y</literal> flags must be used to enable language
+<literal>-std=c++14</literal> flag must be used to enable language
 and library
 features. See <link linkend="manual.intro.using.flags">dialect</link>
 options. The pre-defined symbol
@@ -196,7 +196,7 @@ not in any particular release.
       </entry>
       <entry>Shared Locking in C++</entry>
       <entry>Y</entry>
-      <entry>Need tests</entry>
+      <entry/>
     </row>
 
 
@@ -395,15 +395,18 @@ not in any particular release.
     </row>
 
     <row>
-      <?dbhtml bgcolor="#C8C8B0" ?>
       <entry>
-	<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3932.htm">
+	<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4100.pdf">
-	  N3940
+	  N4100
 	</link>
       </entry>
       <entry>File System</entry>
-      <entry>WIP</entry>
+      <entry>Y</entry>
-      <entry></entry>
+      <entry>
+	Link with
+	<link linkend="manual.intro.using.linkage.experimental">
+	<option>-lstdc++fs</option></link>
+      </entry>
     </row>
 
 

libstdc++-v3/doc/xml/manual/using.xml

@@ -13,7 +13,10 @@
     </para>
 
     <para>
-      By default, <command>g++</command> is equivalent to  <command>g++ -std=gnu++98</command>. The standard library also defaults to this dialect.
+      The standard library conforms to the dialect of C++ specified by the
+      <option>-std</option> option passed to the compiler.
+      By default, <command>g++</command> is equivalent to
+      <command>g++ -std=gnu++98</command> for GCC 5 and older releases.
     </para>
 
  <table frame="all" xml:id="table.cmd_options">
@@ -32,12 +35,14 @@
 
   <tbody>
     <row>
-      <entry><literal>-std=c++98</literal></entry>
+      <entry><literal>-std=c++98</literal> or <literal>-std=c++03</literal>
+      </entry>
       <entry>Use the 1998 ISO C++ standard plus amendments.</entry>
     </row>
 
     <row>
-      <entry><literal>-std=gnu++98</literal></entry>
+      <entry><literal>-std=gnu++98</literal> or <literal>-std=gnu++03</literal>
+      </entry>
       <entry>As directly above, with GNU extensions.</entry>
     </row>
 
@@ -51,6 +56,16 @@
       <entry>As directly above, with GNU extensions.</entry>
     </row>
 
+    <row>
+      <entry><literal>-std=c++14</literal></entry>
+      <entry>Use the 2014 ISO C++ standard.</entry>
+    </row>
+
+    <row>
+      <entry><literal>-std=gnu++14</literal></entry>
+      <entry>As directly above, with GNU extensions.</entry>
+    </row>
+
     <row>
       <entry><literal>-fexceptions</literal></entry>
       <entry>See <link linkend="intro.using.exception.no">exception-free dialect</link></entry>
@@ -79,6 +94,14 @@
       </entry>
     </row>
 
+    <row>
+      <entry><literal>-lstdc++fs</literal></entry>
+      <entry>Linking to <filename class="libraryfile">libstdc++fs</filename>
+        is required for use of the Filesystem library extensions in
+        <filename class="headerfile">&lt;experimental/filesystem&gt;</filename>.
+      </entry>
+    </row>
+
     <row>
       <entry><literal>-fopenmp</literal></entry>
       <entry>For <link linkend="manual.ext.parallel_mode">parallel</link> mode.</entry>
@@ -703,7 +726,7 @@ and <code>std::sinl</code>.
 
 <para>There are three base header files that are provided. They can be
 used to precompile the standard headers and extensions into binary
-files that may the be used to speed compiles that use these headers.
+files that may then be used to speed up compilations that use these headers.
 </para>
 
 
@@ -711,7 +734,7 @@ files that may the be used to speed compiles that use these headers.
 <listitem>
   <para>stdc++.h</para>
 <para>Includes all standard headers. Actual content varies depending on
-language dialect.
+<link linkend="manual.intro.using.flags">language dialect</link>.
 </para>
 </listitem>
 
@@ -722,13 +745,14 @@ language dialect.
 </listitem>
 
 <listitem><para>extc++.h</para>
-<para>Includes all of &lt;stdtr1c++.h&gt;, and adds all the Extension headers.
+<para>Includes all of the Extension headers
+(and in C++98 mode also adds all the TR1 headers by including all of
+&lt;stdtr1c++.h&gt;).
 </para></listitem>
 </itemizedlist>
 
-<para>How to construct a .gch file from one of these base header files.</para>
+<para>To construct a .gch file from one of these base header files,
-
+first find the include directory for the compiler. One way to do
-<para>First, find the include directory for the compiler. One way to do
 this is:</para>
 
 <programlisting>
@@ -1027,8 +1051,8 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
   <listitem><para>std</para>
 <para>The ISO C++ standards specify that "all library entities are defined
 within namespace std." This includes namespaces nested
-within <code>namespace std</code>, such as <code>namespace
+within namespace <code>std</code>, such as namespace
-std::tr1</code>.
+<code>std::chrono</code>.
 </para>
 </listitem>
 <listitem><para>abi</para>
@@ -1333,8 +1357,31 @@ A quick read of the relevant part of the GCC
       you.
     </para>
     </section>
-  </section>
 
+    <section xml:id="manual.intro.using.linkage.experimental" xreflabel="Library Extensions"><info><title>Experimental Library Extensions</title></info>
+
+    <para>
+      GCC 5.3 includes an implementation of the Filesystem library defined
+      by the technical specification ISO/IEC TS 18822:2015. Because this is
+      an experimental library extension, not part of the C++ standard, it
+      is implemented in a separate library,
+      <filename class="libraryfile">libstdc++fs.a</filename>, and there is
+      no shared library for it. To use the library you should include
+      <filename class="headerfile">&lt;experimental/filesystem&gt;</filename>
+      and link with <option>-lstdc++fs</option>. The library implementation
+      is incomplete on non-POSIX platforms, specifically Windows support is
+      rudimentary.
+    </para>
+
+    <para>
+      Due to the experimental nature of the Filesystem library the usual
+      guarantees about ABI stability and backwards compatibility do not apply
+      to it. There is no guarantee that the components in any
+      <filename class="headerfile">&lt;experimental/xxx&gt;</filename>
+      header will remain compatible between different GCC releases.
+    </para>
+    </section>
+  </section>
 
   <section xml:id="manual.intro.using.concurrency" xreflabel="Concurrency"><info><title>Concurrency</title></info>
     <?dbhtml filename="using_concurrency.html"?>