diff --git a/doc/auto_index.qbk b/doc/auto_index.qbk index 4b98308..e91d54a 100644 --- a/doc/auto_index.qbk +++ b/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] diff --git a/doc/html/autoindex/comm_ref.html b/doc/html/autoindex/comm_ref.html index 5fd65a2..7cffab5 100644 --- a/doc/html/autoindex/comm_ref.html +++ b/doc/html/autoindex/comm_ref.html @@ -16,7 +16,7 @@

- Command Line Reference +Command Line Reference

The following command line options are supported by auto_index: diff --git a/doc/html/autoindex/overview.html b/doc/html/autoindex/overview.html index e3c69ad..1eb12d0 100644 --- a/doc/html/autoindex/overview.html +++ b/doc/html/autoindex/overview.html @@ -17,7 +17,7 @@

- Overview +Overview

AutoIndex is a tool for taking the grunt work out of indexing a Quickbook/Boostbook/Docbook diff --git a/doc/html/autoindex/script_ref.html b/doc/html/autoindex/script_ref.html index ba1b659..47613d3 100644 --- a/doc/html/autoindex/script_ref.html +++ b/doc/html/autoindex/script_ref.html @@ -17,13 +17,13 @@

- Script File Reference +Script File Reference

The following elements can occur in a script:

- + Comments and blank lines
@@ -32,7 +32,7 @@ with a '#'.

- + Simple Inclusions 
term [regular-expression1 [regular-expression2 [category]]]
@@ -99,7 +99,7 @@
- + Source File Scanning 
!scan source-file-name
@@ -128,7 +128,7 @@
       

 
 

-
+
       Directory
       and Source File Scanning
     

@@ -157,7 +157,7 @@
 
 
 

-
+
       Excluding Terms
     

 
!exclude term-list
@@ -170,7 +170,7 @@
       of things to index.
     

 

-
+
       Rewriting Section
       Names
     

@@ -208,7 +208,7 @@
 
 
 

-
+
       Changing
       the regular expressions used when scanning
     

@@ -348,6 +348,29 @@
           

 
 
+

+
+      Debugging
+    

+

+      If you see a term in the index, and you don't understand why it's there, add
+      a debug directive:
+    

+
!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:
+    

+
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
+

 
 
diff --git a/doc/html/autoindex/tut.html b/doc/html/autoindex/tut.html
index 208fb76..7748248 100644
--- a/doc/html/autoindex/tut.html
+++ b/doc/html/autoindex/tut.html
@@ -17,10 +17,10 @@
 

 

 

-
+
       Step 1: Build the tool
     

 

@@ -62,7 +62,7 @@
       is accepted into Boost.
     

 

-
+
       Step 2: Configure
       Boost.Build
     

@@ -155,7 +155,7 @@
 
 

-
+
       Step
       3: Add indexes to your documentation
     

@@ -249,7 +249,7 @@ boostbook standalone
         <xsl:param>index.on.type=1
 

-
+
       Step 4: Create
       the script file
     

@@ -322,7 +322,7 @@ boostbook standalone
 
!rewrite-name "(?i)(?:A|The)\s+(.*)" "\1"
 

-
+
       Step
       5: Add Manual Index Entries - Optional
     

@@ -338,7 +338,7 @@ boostbook standalone
       index itself, with the exception of the "type" attribute.
     

-
+
       Step 6: Build the
       Your Docs
     

@@ -365,7 +365,7 @@ boostbook standalone
       If you don't see that, or if it's indexing 0 terms then something is wrong!
     

-
+
       Step 7: Iterate
     

@@ -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.
     

+

 
 
 
 
 
 
 
 

+
+
+
+
+
+
[Tip]Tip

+        If you don't understand why a particular term is present in the index, try
+        adding a !debug regular-expression directive to the
+        script file.
+      

 
 
diff --git a/doc/html/index.html b/doc/html/index.html
index 1df96a2..836bb5a 100644
--- a/doc/html/index.html
+++ b/doc/html/index.html
@@ -21,7 +21,7 @@
 
Copyright © 2008 John Maddock

-

+

         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)
       

@@ -32,15 +32,15 @@
 

 
Table of Contents

 

-
 Overview

-
 Getting Started and Tutorial

-
 Script File Reference

-
 Command Line Reference

+
Overview

+
Getting Started and Tutorial

+
Script File Reference

+
Command Line Reference

 

 

 

 

 
 
 

-
+
Last revised: June 28, 2010 at 17:45:04 GMT
Last revised: December 20, 2010 at 13:16:00 GMT

 

 

 

diff --git a/src/auto_index.cpp b/src/auto_index.cpp
index 608afdf..448229c 100644
--- a/src/auto_index.cpp
+++ b/src/auto_index.cpp
@@ -22,6 +22,7 @@ boost::tiny_xml::element_list indexes;
 std::list 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))
                {
                   //
diff --git a/src/auto_index.hpp b/src/auto_index.hpp
index 5b684b1..35b6bf9 100644
--- a/src/auto_index.hpp
+++ b/src/auto_index.hpp
@@ -110,5 +110,6 @@ extern std::list id_rewrite_list;
 extern bool internal_indexes;
 extern std::string prefix;
 extern std::string internal_index_type;
+extern boost::regex debug;
 
 #endif
diff --git a/src/file_scanning.cpp b/src/file_scanning.cpp
index 4dfcef3..980f82a 100644
--- a/src/file_scanning.cpp
+++ b/src/file_scanning.cpp
@@ -310,6 +310,10 @@ void process_script(const char* script)
       "(?[^\"[:space:]]+|\"(?:[^\"\\\\]|\\\\.)+\")\\s+"
       "(?[^\"[: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());