Added a debug option.

[SVN r67358]

doc/auto_index.qbk

@@ -370,6 +370,9 @@ the documentation and see:
 Further rules can then be added to the script to handle these cases
 and the next iteration examined, and so on.
 
+[tip If you don't understand why a particular term is present in the index, try adding a ['!debug regular-expression] 
+directive to the [link autoindex.script_ref script file].]
+
 [endsect]
 
 [section:script_ref Script File Reference]
@@ -525,6 +528,27 @@ The arguments to the set-regex rule as follows:
 [[suffix][The suffix regular expression, or "" to reset to the default.]]
 ]
 
+[h4 Debugging]
+
+If you see a term in the index, and you don't understand why it's there, add a ['debug] directive:
+
+[pre
+!debug regular-expression
+]
+
+Now, whenever ['regular-expression] matches either the found index term, or the section title it appears in, then
+some diagnostic information will be printed that will look something like:
+
+[pre
+Debug term found, in block with ID: spirit.qi.reference.parser_concepts.parser
+Current section title is: Notation
+The main index entry will be : Notation
+The indexed term is: parser
+The search regex is: \[P\|p\]arser
+The section constraint is: .*qi.reference.parser_concepts.*
+The index type for this entry is: qi_index
+]
+
 [endsect]
 
 [section:comm_ref Command Line Reference]

doc/html/autoindex/comm_ref.html

@@ -16,7 +16,7 @@
 </div>
 <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>
+<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>
 <p>
       The following command line options are supported by auto_index:

doc/html/autoindex/overview.html

@@ -17,7 +17,7 @@
 </div>
 <div class="section" lang="en">
 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="autoindex.overview"></a><a class="link" href="overview.html" title="Overview"> Overview</a>
+<a name="autoindex.overview"></a><a class="link" href="overview.html" title="Overview">Overview</a>
 </h2></div></div></div>
 <p>
       AutoIndex is a tool for taking the grunt work out of indexing a Quickbook/Boostbook/Docbook

doc/html/autoindex/script_ref.html

@@ -17,13 +17,13 @@
 </div>
 <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>
+<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>
 <p>
       The following elements can occur in a script:
     </p>
 <a name="autoindex.script_ref.comments_and_blank_lines"></a><h5>
-<a name="id911500"></a>
+<a name="id1003329"></a>
       <a class="link" href="script_ref.html#autoindex.script_ref.comments_and_blank_lines">Comments and
       blank lines</a>
     </h5>
@@ -32,7 +32,7 @@
       with a '#'.
     </p>
 <a name="autoindex.script_ref.simple_inclusions"></a><h5>
-<a name="id911517"></a>
+<a name="id1003346"></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>
@@ -99,7 +99,7 @@
 </dl>
 </div>
 <a name="autoindex.script_ref.source_file_scanning"></a><h5>
-<a name="id911726"></a>
+<a name="id1003555"></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>
@@ -128,7 +128,7 @@
       </p></td></tr>
 </table></div>
 <a name="autoindex.script_ref.directory_and_source_file_scanning"></a><h5>
-<a name="id911804"></a>
+<a name="id1003633"></a>
       <a class="link" href="script_ref.html#autoindex.script_ref.directory_and_source_file_scanning">Directory
       and Source File Scanning</a>
     </h5>
@@ -157,7 +157,7 @@
 </dl>
 </div>
 <a name="autoindex.script_ref.excluding_terms"></a><h5>
-<a name="id911929"></a>
+<a name="id1003758"></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>
@@ -170,7 +170,7 @@
       of things to index.
     </p>
 <a name="autoindex.script_ref.rewriting_section_names"></a><h5>
-<a name="id911984"></a>
+<a name="id1003813"></a>
       <a class="link" href="script_ref.html#autoindex.script_ref.rewriting_section_names">Rewriting Section
       Names</a>
     </h5>
@@ -208,7 +208,7 @@
 </dl>
 </div>
 <a name="autoindex.script_ref.changing_the_regular_expressions_used_when_scanning"></a><h5>
-<a name="id912122"></a>
+<a name="id1003951"></a>
       <a class="link" href="script_ref.html#autoindex.script_ref.changing_the_regular_expressions_used_when_scanning">Changing
       the regular expressions used when scanning</a>
     </h5>
@@ -348,6 +348,29 @@
           </p></dd>
 </dl>
 </div>
+<a name="autoindex.script_ref.debugging"></a><h5>
+<a name="id1004239"></a>
+      <a class="link" href="script_ref.html#autoindex.script_ref.debugging">Debugging</a>
+    </h5>
+<p>
+      If you see a term in the index, and you don't understand why it's there, add
+      a <span class="emphasis"><em>debug</em></span> directive:
+    </p>
+<pre class="programlisting">!debug regular-expression
+</pre>
+<p>
+      Now, whenever <span class="emphasis"><em>regular-expression</em></span> matches either the found
+      index term, or the section title it appears in, then some diagnostic information
+      will be printed that will look something like:
+    </p>
+<pre class="programlisting">Debug term found, in block with ID: spirit.qi.reference.parser_concepts.parser
+Current section title is: Notation
+The main index entry will be : Notation
+The indexed term is: parser
+The search regex is: [P|p]arser
+The section constraint is: .<span class="bold"><strong>qi.reference.parser_concepts.</strong></span>
+The index type for this entry is: qi_index
+</pre>
 </div>
 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 <td align="left"></td>

doc/html/autoindex/tut.html

@@ -17,10 +17,10 @@
 </div>
 <div class="section" lang="en">
 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="autoindex.tut"></a><a class="link" href="tut.html" title="Getting Started and Tutorial"> Getting Started and Tutorial</a>
+<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="id902662"></a>
+<a name="id994380"></a>
       <a class="link" href="tut.html#autoindex.tut.step_1__build_the_tool">Step 1: Build the tool</a>
     </h5>
 <p>
@@ -62,7 +62,7 @@
       is accepted into Boost.
     </p>
 <a name="autoindex.tut.step_2__configure_boost_build"></a><h5>
-<a name="id902826"></a>
+<a name="id994545"></a>
       <a class="link" href="tut.html#autoindex.tut.step_2__configure_boost_build">Step 2: Configure
       Boost.Build</a>
     </h5>
@@ -155,7 +155,7 @@
 </dl>
 </div>
 <a name="autoindex.tut.step_3__add_indexes_to_your_documentation"></a><h5>
-<a name="id902989"></a>
+<a name="id994708"></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>
@@ -249,7 +249,7 @@ boostbook standalone
         &lt;xsl:param&gt;index.on.type=1
 </pre>
 <a name="autoindex.tut.step_4__create_the_script_file"></a><h5>
-<a name="id910948"></a>
+<a name="id1002762"></a>
       <a class="link" href="tut.html#autoindex.tut.step_4__create_the_script_file">Step 4: Create
       the script file</a>
     </h5>
@@ -322,7 +322,7 @@ boostbook standalone
 <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__add_manual_index_entries___optional"></a><h5>
-<a name="id911206"></a>
+<a name="id1003020"></a>
       <a class="link" href="tut.html#autoindex.tut.step_5__add_manual_index_entries___optional">Step
       5: Add Manual Index Entries - Optional</a>
     </h5>
@@ -338,7 +338,7 @@ boostbook standalone
       index itself, with the exception of the "type" attribute.
     </p>
 <a name="autoindex.tut.step_6__build_the_your_docs"></a><h5>
-<a name="id911326"></a>
+<a name="id1003140"></a>
       <a class="link" href="tut.html#autoindex.tut.step_6__build_the_your_docs">Step 6: Build the
       Your Docs</a>
     </h5>
@@ -365,7 +365,7 @@ boostbook standalone
       If you don't see that, or if it's indexing 0 terms then something is wrong!
     </p>
 <a name="autoindex.tut.step_7__iterate"></a><h5>
-<a name="id911437"></a>
+<a name="id1003250"></a>
       <a class="link" href="tut.html#autoindex.tut.step_7__iterate">Step 7: Iterate</a>
     </h5>
 <p>
@@ -388,6 +388,17 @@ boostbook standalone
       Further rules can then be added to the script to handle these cases and the
       next iteration examined, and so on.
     </p>
+<div class="tip"><table border="0" summary="Tip">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../images/tip.png"></td>
+<th align="left">Tip</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+        If you don't understand why a particular term is present in the index, try
+        adding a <span class="emphasis"><em>!debug regular-expression</em></span> directive to the
+        <a class="link" href="script_ref.html" title="Script File Reference">script file</a>.
+      </p></td></tr>
+</table></div>
 </div>
 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 <td align="left"></td>

doc/html/index.html

@@ -21,7 +21,7 @@
 </h3></div></div></div>
 <div><p class="copyright">Copyright &#169; 2008 John Maddock</p></div>
 <div><div class="legalnotice">
-<a name="id902374"></a><p>
+<a name="id994092"></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>
@@ -32,15 +32,15 @@
 <div class="toc">
 <p><b>Table of Contents</b></p>
 <dl>
-<dt><span class="section"><a href="autoindex/overview.html"> Overview</a></span></dt>
+<dt><span class="section"><a href="autoindex/overview.html">Overview</a></span></dt>
-<dt><span class="section"><a href="autoindex/tut.html"> Getting Started and Tutorial</a></span></dt>
+<dt><span class="section"><a href="autoindex/tut.html">Getting Started and Tutorial</a></span></dt>
-<dt><span class="section"><a href="autoindex/script_ref.html"> Script File Reference</a></span></dt>
+<dt><span class="section"><a href="autoindex/script_ref.html">Script File Reference</a></span></dt>
-<dt><span class="section"><a href="autoindex/comm_ref.html"> Command Line Reference</a></span></dt>
+<dt><span class="section"><a href="autoindex/comm_ref.html">Command Line Reference</a></span></dt>
 </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: June 28, 2010 at 17:45:04 GMT</small></p></td>
+<td align="left"><p><small>Last revised: December 20, 2010 at 13:16:00 GMT</small></p></td>
 <td align="right"><div class="copyright-footer"></div></td>
 </tr></table>
 <hr>

src/auto_index.cpp

@@ -22,6 +22,7 @@ boost::tiny_xml::element_list indexes;
 std::list<id_rewrite_rule> id_rewrite_list;
 bool internal_indexes = false;
 std::string internal_index_type = "section";
+boost::regex debug;
 
 int help()
 {
@@ -319,6 +320,17 @@ void process_node(boost::tiny_xml::element_ptr node, node_id* prev, title_info*
                // We have something to index!
                found_terms.insert(item_index);
 
+               if(!debug.empty() && (regex_match(i->term, debug) || regex_match(rtitle, debug) || regex_match(simple_title, debug)))
+               {
+                  std::cout << "Debug term found, in block with ID: " << *pid << std::endl;
+                  std::cout << "Current section title is: " << rtitle << std::endl;
+                  std::cout << "The main index entry will be : " << simple_title << std::endl;
+                  std::cout << "The indexed term is: " << i->term << std::endl;
+                  std::cout << "The search regex is: " << i->search_text << std::endl;
+                  std::cout << "The section constraint is: " << i->search_id << std::endl;
+                  std::cout << "The index type for this entry is: " << i->category << std::endl;
+               }
+
                if(use_section_names && (simple_title != i->term))
                {
                   //

src/auto_index.hpp

@@ -110,5 +110,6 @@ extern std::list<id_rewrite_rule> id_rewrite_list;
 extern bool internal_indexes;
 extern std::string prefix;
 extern std::string internal_index_type;
+extern boost::regex debug;
 
 #endif

src/file_scanning.cpp

@@ -310,6 +310,10 @@ void process_script(const char* script)
       "(?<prefix>[^\"[:space:]]+|\"(?:[^\"\\\\]|\\\\.)+\")\\s+"
       "(?<suffix>[^\"[:space:]]+|\"(?:[^\"\\\\]|\\\\.)+\")\\s*"
       );
+   static const boost::regex debug_parser(
+      "!debug\\s+"
+      "([^\"[:space:]]+|\"(?:[^\"\\\\]|\\\\.)+\")\\s*"
+      );
 
    if(verbose)
       std::cout << "Processing script " << script << std::endl;
@@ -347,6 +351,10 @@ void process_script(const char* script)
          }
          scan_file(f.c_str());
       }
+      else if(regex_match(line, what, debug_parser))
+      {
+         debug = unquote(what[1].str());
+      }
       else if(regex_match(line, what, scan_dir_parser))
       {
          std::string d = unquote(what[1].str());