Documentation fixes, added AutoIndex indexes

[SVN r74154]
2025-08-02 22:14:26 +02:00 · 2011-08-30 12:23:34 +00:00
parent 46d4f1e294
commit 90782d289b
6 changed files with 73 additions and 131 deletions
--- a/doc/Jamfile.v2
+++ b/doc/Jamfile.v2
@@ -10,6 +10,8 @@
 import doxygen ;
 import quickbook ;

+using auto-index ;
+
 path-constant images_location : html ;

 doxygen autodoc
@@ -29,10 +31,13 @@ doxygen autodoc
                                   \"BOOST_RV_REF_2_TEMPL_ARGS(T,a,b)=T<a, b> &&\" \\
                                   \"BOOST_RV_REF_3_TEMPL_ARGS(T,a,b,c)=T<a,b,c>T<a,b,c> &&\" \\
                                   \"BOOST_FWD_REF(a)=a &&\""
-        <xsl:param>"boost.doxygen.reftitle=Boost.Container Reference"
+        <xsl:param>"boost.doxygen.reftitle=Boost.Container Header Reference"
   ;

-xml container : container.qbk ;
+xml container : container.qbk 
+              : 
+                 <include>../../../tools/auto_index/include
+              ;

 boostbook standalone
   :
@@ -45,4 +50,33 @@ boostbook standalone
        <format>pdf:<xsl:param>img.src.path=$(images_location)/
        <dependency>autodoc
        <format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/doc/html
+
+        # Build requirements go here:
+        
+        # <auto-index>on (or off) one turns on (or off) indexing:
+        <auto-index>on
+        
+        # Turns on (or off) auto-index-verbose for diagnostic info.
+        # This is highly recommended until you have got all the many details correct!
+        <auto-index-verbose>on 
+        
+        # Choose the indexing method (separately for html and PDF) - see manual.
+        # Choose indexing method for PDFs:
+        <format>pdf:<auto-index-internal>off
+        
+        # Choose indexing method for html:
+        <format>html:<auto-index-internal>on
+        
+        # Set the name of the script file to use (index.idx is popular):
+        <auto-index-script>index.idx
+        # Commands in the script file should all use RELATIVE PATHS
+        # otherwise the script will not be portable to other machines.
+        # Relative paths are normally taken as relative to the location 
+        # of the script file, but we can add a prefix to all
+        # those relative paths using the <auto-index-prefix> feature.
+        # The path specified by <auto-index-prefix> may be either relative or
+        # absolute, for example the following will get us up to the boost root
+        # directory for most Boost libraries:
+        <auto-index-prefix>"../../.."
+
   ;
--- a/doc/container.qbk
+++ b/doc/container.qbk
@@ -70,7 +70,7 @@ compiler include path.
 [section:move_emplace Efficient insertion]

 Move semantics and placement insertion are two features brought by C++11 containers
-that can have a very positive impacto in your C++ applications. Boost.Container implements
+that can have a very positive impact in your C++ applications. Boost.Container implements
 both techniques both for C++11 and C++03 compilers.

 [section:move_containers Move-aware containers]
@@ -82,7 +82,7 @@ movable or default constructible types instead of just copy constructible types.

 Containers themselves are also movable, with no-throw guarantee if allocator
 or predicate (if present) copy operations are no-throw. This allows
-high performance operations when transfering data between vectors.
+high performance operations when transferring data between vectors.
 Let's see an example:

 [import ../example/doc_move_containers.cpp]
@@ -311,7 +311,7 @@ likely to insert a new element anywhere, you'll be shifting N/2 elements.]]
 This class does not satisfy the requirements of a Standard Associative Container, since the complexity of insert is
 O(N) rather than O(log N), but otherwise it is almost a drop-in replacement for set.]]

-Following Matt Austerns indications, Andrei Alexandrescu's
+Following Matt Austern's indications, Andrei Alexandrescu's
 [@http://www.bestwebbuys.com/Modern-C-Design-Generic-Programming-and-Design-Patterns-Applied-ISBN-9780201704310?isrc=-rd Modern C++ Design]
 showed `AssocVector`, a `std::map` drop-in
 replacement designed in his [@http://loki-lib.sourceforge.net/ Loki] library:
@@ -427,12 +427,12 @@ Many C++ container implementors felt C++03 guarantees were too weak and started
 containers experience supporting stateful allocators, offers the following guarantees:

 * Allocators are copy-constructed in copy/move constructors
-* If possible, asingle allocator is hold to construct `value_type` and this allocator is copy constructed
-  from the user-supplied allocator object during container's contructor. If the container needs an auxiliary 
+* If possible, a single allocator is hold to construct `value_type` and this allocator is copy constructed
+  from the user-supplied allocator object during container's constructor. If the container needs an auxiliary 
  allocator (e.g. a array allocator used by `deque` or `stable_vector`), that allocator is also 
  copy-constructed from the user-supplied allocator when the container is constructed (i.e. it's 
  not constructed on the fly when auxiliary memory is needed).
-* Allocators are compared for equality when swapping containers. If allocators dont' compare
+* Allocators are compared for equality when swapping containers. If allocators don't compare
  equal allocators are swapped using an unqualified `swap` call.

 C++11 further improves stateful allocator support through the
@@ -491,8 +491,8 @@ If you need a memory optimized version of `boost::container::vector<bool>` funct
  with an internal buffer of 11/23 bytes (32/64 bit systems)
  [*without] increasing the usual `sizeof` of the string (3 words).

-* `[multi]set/map` containers are size optimized embedding the color bit of the red-black trees into
-   the parent pointer.
+* `[multi]set/map` containers are size optimized embedding the color bit of the red-black tree nodes
+   in the parent pointer.

 * `[multi]set/map` containers use no recursive functions so stack problems are avoided.

@@ -502,7 +502,8 @@ If you need a memory optimized version of `boost::container::vector<bool>` funct

 [section:boost_container_history Boost.Container history]

-[*Boost.Container] is a product of a long development effort that started with the experimental Shmem library,
+[*Boost.Container] is a product of a long development effort that started
+[@http://lists.boost.org/Archives/boost/2004/11/76263.php in 2004 with the experimental Shmem library],
 which pioneered the use of standard containers in shared memory. Shmem included modified SGI STL container
 code tweaked to support non-raw `allocator::pointer` types and stateful allocators. Once reviewed,
 Shmem was accepted as [@http://www.boost.org/libs/interprocess/ Boost.Interprocess] and this library
@@ -525,34 +526,45 @@ collect them containers and build [*Boost.Container], a library targeted to a wi

 [section:Why_boost_container Why Boost.Container?]

-With so many high quality standard library implemenations out there, why would you want to
+With so many high quality standard library implementations out there, why would you want to
 use [*Boost.Container]? There are several reasons for that:

 * If you have a C++03 compiler, you can have access to C++11 features and have an easy
  code migration when you change your compiler.
 * It's compatible with [*Boost.Interprocess] shared memory allocators.
 * You have extremely useful new containers like `stable_vector` and `flat_[multi]set/map`.
-* If you work on multiple plataforms, you'll have a portable behaviour without depending
+* If you work on multiple platforms, you'll have a portable behaviour without depending
  on the std-lib implementation conformance of each platform. Some examples:
   * Default constructors don't allocate memory at all, which improves performance and
   usually implies a no-throw guarantee (if predicate's or allocator's default constructor doesn't throw).
   * Small string optimization for [classref boost::container::basic_string basic_string].
-* New extensions beyond the standard based on user feedbak to improve code performance.
+* New extensions beyond the standard based on user feedback to improve code performance.

 [endsect]

 [endsect]

+[include auto_index_helpers.qbk]

+[section:index Indexes]

+[named_index class_name Class Index]
+[named_index typedef_name Typedef Index]
+[named_index function_name Function Index]
+[/named_index macro_name Macro Index]
+[/index]
+
+[endsect]
+
+[xinclude autodoc.xml]

 [section:acknowledgements_notes Acknowledgements, notes and links]

 *  Original standard container code comes from [@http://www.sgi.com/tech/stl/ SGI STL library],
   which enhanced the original HP STL code. Most of this code was rewritten for
   [*Boost.Interprocess] and moved to [*Boost.Intrusive]. `deque` and `string` containers still
-   have fragments of the original SGI code. Many thanks to Alexander Stepanov, Meng Lee, and David Musser,
-   Matt Austern, and all HP and SGI STL developers.
+   have fragments of the original SGI code. Many thanks to Alexander Stepanov, Meng Lee, David Musser,
+   Matt Austern... and all HP and SGI STL developers.

 *  `flat_[multi]_map/set` containers were originally based on [@http://en.wikipedia.org/wiki/Loki_%28C%2B%2B%29 Loki's]
   AssocVector class. Code was rewritten and expanded for [*Boost.Interprocess], so thanks to Andrei Alexandrescu.
@@ -561,12 +573,12 @@ use [*Boost.Container]? There are several reasons for that:
   [@http://bannalia.blogspot.com/2008/09/introducing-stablevector.html Joaqu\u00EDn M. L\u00F3pez Mu\u00F1oz],
   then adapted for [*Boost.Interprocess]. Thanks for such a great container.

-*  Howard Hinnant's help and experience was essential when implementing move semantics, 
-   improving allocator support and implementing small string optimization. Thanks Howard
+*  Howard Hinnant's help and advices were essential when implementing move semantics, 
+   improving allocator support or implementing small string optimization. Thanks Howard
   for your wonderful standard library implementations.

 *  And finally thanks to all Boosters who helped all these years, improving, fixing and
-   reviewing the library.
+   reviewing all my libraries.

 [endsect]

@@ -576,5 +588,3 @@ use [*Boost.Container]? There are several reasons for that:
   and redirected to [*Boost.Container ] via using directives.

 [endsect]
-
-[xinclude autodoc.xml]
--- a/doc/html/index.html
+++ b/doc/html/index.html
@@ -1,110 +0,0 @@
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
-<title>Chapter&#160;1.&#160;Boost.Container</title>
-<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.67.0">
-<link rel="start" href="index.html" title="Chapter&#160;1.&#160;Boost.Container">
-<link rel="next" href="container/intro.html" title="Introduction">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<table cellpadding="2" width="100%"><tr>
-<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
-<td align="center"><a href="../../../../index.html">Home</a></td>
-<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
-<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
-<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
-<td align="center"><a href="../../../../more/index.htm">More</a></td>
-</tr></table>
-<hr>
-<div class="spirit-nav"><a accesskey="n" href="container/intro.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div>
-<div class="chapter" lang="en">
-<div class="titlepage"><div>
-<div><h2 class="title">
-<a name="container"></a>Chapter&#160;1.&#160;Boost.Container</h2></div>
-<div><div class="author"><h3 class="author">
-<span class="firstname">Ion</span> <span class="surname">Gaztanaga</span>
-</h3></div></div>
-<div><p class="copyright">Copyright &#169; 2009-2011 Ion Gaztanaga</p></div>
-<div><div class="legalnotice">
-<a name="id706806"></a><p>
-        Distributed under the Boost Software License, Version 1.0. (See accompanying
-        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
-      </p>
-</div></div>
-</div></div>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl>
-<dt><span class="section"><a href="container/intro.html">Introduction</a></span></dt>
-<dd><dl>
-<dt><span class="section"><a href="container/intro.html#container.intro.introduction_building_container">Building
-      Boost.Container</a></span></dt>
-<dt><span class="section"><a href="container/intro.html#container.intro.tested_compilers">Tested compilers</a></span></dt>
-</dl></dd>
-<dt><span class="section"><a href="container/move_emplace.html">Efficient insertion</a></span></dt>
-<dd><dl>
-<dt><span class="section"><a href="container/move_emplace.html#container.move_emplace.move_containers">Move-aware containers</a></span></dt>
-<dt><span class="section"><a href="container/move_emplace.html#container.move_emplace.emplace">Emplace: Placement insertion</a></span></dt>
-</dl></dd>
-<dt><span class="section"><a href="container/containers_of_incomplete_types.html">Containers of
-    Incomplete Types</a></span></dt>
-<dd><dl>
-<dt><span class="section"><a href="container/containers_of_incomplete_types.html#container.containers_of_incomplete_types.recursive_containers">Recursive
-      containers</a></span></dt>
-<dt><span class="section"><a href="container/containers_of_incomplete_types.html#container.containers_of_incomplete_types.type_erasure">Type
-      Erasure</a></span></dt>
-</dl></dd>
-<dt><span class="section"><a href="container/non_standard_containers.html">Non-standard containers</a></span></dt>
-<dd><dl>
-<dt><span class="section"><a href="container/non_standard_containers.html#container.non_standard_containers.stable_vector"><span class="emphasis"><em>stable_vector</em></span></a></span></dt>
-<dt><span class="section"><a href="container/non_standard_containers.html#container.non_standard_containers.flat_xxx"><span class="emphasis"><em>flat_(multi)map/set</em></span>
-      associative containers</a></span></dt>
-<dt><span class="section"><a href="container/non_standard_containers.html#container.non_standard_containers.slist"><span class="emphasis"><em>slist</em></span></a></span></dt>
-</dl></dd>
-<dt><span class="section"><a href="container/Cpp11_conformance.html">C++11 Conformance</a></span></dt>
-<dd><dl>
-<dt><span class="section"><a href="container/Cpp11_conformance.html#container.Cpp11_conformance.move_emplace">Move and Emplace</a></span></dt>
-<dt><span class="section"><a href="container/Cpp11_conformance.html#container.Cpp11_conformance.alloc_traits_move_traits">Stateful
-      allocators and Scoped allocators</a></span></dt>
-<dt><span class="section"><a href="container/Cpp11_conformance.html#container.Cpp11_conformance.initializer_lists">Initializer
-      lists</a></span></dt>
-<dt><span class="section"><a href="container/Cpp11_conformance.html#container.Cpp11_conformance.Vector_bool">vector&lt;bool&gt;</a></span></dt>
-</dl></dd>
-<dt><span class="section"><a href="container/other_features.html">Other features</a></span></dt>
-<dt><span class="section"><a href="container/history_and_reasons.html">History and reasons to use
-    Boost.Container</a></span></dt>
-<dd><dl>
-<dt><span class="section"><a href="container/history_and_reasons.html#container.history_and_reasons.boost_container_history">Boost.Container
-      history</a></span></dt>
-<dt><span class="section"><a href="container/history_and_reasons.html#container.history_and_reasons.Why_boost_container">Why
-      Boost.Container?</a></span></dt>
-</dl></dd>
-<dt><span class="section"><a href="container/acknowledgements_notes.html">Acknowledgements, notes
-    and links</a></span></dt>
-<dt><span class="section"><a href="container/release_notes.html">Release Notes</a></span></dt>
-<dt><span class="section"><a href="boost_container_reference.html">Boost.Container Reference</a></span></dt>
-<dd><dl>
-<dt><span class="section"><a href="boost_container_reference.html#header.boost.container.container_fwd_hpp">Header &lt;boost/container/container_fwd.hpp&gt;</a></span></dt>
-<dt><span class="section"><a href="boost_container_reference.html#header.boost.container.deque_hpp">Header &lt;boost/container/deque.hpp&gt;</a></span></dt>
-<dt><span class="section"><a href="boost_container_reference.html#header.boost.container.flat_map_hpp">Header &lt;boost/container/flat_map.hpp&gt;</a></span></dt>
-<dt><span class="section"><a href="boost_container_reference.html#header.boost.container.flat_set_hpp">Header &lt;boost/container/flat_set.hpp&gt;</a></span></dt>
-<dt><span class="section"><a href="boost_container_reference.html#header.boost.container.list_hpp">Header &lt;boost/container/list.hpp&gt;</a></span></dt>
-<dt><span class="section"><a href="boost_container_reference.html#header.boost.container.map_hpp">Header &lt;boost/container/map.hpp&gt;</a></span></dt>
-<dt><span class="section"><a href="boost_container_reference.html#header.boost.container.set_hpp">Header &lt;boost/container/set.hpp&gt;</a></span></dt>
-<dt><span class="section"><a href="boost_container_reference.html#header.boost.container.slist_hpp">Header &lt;boost/container/slist.hpp&gt;</a></span></dt>
-<dt><span class="section"><a href="boost_container_reference.html#header.boost.container.stable_vector_hpp">Header &lt;boost/container/stable_vector.hpp&gt;</a></span></dt>
-<dt><span class="section"><a href="boost_container_reference.html#header.boost.container.string_hpp">Header &lt;boost/container/string.hpp&gt;</a></span></dt>
-<dt><span class="section"><a href="boost_container_reference.html#header.boost.container.vector_hpp">Header &lt;boost/container/vector.hpp&gt;</a></span></dt>
-</dl></dd>
-</dl>
-</div>
-</div>
-<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><p><small>Last revised: August 26, 2011 at 17:45:38 GMT</small></p></td>
-<td align="right"><div class="copyright-footer"></div></td>
-</tr></table>
-<hr>
-<div class="spirit-nav"><a accesskey="n" href="container/intro.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div>
-</body>
-</html>
--- a/doc/index.idx
+++ b/doc/index.idx
@@ -0,0 +1 @@
+!scan-path "boost/container" ".*.hpp" false 
--- a/include/boost/container/stable_vector.hpp
+++ b/include/boost/container/stable_vector.hpp
@@ -335,6 +335,8 @@ struct select_multiallocation_chain<A, 1>

 } //namespace stable_vector_detail

+#if !defined(BOOST_CONTAINER_DOXYGEN_INVOKED)
+
 #if defined(STABLE_VECTOR_ENABLE_INVARIANT_CHECKING)

 #define STABLE_VECTOR_CHECK_INVARIANT \
@@ -346,6 +348,8 @@ BOOST_JOIN(check_invariant_,__LINE__).touch();

 #endif   //#if defined(STABLE_VECTOR_ENABLE_INVARIANT_CHECKING)

+#endif   //#if !defined(BOOST_CONTAINER_DOXYGEN_INVOKED)
+
 /// @endcond

 //!Originally developed by Joaquin M. Lopez Munoz, stable_vector is std::vector
--- a/proj/vc7ide/container.vcproj
+++ b/proj/vc7ide/container.vcproj
@@ -180,6 +180,9 @@
 			<File
 				RelativePath="..\..\doc\container.qbk">
 			</File>
+			<File
+				RelativePath="..\..\doc\index.idx">
+			</File>
 			<File
 				RelativePath="..\..\doc\Jamfile.v2">
 			</File>
				`@@ -0,0 +1 @@`
				`!scan-path "boost/container" ".*.hpp" false`