Update docs, add build Jamfile.

[SVN r49860]

build/Jamfile.v2

@@ -0,0 +1,11 @@
+import quickbook ;
+
+exe auto_index : ../src/auto_index.cpp ../src/tiny_xml.cpp /boost/regex /boost/filesystem 
+: <define>BOOST_ALL_NO_LIB=1 <link>static
+;
+
+install dist : auto_index ;
+
+
+
+

doc/auto_index.qbk

@@ -161,9 +161,20 @@ We can also add terms manually:
    
 will index occurances of "foobar" and:
 
-   foo bar
+   foobar \<\w*(foo|bar)\w*\>
    
-will index occurances of "foo" under the name "bar".
+will index any whole word containing either "foo" or "bar" within it,
+this is useful when you want to index a lot of similar or related
+words under one entry, for example:
+
+   reflex
+   
+Will only index occurances of "reflex" as a whole word, but:
+
+   reflex \<reflex\w*\>
+   
+will index occurances of "reflex", reflexing" and 
+"reflexed" all under the same entry ['reflex].
 
 This inclusion rule can also restict the term to
 certain sections, and add an index category that
@@ -194,10 +205,124 @@ and the next iteration examined, and so on.
 
 [section:script_ref Script File Reference]
 
+The following elements can occur in a script:
+
+[h4 Simple Inclusions]
+
+   term [regular-expression1 [regular-expression2 [category]]]
+   
+[variablelist
+[[term][The term to index: this will form a primary entry in the Index
+with the section title(s) containing the term as secondary entries, and
+also will be used as a secondary entry beneath each of the section
+titles that the term occurs in.]]
+
+[[regular-expression1][An optional regular expression: each occurance
+of the regular expression in the text of the document will result
+in one index term being emitted.
+
+If the regular expression is omitted or is "", then the ['term] itself
+will be used as the search text - and only occurance of whole words matching
+['term] will be indexed.]]
+
+[[regular-expression2][A constraint that specifies which sections are
+indexed for ['term]: only if the ID of the section matches
+['regular-expression2] exactly will that section be indexed for occurances
+of ['term].
+
+For example:
+
+   `myclass "" "mylib.examples.*"`
+   
+Will index occurances of "myclass" as a whole word only in sections
+whose ID begins "mylib.examples", while:
+
+   `myclass "" "(?!mylib.introduction.*).*"`
+   
+will index occurances of "myclass" in any section, except those whose
+ID's begin "mylib.introduction".]]
+
+[[category][Optionally an index category to place occurances of
+['term] in.  If you have multiple indexes then this is the name
+assigned to the indexes "type" attribute.
+]]
+
+]
+
+[h4 Source File Scanning]
+
+   !scan source-file-name
+   
+Scans the C\/C++ source file ['source-file-name] for definitions of
+['function]'s, ['class]'s, ['macro]'s or ['typedef]'s and makes each of
+these a term to be indexed.  Terms found are assigned to the index category
+"function_name", "class_name", "macro_name" or "typedef_name" depending
+on how they were seen in the source file.  These may then be included
+in a specialised index whose "type" attribute has the same category name.
+
+[h4 Directory and Source File Scanning]
+
+   !scan-path directory-name file-name-regex [recurse]
+   
+[variablelist
+[[directory-name][The directory to scan: this should be a path relative
+to the script file and should use all forward slashes in it's file name.]]
+
+[[file-name-regex][A regular expression: any file in the directory whose name
+matches the regular expression will be scanned for terms to index.]]
+
+[[recurse][An optional boolian value - either "true" or "false" - that
+indicates whether to recurse into subdirectories.]]
+]
+
+[h4 Excluding Terms]
+
+   !exclude term-list
+   
+Excludes all the terms in whitespace separated ['term-list] from being indexed.
+This should be placed /after/ any ['!scan] or ['!scan-path] rules which may
+result in the terms becoming included.
+
+[h4 Rewriting Section Names]
+
+   !rewrite-id regular-expression new-name
+   
+[variablelist
+[[regular-expression][A regular expression: all section ID's that match
+the expression exactly will have index entries ['new-name] instead of 
+their title(s).]]
+
+[[new-name][The name that the section will appear under in the index.]]
+]
+
+   !rewrite-name regular-expression format-text
+   
+[variablelist
+[[regular-expression][A regular expression: all sections whose titles
+match the regular expression exactly, will have index entries composed
+of the regular expression match combined with the regex format string
+['format-text].]]
+[[format-text][The Perl-style format string used to reformat the title.]]
+]
 
 [endsect]
 
 [section:comm_ref Command Line Reference]
 
+The following command line options are supported by auto_index:
+
+[variablelist
+[[in=infilename][Specifies the name of the XML input file to be indexed.]]
+[[out=outfilename][Specifies the name of the new XML file to create.]]
+[[scan=source-filename][Specifies that ['source-filename] should be scanned
+for terms to index.]]
+[[script=script-filename][Specifies the name of the script file to process.]]
+[[--no-duplicates][If a term occurs more than once in the same section, then
+include only one index entry.]]
+[[--internal-index][Specifies that auto_index should generate the actual
+indexes rather than inserting `<indexterm>`'s and leaving index generation
+to the XSL stylesheets.]]
+]
+
 [endsect]
 

doc/html/autoindex/comm_ref.html

@@ -21,9 +21,47 @@
 <div class="spirit-nav">
 <a accesskey="p" href="script_ref.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a>
 </div>
-<div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
 <a name="autoindex.comm_ref"></a><a class="link" href="comm_ref.html" title="Command Line Reference"> Command Line Reference</a>
-</h2></div></div></div></div>
+</h2></div></div></div>
+<p>
+      The following command line options are supported by auto_index:
+    </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">in=infilename</span></dt>
+<dd><p>
+          Specifies the name of the XML input file to be indexed.
+        </p></dd>
+<dt><span class="term">out=outfilename</span></dt>
+<dd><p>
+          Specifies the name of the new XML file to create.
+        </p></dd>
+<dt><span class="term">scan=source-filename</span></dt>
+<dd><p>
+          Specifies that <span class="emphasis"><em>source-filename</em></span> should be scanned for
+          terms to index.
+        </p></dd>
+<dt><span class="term">script=script-filename</span></dt>
+<dd><p>
+          Specifies the name of the script file to process.
+        </p></dd>
+<dt><span class="term">--no-duplicates</span></dt>
+<dd><p>
+          If a term occurs more than once in the same section, then include only
+          one index entry.
+        </p></dd>
+<dt><span class="term">--internal-index</span></dt>
+<dd><p>
+          Specifies that auto_index should generate the actual indexes rather than
+          inserting <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">indexterm</span><span class="special">&gt;</span></code>'s and leaving index generation to the
+          XSL stylesheets.
+        </p></dd>
+</dl>
+</div>
+</div>
 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 <td align="left"></td>
 <td align="right"><div class="copyright-footer">Copyright © 2008 John Maddock<p>

doc/html/autoindex/script_ref.html

@@ -22,9 +22,170 @@
 <div class="spirit-nav">
 <a accesskey="p" href="tut.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="comm_ref.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
 </div>
-<div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
 <a name="autoindex.script_ref"></a><a class="link" href="script_ref.html" title="Script File Reference"> Script File Reference</a>
-</h2></div></div></div></div>
+</h2></div></div></div>
+<p>
+      The following elements can occur in a script:
+    </p>
+<a name="autoindex.script_ref.simple_inclusions"></a><h5>
+<a name="id527549"></a>
+      <a class="link" href="script_ref.html#autoindex.script_ref.simple_inclusions">Simple Inclusions</a>
+    </h5>
+<pre class="programlisting"><span class="identifier">term</span> <span class="special">[</span><span class="identifier">regular</span><span class="special">-</span><span class="identifier">expression1</span> <span class="special">[</span><span class="identifier">regular</span><span class="special">-</span><span class="identifier">expression2</span> <span class="special">[</span><span class="identifier">category</span><span class="special">]]]</span>
+</pre>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">term</span></dt>
+<dd><p>
+          The term to index: this will form a primary entry in the Index with the
+          section title(s) containing the term as secondary entries, and also will
+          be used as a secondary entry beneath each of the section titles that the
+          term occurs in.
+        </p></dd>
+<dt><span class="term">regular-expression1</span></dt>
+<dd>
+<p>
+          An optional regular expression: each occurance of the regular expression
+          in the text of the document will result in one index term being emitted.
+        </p>
+<p>
+          If the regular expression is omitted or is "", then the <span class="emphasis"><em>term</em></span>
+          itself will be used as the search text - and only occurance of whole words
+          matching <span class="emphasis"><em>term</em></span> will be indexed.
+        </p>
+</dd>
+<dt><span class="term">regular-expression2</span></dt>
+<dd>
+<p>
+          A constraint that specifies which sections are indexed for <span class="emphasis"><em>term</em></span>:
+          only if the ID of the section matches <span class="emphasis"><em>regular-expression2</em></span>
+          exactly will that section be indexed for occurances of <span class="emphasis"><em>term</em></span>.
+        </p>
+<p>
+          For example:
+        </p>
+<p>
+          <code class="computeroutput"><span class="identifier">myclass</span> <span class="string">""</span>
+          <span class="string">"mylib.examples.*"</span></code>
+        </p>
+<p>
+          Will index occurances of "myclass" as a whole word only in sections
+          whose ID begins "mylib.examples", while:
+        </p>
+<p>
+          <code class="computeroutput"><span class="identifier">myclass</span> <span class="string">""</span>
+          <span class="string">"(?!mylib.introduction.*).*"</span></code>
+        </p>
+<p>
+          will index occurances of "myclass" in any section, except those
+          whose ID's begin "mylib.introduction".
+        </p>
+</dd>
+<dt><span class="term">category</span></dt>
+<dd><p>
+          Optionally an index category to place occurances of <span class="emphasis"><em>term</em></span>
+          in. If you have multiple indexes then this is the name assigned to the
+          indexes "type" attribute.
+        </p></dd>
+</dl>
+</div>
+<a name="autoindex.script_ref.source_file_scanning"></a><h5>
+<a name="id527817"></a>
+      <a class="link" href="script_ref.html#autoindex.script_ref.source_file_scanning">Source File Scanning</a>
+    </h5>
+<pre class="programlisting"><span class="special">!</span><span class="identifier">scan</span> <span class="identifier">source</span><span class="special">-</span><span class="identifier">file</span><span class="special">-</span><span class="identifier">name</span>
+</pre>
+<p>
+      Scans the C/C++ source file <span class="emphasis"><em>source-file-name</em></span> for definitions
+      of <span class="emphasis"><em>function</em></span>'s, <span class="emphasis"><em>class</em></span>'s, <span class="emphasis"><em>macro</em></span>'s
+      or <span class="emphasis"><em>typedef</em></span>'s and makes each of these a term to be indexed.
+      Terms found are assigned to the index category "function_name", "class_name",
+      "macro_name" or "typedef_name" depending on how they were
+      seen in the source file. These may then be included in a specialised index
+      whose "type" attribute has the same category name.
+    </p>
+<a name="autoindex.script_ref.directory_and_source_file_scanning"></a><h5>
+<a name="id527916"></a>
+      <a class="link" href="script_ref.html#autoindex.script_ref.directory_and_source_file_scanning">Directory
+      and Source File Scanning</a>
+    </h5>
+<pre class="programlisting"><span class="special">!</span><span class="identifier">scan</span><span class="special">-</span><span class="identifier">path</span> <span class="identifier">directory</span><span class="special">-</span><span class="identifier">name</span> <span class="identifier">file</span><span class="special">-</span><span class="identifier">name</span><span class="special">-</span><span class="identifier">regex</span> <span class="special">[</span><span class="identifier">recurse</span><span class="special">]</span>
+</pre>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">directory-name</span></dt>
+<dd><p>
+          The directory to scan: this should be a path relative to the script file
+          and should use all forward slashes in it's file name.
+        </p></dd>
+<dt><span class="term">file-name-regex</span></dt>
+<dd><p>
+          A regular expression: any file in the directory whose name matches the
+          regular expression will be scanned for terms to index.
+        </p></dd>
+<dt><span class="term">recurse</span></dt>
+<dd><p>
+          An optional boolian value - either "true" or "false"
+          - that indicates whether to recurse into subdirectories.
+        </p></dd>
+</dl>
+</div>
+<a name="autoindex.script_ref.excluding_terms"></a><h5>
+<a name="id528079"></a>
+      <a class="link" href="script_ref.html#autoindex.script_ref.excluding_terms">Excluding Terms</a>
+    </h5>
+<pre class="programlisting"><span class="special">!</span><span class="identifier">exclude</span> <span class="identifier">term</span><span class="special">-</span><span class="identifier">list</span>
+</pre>
+<p>
+      Excludes all the terms in whitespace separated <span class="emphasis"><em>term-list</em></span>
+      from being indexed. This should be placed <span class="emphasis"><em>after</em></span> any <span class="emphasis"><em>!scan</em></span>
+      or <span class="emphasis"><em>!scan-path</em></span> rules which may result in the terms becoming
+      included.
+    </p>
+<a name="autoindex.script_ref.rewriting_section_names"></a><h5>
+<a name="id528160"></a>
+      <a class="link" href="script_ref.html#autoindex.script_ref.rewriting_section_names">Rewriting Section
+      Names</a>
+    </h5>
+<pre class="programlisting"><span class="special">!</span><span class="identifier">rewrite</span><span class="special">-</span><span class="identifier">id</span> <span class="identifier">regular</span><span class="special">-</span><span class="identifier">expression</span> <span class="keyword">new</span><span class="special">-</span><span class="identifier">name</span>
+</pre>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">regular-expression</span></dt>
+<dd><p>
+          A regular expression: all section ID's that match the expression exactly
+          will have index entries <span class="emphasis"><em>new-name</em></span> instead of their
+          title(s).
+        </p></dd>
+<dt><span class="term">new-name</span></dt>
+<dd><p>
+          The name that the section will appear under in the index.
+        </p></dd>
+</dl>
+</div>
+<pre class="programlisting"><span class="special">!</span><span class="identifier">rewrite</span><span class="special">-</span><span class="identifier">name</span> <span class="identifier">regular</span><span class="special">-</span><span class="identifier">expression</span> <span class="identifier">format</span><span class="special">-</span><span class="identifier">text</span>
+</pre>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">regular-expression</span></dt>
+<dd><p>
+          A regular expression: all sections whose titles match the regular expression
+          exactly, will have index entries composed of the regular expression match
+          combined with the regex format string <span class="emphasis"><em>format-text</em></span>.
+        </p></dd>
+<dt><span class="term">format-text</span></dt>
+<dd><p>
+          The Perl-style format string used to reformat the title.
+        </p></dd>
+</dl>
+</div>
+</div>
 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 <td align="left"></td>
 <td align="right"><div class="copyright-footer">Copyright © 2008 John Maddock<p>

doc/html/autoindex/tut.html

@@ -27,7 +27,7 @@
 <a name="autoindex.tut"></a><a class="link" href="tut.html" title="Getting Started and Tutorial"> Getting Started and Tutorial</a>
 </h2></div></div></div>
 <a name="autoindex.tut.step_1__build_the_tool"></a><h5>
-<a name="id473685"></a>
+<a name="id473689"></a>
       <a class="link" href="tut.html#autoindex.tut.step_1__build_the_tool">Step 1: Build the tool</a>
     </h5>
 <p>
@@ -42,7 +42,7 @@
 <pre class="programlisting"><span class="identifier">bjam</span> <span class="identifier">release</span> <span class="identifier">gcc</span>
 </pre>
 <a name="autoindex.tut.step_2__configure_boost_build"></a><h5>
-<a name="id473793"></a>
+<a name="id473797"></a>
       <a class="link" href="tut.html#autoindex.tut.step_2__configure_boost_build">Step 2: Configure
       Boost.Build</a>
     </h5>
@@ -53,7 +53,7 @@
       Currently the tool can only be run manually.
     </p>
 <a name="autoindex.tut.step_3__add_indexes_to_your_documentation"></a><h5>
-<a name="id475028"></a>
+<a name="id475023"></a>
       <a class="link" href="tut.html#autoindex.tut.step_3__add_indexes_to_your_documentation">Step
       3: Add indexes to your documentation</a>
     </h5>
@@ -93,7 +93,7 @@
 <pre class="programlisting"><span class="char">''</span><span class="char">'&lt;index/&gt;'</span><span class="char">''</span>
 </pre>
 <a name="autoindex.tut.step_4__create_the_script_file"></a><h5>
-<a name="id473476"></a>
+<a name="id473477"></a>
       <a class="link" href="tut.html#autoindex.tut.step_4__create_the_script_file">Step 4: Create
       the script file</a>
     </h5>
@@ -135,10 +135,23 @@
 <p>
       will index occurances of "foobar" and:
     </p>
-<pre class="programlisting"><span class="identifier">foo</span> <span class="identifier">bar</span>
+<pre class="programlisting"><span class="identifier">foobar</span> <span class="special">\&lt;\</span><span class="identifier">w</span><span class="special">*(</span><span class="identifier">foo</span><span class="special">|</span><span class="identifier">bar</span><span class="special">)\</span><span class="identifier">w</span><span class="special">*\&gt;</span>
 </pre>
 <p>
-      will index occurances of "foo" under the name "bar".
+      will index any whole word containing either "foo" or "bar"
+      within it, this is useful when you want to index a lot of similar or related
+      words under one entry, for example:
+    </p>
+<pre class="programlisting"><span class="identifier">reflex</span>
+</pre>
+<p>
+      Will only index occurances of "reflex" as a whole word, but:
+    </p>
+<pre class="programlisting"><span class="identifier">reflex</span> <span class="special">\&lt;</span><span class="identifier">reflex</span><span class="special">\</span><span class="identifier">w</span><span class="special">*\&gt;</span>
+</pre>
+<p>
+      will index occurances of "reflex", reflexing" and "reflexed"
+      all under the same entry <span class="emphasis"><em>reflex</em></span>.
     </p>
 <p>
       This inclusion rule can also restict the term to certain sections, and add
@@ -154,7 +167,7 @@
 <pre class="programlisting"><span class="special">!</span><span class="identifier">rewrite</span><span class="special">-</span><span class="identifier">name</span> <span class="string">"(?i)(?:A|The)\s+(.*)"</span> <span class="string">"\1"</span>
 </pre>
 <a name="autoindex.tut.step_5__iterate"></a><h5>
-<a name="id527366"></a>
+<a name="id527476"></a>
       <a class="link" href="tut.html#autoindex.tut.step_5__iterate">Step 5: Iterate</a>
     </h5>
 <p>

doc/html/index.html

@@ -28,7 +28,7 @@
 </h3></div></div></div>
 <div><p class="copyright">Copyright © 2008 John Maddock</p></div>
 <div><div class="legalnotice">
-<a name="id473180"></a><p>
+<a name="id473182"></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>
@@ -47,7 +47,7 @@
 </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: November 21, 2008 at 13:57:27 GMT</small></p></td>
+<td align="left"><p><small>Last revised: November 21, 2008 at 17:25:20 GMT</small></p></td>
 <td align="right"><div class="copyright-footer"></div></td>
 </tr></table>
 <hr>

project-root.jam

@@ -0,0 +1,47 @@
+#
+#   Copyright (c) 2006 João Abecasis
+#
+#   Distributed under the Boost Software License, Version 1.0. (See
+#   accompanying file LICENSE_1_0.txt or copy at
+#   http://www.boost.org/LICENSE_1_0.txt)
+#
+
+##
+##  IMPORTANT NOTE: This file MUST NOT be copied over a boost installation
+##
+
+path-constant top : . ;
+
+import modules ;
+import path ;
+
+local boost-root = [ modules.peek : BOOST_ROOT ] ;
+local math-header-include = $(top)/../.. ;
+
+if ! $(boost-root)
+{
+    local boost-search-dirs = [ modules.peek : BOOST_BUILD_PATH ] ;
+
+    for local dir in $(boost-search-dirs)
+    {
+        if [ path.glob $(dir)/../../../ : boost/version.hpp ]
+        {
+            boost-root += $(dir)/../../../ ;
+        }
+    }
+
+    if $(boost-root)
+    {
+        boost-root = [ path.make $(boost-root[1]) ] ;
+    }
+    else
+    {
+        ECHO "Warning: couldn't find BOOST_ROOT in" $(boost-root) ;
+    }
+}
+
+use-project /boost/regex : $(boost-root)/libs/regex/build ;
+use-project /boost/unit_test : $(boost-root)/libs/test/build ;
+use-project /boost/filesystem : $(boost-root)/libs/filesystem/build ;
+
+