From b4f1b069be94e0394543153664132d5f7b522def Mon Sep 17 00:00:00 2001
From: Dave Abrahams <dave@boostpro.com>
Date: Mon, 12 Jan 2004 18:02:50 +0000
Subject: [PATCH] Really re-resolved title level problem

A few minor edits


[SVN r21634]
---
 doc/facade-and-adaptor.html  | 39 +++++++++++++++---------------
 doc/iterator_facade.html     | 47 +++++++++++++++++++-----------------
 doc/iterator_facade.rst      |  6 ++---
 doc/iterator_facade_body.rst | 26 +++++++++++---------
 doc/iterator_facade_ref.rst  |  6 ++---
 5 files changed, 65 insertions(+), 59 deletions(-)

diff --git a/doc/facade-and-adaptor.html b/doc/facade-and-adaptor.html
index 44ae1dc..dab0bfc 100755
--- a/doc/facade-and-adaptor.html
+++ b/doc/facade-and-adaptor.html
@@ -75,14 +75,12 @@ by adapting other iterators.</td>
 <li><a class="reference" href="#proposed-text" id="id25" name="id25">Proposed Text</a><ul>
 <li><a class="reference" href="#header-iterator-helper-synopsis-lib-iterator-helper-synopsis" id="id26" name="id26">Header <tt class="literal"><span class="pre">&lt;iterator_helper&gt;</span></tt> synopsis    [lib.iterator.helper.synopsis]</a></li>
 <li><a class="reference" href="#iterator-facade-lib-iterator-facade" id="id27" name="id27">Iterator facade [lib.iterator.facade]</a><ul>
-<li><a class="reference" href="#class-template-iterator-facade" id="id28" name="id28">Class template <tt class="literal"><span class="pre">iterator_facade</span></tt></a><ul>
+<li><a class="reference" href="#class-template-iterator-facade" id="id28" name="id28">Class template <tt class="literal"><span class="pre">iterator_facade</span></tt></a></li>
 <li><a class="reference" href="#iterator-facade-requirements" id="id29" name="id29"><tt class="literal"><span class="pre">iterator_facade</span></tt> Requirements</a></li>
 <li><a class="reference" href="#iterator-facade-iterator-category" id="id30" name="id30"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></li>
 <li><a class="reference" href="#iterator-facade-operations" id="id31" name="id31"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></li>
 </ul>
 </li>
-</ul>
-</li>
 <li><a class="reference" href="#iterator-adaptor-lib-iterator-adaptor" id="id32" name="id32">Iterator adaptor [lib.iterator.adaptor]</a><ul>
 <li><a class="reference" href="#class-template-iterator-adaptor" id="id33" name="id33">Class template <tt class="literal"><span class="pre">iterator_adaptor</span></tt></a></li>
 <li><a class="reference" href="#iterator-adaptor-base-class-parameters" id="id34" name="id34"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></li>
@@ -285,11 +283,11 @@ identified the following core behaviors for iterators:</p>
 include the associated types exposed through iterator traits:
 <tt class="literal"><span class="pre">value_type</span></tt>, <tt class="literal"><span class="pre">reference</span></tt>, <tt class="literal"><span class="pre">difference_type</span></tt>, and
 <tt class="literal"><span class="pre">iterator_category</span></tt>.</p>
-<p>Iterator facade uses the Curiously Recurring Template Pattern (CRTP)
-<a class="citation-reference" href="#cop95" id="id4" name="id4">[Cop95]</a> so that the user can specify the behavior of
-<tt class="literal"><span class="pre">iterator_facade</span></tt> in a derived class.  Former designs used policy
-objects to specify the behavior.  <tt class="literal"><span class="pre">iterator_facade</span></tt> does not use policy
-objects for several reasons:</p>
+<p>Iterator facade uses the Curiously Recurring Template
+Pattern (CRTP) <a class="citation-reference" href="#cop95" id="id4" name="id4">[Cop95]</a> so that the user can specify the behavior
+of <tt class="literal"><span class="pre">iterator_facade</span></tt> in a derived class.  Former designs used
+policy objects to specify the behavior, but that approach was
+discarded for several reasons:</p>
 <blockquote>
 <ol class="arabic simple">
 <li>the creation and eventual copying of the policy object may create
@@ -299,9 +297,11 @@ on the created iterator types, an essential feature if
 <tt class="literal"><span class="pre">iterator_facade</span></tt> should be used in other library
 implementations.</li>
 <li>Without the use of CRTP, the standard requirement that an
-iterator's <tt class="literal"><span class="pre">operator++</span></tt> returns the iterator type itself means
-that all iterators generated by <tt class="literal"><span class="pre">iterator_facade</span></tt> would be
-specializations of <tt class="literal"><span class="pre">iterator_facade</span></tt>.  Cumbersome type generator
+iterator's <tt class="literal"><span class="pre">operator++</span></tt> returns the iterator type itself
+would mean that all iterators built with the library would
+have to be specializations of <tt class="literal"><span class="pre">iterator_facade&lt;...&gt;</span></tt>, rather
+than something more descriptive like
+<tt class="literal"><span class="pre">indirect_iterator&lt;T*&gt;</span></tt>.  Cumbersome type generator
 metafunctions would be needed to build new parameterized
 iterators, and a separate <tt class="literal"><span class="pre">iterator_adaptor</span></tt> layer would be
 impossible.</li>
@@ -437,9 +437,10 @@ is a class, however, it must still be possible to access members
 through <tt class="literal"><span class="pre">operator-&gt;</span></tt>.  Therefore, an iterator whose <tt class="literal"><span class="pre">reference</span></tt>
 type is not in fact a reference must return a proxy containing a copy
 of the referenced value from its <tt class="literal"><span class="pre">operator-&gt;</span></tt>.</p>
-<p>The return type for <tt class="literal"><span class="pre">operator-&gt;</span></tt> and <tt class="literal"><span class="pre">operator[]</span></tt> is not
-explicitly specified. Instead it requires each <tt class="literal"><span class="pre">iterator_facade</span></tt>
-specialization to meet the requirements of its <tt class="literal"><span class="pre">iterator_category</span></tt>.</p>
+<p>The return types for <tt class="literal"><span class="pre">iterator_facade</span></tt>'s <tt class="literal"><span class="pre">operator-&gt;</span></tt> and
+<tt class="literal"><span class="pre">operator[]</span></tt> are not explicitly specified. Instead, those types
+are described in terms of a set of requirements, which must be
+satisfied by the <tt class="literal"><span class="pre">iterator_facade</span></tt> implementation.</p>
 <table class="citation" frame="void" id="cop95" rules="none">
 <colgroup><col class="label" /><col /></colgroup>
 <col />
@@ -707,8 +708,9 @@ struct enable_if_interoperable
     &gt;
 {};
 </pre>
+</div>
 <div class="section" id="iterator-facade-requirements">
-<h4><a class="toc-backref" href="#id29" name="iterator-facade-requirements"><tt class="literal"><span class="pre">iterator_facade</span></tt> Requirements</a></h4>
+<h3><a class="toc-backref" href="#id29" name="iterator-facade-requirements"><tt class="literal"><span class="pre">iterator_facade</span></tt> Requirements</a></h3>
 <p>The following table describes the typical valid expressions on
 <tt class="literal"><span class="pre">iterator_facade</span></tt>'s <tt class="literal"><span class="pre">Derived</span></tt> parameter, depending on the
 iterator concept(s) it will model.  The operations in the first
@@ -789,7 +791,7 @@ Iterator</td>
 </div>
 <a class="target" id="facade-iterator-category" name="facade-iterator-category"></a></div>
 <div class="section" id="iterator-facade-iterator-category">
-<h4><a class="toc-backref" href="#id30" name="iterator-facade-iterator-category"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></h4>
+<h3><a class="toc-backref" href="#id30" name="iterator-facade-iterator-category"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></h3>
 <p>The <tt class="literal"><span class="pre">iterator_category</span></tt> member of <tt class="literal"><span class="pre">iterator_facade&lt;X,V,R,C,D&gt;</span></tt>
 is a type which satisfies the following conditions:</p>
 <blockquote>
@@ -842,7 +844,7 @@ convertible, and not to any more-derived traversal tag type.</p>
 </blockquote>
 </div>
 <div class="section" id="iterator-facade-operations">
-<h4><a class="toc-backref" href="#id31" name="iterator-facade-operations"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></h4>
+<h3><a class="toc-backref" href="#id31" name="iterator-facade-operations"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></h3>
 <p>The operations in this section are described in terms of operations on
 the core interface of <tt class="literal"><span class="pre">Derived</span></tt> which may be inaccessible
 (i.e. private).  The implementation should access these operations
@@ -983,7 +985,6 @@ return tmp -= n;
 </table>
 </div>
 </div>
-</div>
 <div class="section" id="iterator-adaptor-lib-iterator-adaptor">
 <h2><a class="toc-backref" href="#id32" name="iterator-adaptor-lib-iterator-adaptor">Iterator adaptor [lib.iterator.adaptor]</a></h2>
 <!-- Version 1.1 of this ReStructuredText document corresponds to
@@ -2237,7 +2238,7 @@ LocalWords:  OtherIncrementable Coplien -->
 <hr class="footer" />
 <div class="footer">
 <a class="reference" href="facade-and-adaptor.rst">View document source</a>.
-Generated on: 2004-01-12 16:01 UTC.
+Generated on: 2004-01-12 17:28 UTC.
 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
 </div>
 </body>
diff --git a/doc/iterator_facade.html b/doc/iterator_facade.html
index d825dec..5bb637f 100644
--- a/doc/iterator_facade.html
+++ b/doc/iterator_facade.html
@@ -45,19 +45,19 @@ and associated types, to be supplied by a derived iterator class.</td>
 <div class="contents topic" id="table-of-contents">
 <p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>
 <ul class="simple">
-<li><a class="reference" href="#a-facade-for-iterator-implementation" id="id21" name="id21">A Facade for Iterator Implementation</a><ul>
+<li><a class="reference" href="#overview" id="id21" name="id21">Overview</a><ul>
 <li><a class="reference" href="#usage" id="id22" name="id22">Usage</a></li>
 <li><a class="reference" href="#iterator-core-access" id="id23" name="id23">Iterator Core Access</a></li>
 <li><a class="reference" href="#operator" id="id24" name="id24"><tt class="literal"><span class="pre">operator[]</span></tt></a></li>
 <li><a class="reference" href="#id2" id="id25" name="id25"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></li>
+</ul>
+</li>
 <li><a class="reference" href="#reference" id="id26" name="id26">Reference</a><ul>
 <li><a class="reference" href="#iterator-facade-requirements" id="id27" name="id27"><tt class="literal"><span class="pre">iterator_facade</span></tt> Requirements</a></li>
 <li><a class="reference" href="#iterator-facade-iterator-category" id="id28" name="id28"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></li>
 <li><a class="reference" href="#iterator-facade-operations" id="id29" name="id29"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></li>
 </ul>
 </li>
-</ul>
-</li>
 <li><a class="reference" href="#tutorial-example" id="id30" name="id30">Tutorial Example</a><ul>
 <li><a class="reference" href="#the-problem" id="id31" name="id31">The Problem</a></li>
 <li><a class="reference" href="#a-basic-iterator-using-iterator-facade" id="id32" name="id32">A Basic Iterator Using <tt class="literal"><span class="pre">iterator_facade</span></tt></a><ul>
@@ -81,8 +81,8 @@ and associated types, to be supplied by a derived iterator class.</td>
 </li>
 </ul>
 </div>
-<div class="section" id="a-facade-for-iterator-implementation">
-<h1><a class="toc-backref" href="#id21" name="a-facade-for-iterator-implementation">A Facade for Iterator Implementation</a></h1>
+<div class="section" id="overview">
+<h1><a class="toc-backref" href="#id21" name="overview">Overview</a></h1>
 <!-- Version 1.1 of this ReStructuredText document corresponds to
 n1530_, the paper accepted by the LWG for TR1. -->
 <!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
@@ -102,11 +102,11 @@ identified the following core behaviors for iterators:</p>
 include the associated types exposed through iterator traits:
 <tt class="literal"><span class="pre">value_type</span></tt>, <tt class="literal"><span class="pre">reference</span></tt>, <tt class="literal"><span class="pre">difference_type</span></tt>, and
 <tt class="literal"><span class="pre">iterator_category</span></tt>.</p>
-<p>Iterator facade uses the Curiously Recurring Template Pattern (CRTP)
-<a class="citation-reference" href="#cop95" id="id1" name="id1">[Cop95]</a> so that the user can specify the behavior of
-<tt class="literal"><span class="pre">iterator_facade</span></tt> in a derived class.  Former designs used policy
-objects to specify the behavior.  <tt class="literal"><span class="pre">iterator_facade</span></tt> does not use policy
-objects for several reasons:</p>
+<p>Iterator facade uses the Curiously Recurring Template
+Pattern (CRTP) <a class="citation-reference" href="#cop95" id="id1" name="id1">[Cop95]</a> so that the user can specify the behavior
+of <tt class="literal"><span class="pre">iterator_facade</span></tt> in a derived class.  Former designs used
+policy objects to specify the behavior, but that approach was
+discarded for several reasons:</p>
 <blockquote>
 <ol class="arabic simple">
 <li>the creation and eventual copying of the policy object may create
@@ -116,9 +116,11 @@ on the created iterator types, an essential feature if
 <tt class="literal"><span class="pre">iterator_facade</span></tt> should be used in other library
 implementations.</li>
 <li>Without the use of CRTP, the standard requirement that an
-iterator's <tt class="literal"><span class="pre">operator++</span></tt> returns the iterator type itself means
-that all iterators generated by <tt class="literal"><span class="pre">iterator_facade</span></tt> would be
-specializations of <tt class="literal"><span class="pre">iterator_facade</span></tt>.  Cumbersome type generator
+iterator's <tt class="literal"><span class="pre">operator++</span></tt> returns the iterator type itself
+would mean that all iterators built with the library would
+have to be specializations of <tt class="literal"><span class="pre">iterator_facade&lt;...&gt;</span></tt>, rather
+than something more descriptive like
+<tt class="literal"><span class="pre">indirect_iterator&lt;T*&gt;</span></tt>.  Cumbersome type generator
 metafunctions would be needed to build new parameterized
 iterators, and a separate <tt class="literal"><span class="pre">iterator_adaptor</span></tt> layer would be
 impossible.</li>
@@ -254,9 +256,10 @@ is a class, however, it must still be possible to access members
 through <tt class="literal"><span class="pre">operator-&gt;</span></tt>.  Therefore, an iterator whose <tt class="literal"><span class="pre">reference</span></tt>
 type is not in fact a reference must return a proxy containing a copy
 of the referenced value from its <tt class="literal"><span class="pre">operator-&gt;</span></tt>.</p>
-<p>The return type for <tt class="literal"><span class="pre">operator-&gt;</span></tt> and <tt class="literal"><span class="pre">operator[]</span></tt> is not
-explicitly specified. Instead it requires each <tt class="literal"><span class="pre">iterator_facade</span></tt>
-specialization to meet the requirements of its <tt class="literal"><span class="pre">iterator_category</span></tt>.</p>
+<p>The return types for <tt class="literal"><span class="pre">iterator_facade</span></tt>'s <tt class="literal"><span class="pre">operator-&gt;</span></tt> and
+<tt class="literal"><span class="pre">operator[]</span></tt> are not explicitly specified. Instead, those types
+are described in terms of a set of requirements, which must be
+satisfied by the <tt class="literal"><span class="pre">iterator_facade</span></tt> implementation.</p>
 <table class="citation" frame="void" id="cop95" rules="none">
 <colgroup><col class="label" /><col /></colgroup>
 <col />
@@ -266,8 +269,9 @@ Patterns, C++ Report, February 1995, pp. 24-27.</td></tr>
 </tbody>
 </table>
 </div>
+</div>
 <div class="section" id="reference">
-<h2><a class="toc-backref" href="#id26" name="reference">Reference</a></h2>
+<h1><a class="toc-backref" href="#id26" name="reference">Reference</a></h1>
 <!-- Version 1.3 of this ReStructuredText document corresponds to
 n1530_, the paper accepted by the LWG for TR1. -->
 <!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
@@ -379,7 +383,7 @@ struct enable_if_interoperable
 {};
 </pre>
 <div class="section" id="iterator-facade-requirements">
-<h3><a class="toc-backref" href="#id27" name="iterator-facade-requirements"><tt class="literal"><span class="pre">iterator_facade</span></tt> Requirements</a></h3>
+<h2><a class="toc-backref" href="#id27" name="iterator-facade-requirements"><tt class="literal"><span class="pre">iterator_facade</span></tt> Requirements</a></h2>
 <p>The following table describes the typical valid expressions on
 <tt class="literal"><span class="pre">iterator_facade</span></tt>'s <tt class="literal"><span class="pre">Derived</span></tt> parameter, depending on the
 iterator concept(s) it will model.  The operations in the first
@@ -460,7 +464,7 @@ Iterator</td>
 </div>
 <a class="target" id="facade-iterator-category" name="facade-iterator-category"></a></div>
 <div class="section" id="iterator-facade-iterator-category">
-<h3><a class="toc-backref" href="#id28" name="iterator-facade-iterator-category"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></h3>
+<h2><a class="toc-backref" href="#id28" name="iterator-facade-iterator-category"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></h2>
 <p>The <tt class="literal"><span class="pre">iterator_category</span></tt> member of <tt class="literal"><span class="pre">iterator_facade&lt;X,V,R,C,D&gt;</span></tt>
 is a type which satisfies the following conditions:</p>
 <blockquote>
@@ -513,7 +517,7 @@ convertible, and not to any more-derived traversal tag type.</p>
 </blockquote>
 </div>
 <div class="section" id="iterator-facade-operations">
-<h3><a class="toc-backref" href="#id29" name="iterator-facade-operations"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></h3>
+<h2><a class="toc-backref" href="#id29" name="iterator-facade-operations"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></h2>
 <p>The operations in this section are described in terms of operations on
 the core interface of <tt class="literal"><span class="pre">Derived</span></tt> which may be inaccessible
 (i.e. private).  The implementation should access these operations
@@ -654,7 +658,6 @@ return tmp -= n;
 </table>
 </div>
 </div>
-</div>
 <div class="section" id="tutorial-example">
 <h1><a class="toc-backref" href="#id30" name="tutorial-example">Tutorial Example</a></h1>
 <!-- Copyright David Abrahams 2004. Use, modification and distribution is -->
@@ -1129,7 +1132,7 @@ even be superior.</p>
 <hr class="footer" />
 <div class="footer">
 <a class="reference" href="iterator_facade.rst">View document source</a>.
-Generated on: 2004-01-12 15:49 UTC.
+Generated on: 2004-01-12 17:28 UTC.
 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
 </div>
 </body>
diff --git a/doc/iterator_facade.rst b/doc/iterator_facade.rst
index b7b0397..41a775f 100644
--- a/doc/iterator_facade.rst
+++ b/doc/iterator_facade.rst
@@ -20,14 +20,14 @@
 
 .. contents:: Table of Contents
 
-A Facade for Iterator Implementation
-====================================
+Overview
+========
 
 .. include:: iterator_facade_body.rst
 
 
 Reference
----------
+=========
 
 .. include:: iterator_facade_ref.rst
 
diff --git a/doc/iterator_facade_body.rst b/doc/iterator_facade_body.rst
index 370539d..82f57a1 100644
--- a/doc/iterator_facade_body.rst
+++ b/doc/iterator_facade_body.rst
@@ -21,11 +21,11 @@ include the associated types exposed through iterator traits:
 ``value_type``, ``reference``, ``difference_type``, and
 ``iterator_category``.
 
-Iterator facade uses the Curiously Recurring Template Pattern (CRTP)
-[Cop95]_ so that the user can specify the behavior of
-``iterator_facade`` in a derived class.  Former designs used policy
-objects to specify the behavior.  ``iterator_facade`` does not use policy
-objects for several reasons: 
+Iterator facade uses the Curiously Recurring Template
+Pattern (CRTP) [Cop95]_ so that the user can specify the behavior
+of ``iterator_facade`` in a derived class.  Former designs used
+policy objects to specify the behavior, but that approach was
+discarded for several reasons:
 
   1. the creation and eventual copying of the policy object may create
      overhead that can be avoided with the current approach.
@@ -36,9 +36,11 @@ objects for several reasons:
      implementations.
 
   3. Without the use of CRTP, the standard requirement that an
-     iterator's ``operator++`` returns the iterator type itself means
-     that all iterators generated by ``iterator_facade`` would be
-     specializations of ``iterator_facade``.  Cumbersome type generator
+     iterator's ``operator++`` returns the iterator type itself
+     would mean that all iterators built with the library would
+     have to be specializations of ``iterator_facade<...>``, rather
+     than something more descriptive like
+     ``indirect_iterator<T*>``.  Cumbersome type generator
      metafunctions would be needed to build new parameterized
      iterators, and a separate ``iterator_adaptor`` layer would be
      impossible.
@@ -180,10 +182,10 @@ through ``operator->``.  Therefore, an iterator whose ``reference``
 type is not in fact a reference must return a proxy containing a copy
 of the referenced value from its ``operator->``.
 
-The return type for ``operator->`` and ``operator[]`` is not
-explicitly specified. Instead it requires each ``iterator_facade``
-specialization to meet the requirements of its ``iterator_category``.
-
+The return types for ``iterator_facade``\ 's ``operator->`` and
+``operator[]`` are not explicitly specified. Instead, those types
+are described in terms of a set of requirements, which must be
+satisfied by the ``iterator_facade`` implementation.
 
 .. [Cop95] [Coplien, 1995] Coplien, J., Curiously Recurring Template
    Patterns, C++ Report, February 1995, pp. 24-27.
diff --git a/doc/iterator_facade_ref.rst b/doc/iterator_facade_ref.rst
index f879971..2fa7a5c 100644
--- a/doc/iterator_facade_ref.rst
+++ b/doc/iterator_facade_ref.rst
@@ -121,7 +121,7 @@ were defined to be::
 
 
 ``iterator_facade`` Requirements
-................................
+--------------------------------
 
 The following table describes the typical valid expressions on
 ``iterator_facade``\ 's ``Derived`` parameter, depending on the
@@ -170,7 +170,7 @@ interoperable with ``X``.
 .. _facade iterator category:
 
 ``iterator_facade`` iterator category
-.....................................
+-------------------------------------
 
 The ``iterator_category`` member of ``iterator_facade<X,V,R,C,D>``
 is a type which satisfies the following conditions:
@@ -218,7 +218,7 @@ is a type which satisfies the following conditions:
 
 
 ``iterator_facade`` operations
-..............................
+------------------------------
 
 The operations in this section are described in terms of operations on
 the core interface of ``Derived`` which may be inaccessible