ceph/src/boost/tools/auto_index/doc/html/boost_autoindex/script_ref.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Script File (.idx) Reference</title>
   5 <link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
   7 <link rel="home" href="../index.html" title="Boost.AutoIndex">
   8 <link rel="up" href="../index.html" title="Boost.AutoIndex">
   9 <link rel="prev" href="tut/refine.html" title="Step 8: Iterate - to refine your index">
  10 <link rel="next" href="workflow.html" title="Understanding The AutoIndex Workflow">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="tut/refine.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="workflow.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="boost_autoindex.script_ref"></a><a class="link" href="script_ref.html" title="Script File (.idx) Reference">Script File (.idx) Reference</a>
  28 </h2></div></div></div>
  29 <p>
  30       The following elements can occur in a script:
  31     </p>
  32 <h5>
  33 <a name="boost_autoindex.script_ref.h0"></a>
  34       <span class="phrase"><a name="boost_autoindex.script_ref.comments_and_blank_lines"></a></span><a class="link" href="script_ref.html#boost_autoindex.script_ref.comments_and_blank_lines">Comments
  35       and blank lines</a>
  36     </h5>
  37 <p>
  38       Blank lines consisting of only whitespace are ignored, so are lines that <span class="bold"><strong>start with a #</strong></span>.
  39     </p>
  40 <div class="note"><table border="0" summary="Note">
  41 <tr>
  42 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
  43 <th align="left">Note</th>
  44 </tr>
  45 <tr><td align="left" valign="top"><p>
  46         You can't append # comments onto the end of a line!
  47       </p></td></tr>
  48 </table></div>
  49 <h5>
  50 <a name="boost_autoindex.script_ref.h1"></a>
  51       <span class="phrase"><a name="boost_autoindex.script_ref.inclusion_of_index_terms"></a></span><a class="link" href="script_ref.html#boost_autoindex.script_ref.inclusion_of_index_terms">Inclusion
  52       of Index terms</a>
  53     </h5>
  54 <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>
  55 </pre>
  56 <div class="variablelist">
  57 <p class="title"><b></b></p>
  58 <dl class="variablelist">
  59 <dt><span class="term">term</span></dt>
  60 <dd>
  61 <p>
  62             <span class="emphasis"><em>Term to index.</em></span>
  63           </p>
  64 <p>
  65             The index term will form a primary entry in the Index with the section
  66             title(s) containing the term as secondary entries, and also will be used
  67             as a secondary entry beneath each of the section titles that the index
  68             term occurs in.
  69           </p>
  70 </dd>
  71 <dt><span class="term">regular-expression1</span></dt>
  72 <dd>
  73 <p>
  74             <span class="emphasis"><em>Index term Searcher.</em></span>
  75           </p>
  76 <p>
  77             An optional regular expression: each occurrence of the regular expression
  78             in the text of the document will result in one index term being emitted.
  79           </p>
  80 <p>
  81             If the regular expression is omitted (default) or is "", then
  82             the <span class="emphasis"><em>index term</em></span> itself will be used as the search
  83             text - and only occurrence of whole words matching <span class="emphasis"><em>index term</em></span>
  84             will be indexed.
  85           </p>
  86 <p>
  87             For example:
  88           </p>
  89 <p>
  90 </p>
  91 <pre class="programlisting"><span class="identifier">foobar</span></pre>
  92 <p>
  93           </p>
  94 <p>
  95             will index occurrences of "foobar" in any section, but
  96           </p>
  97 <p>
  98 </p>
  99 <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>
 100 <p>
 101           </p>
 102 <p>
 103             will index any whole word containing either "foo" or "bar"
 104             within it. This is useful when you want to index a lot of similar or
 105             related words under one entry.
 106           </p>
 107 <p>
 108 </p>
 109 <pre class="programlisting"><span class="identifier">reflex</span></pre>
 110 <p>
 111           </p>
 112 <p>
 113             will only index occurrences of "reflex" as a whole word, but:
 114           </p>
 115 <p>
 116 </p>
 117 <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>
 118 <p>
 119           </p>
 120 <p>
 121             will index occurrences of "reflex", "reflexes", "reflexing"
 122             and "reflexed" ... all under the same entry reflex.
 123           </p>
 124 <p>
 125             You will very often need to use this to deal with plurals and other variants.
 126           </p>
 127 </dd>
 128 <dt><span class="term">regular-expression2</span></dt>
 129 <dd>
 130 <p>
 131             <span class="emphasis"><em>Section(s) Selector.</em></span>
 132           </p>
 133 <p>
 134             A constraint that specifies which sections are indexed for <span class="emphasis"><em>term</em></span>:
 135             only if the ID of the section matches <span class="emphasis"><em>regular-expression2</em></span>
 136             exactly will that section be indexed for occurrences of <span class="emphasis"><em>term</em></span>.
 137           </p>
 138 <p>
 139             For example, to limit indexing to just <span class="bold"><strong>one specific
 140             section</strong></span> (but not sub-sections below):
 141           </p>
 142 <p>
 143 </p>
 144 <pre class="programlisting"><span class="identifier">myclass</span> <span class="string">""</span> <span class="string">"mylib\.examples"</span></pre>
 145 <p>
 146           </p>
 147 <p>
 148             For example, to limit indexing to specific sections, <span class="bold"><strong>and
 149             sub-sections below</strong></span>:
 150           </p>
 151 <p>
 152 </p>
 153 <pre class="programlisting"><span class="identifier">myclass</span> <span class="string">""</span> <span class="string">"mylib\.examples.*"</span></pre>
 154 <p>
 155           </p>
 156 <p>
 157             will index occurrences of "myclass" as a whole word, but only
 158             in sections whose section ID <span class="bold"><strong>begins</strong></span>
 159             "mylib.examples", while
 160           </p>
 161 <p>
 162 </p>
 163 <pre class="programlisting"><span class="identifier">myclass</span> <span class="string">"\&lt;myclass\w*\&gt;"</span> <span class="string">"mylib\.examples.*"</span></pre>
 164 <p>
 165           </p>
 166 <p>
 167             will also index plurals myclass, myclasses, myclasss ...
 168           </p>
 169 <p>
 170             and:
 171           </p>
 172 <p>
 173 </p>
 174 <pre class="programlisting"><span class="identifier">myclass</span> <span class="string">""</span> <span class="string">"(?!mylib\.introduction).*"</span></pre>
 175 <p>
 176           </p>
 177 <p>
 178             will index occurrences of "myclass" in any section, except
 179             those whose section IDs begin "mylib.introduction".
 180           </p>
 181 <p>
 182             Finally, two (or more) sections can be excluded by OR'ing them together:
 183           </p>
 184 <p>
 185 </p>
 186 <pre class="programlisting"><span class="identifier">myclass</span> <span class="string">""</span> <span class="string">"(?!mylib\.introduction|mylib\.reference).*"</span></pre>
 187 <p>
 188           </p>
 189 <p>
 190             which excludes searching for this term in sections whose ID's start with
 191             either "mylib.introduction" or "mylib.reference".
 192           </p>
 193 <p>
 194             If this third section selection field is omitted (the default) or is
 195             "", then <span class="bold"><strong>all sections</strong></span> are
 196             indexed for this term.
 197           </p>
 198 </dd>
 199 <dt><span class="term">category</span></dt>
 200 <dd>
 201 <p>
 202             <span class="emphasis"><em>Index Category Constraint.</em></span>
 203           </p>
 204 <p>
 205             Optionally a category to place occurrences of <span class="emphasis"><em>index term</em></span>
 206             in. If you have multiple indexes then this is the name assigned to the
 207             indexes "type" attribute.
 208           </p>
 209 <p>
 210             For example:
 211           </p>
 212 <p>
 213             myclass "" "" class_name
 214           </p>
 215 <p>
 216             Will index occurances of <span class="emphasis"><em>myclass</em></span> and place them
 217             in the class-index if there is one.
 218           </p>
 219 </dd>
 220 </dl>
 221 </div>
 222 <p>
 223       You can have an index term appear more than once in the script file:
 224     </p>
 225 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 226 <li class="listitem">
 227           If they have different <span class="emphasis"><em>category</em></span> names then they are
 228           treated quite separately.
 229         </li>
 230 <li class="listitem">
 231           Otherwise they are combined, so that the logical or of the regular expressions
 232           provided are taken.
 233         </li>
 234 </ul></div>
 235 <p>
 236       Thus:
 237     </p>
 238 <pre class="programlisting"><span class="identifier">myterm</span> <span class="identifier">search_expression1</span> <span class="identifier">constrait_expression2</span> <span class="identifier">foo</span>
 239 <span class="identifier">myterm</span> <span class="identifier">search_expression1</span> <span class="identifier">constrait_expression2</span> <span class="identifier">bar</span>
 240 </pre>
 241 <p>
 242       Will be treated as different terms each with their own entries, while:
 243     </p>
 244 <pre class="programlisting"><span class="identifier">myterm</span> <span class="identifier">search_expression1</span> <span class="identifier">constrait_expression2</span> <span class="identifier">mycategory</span>
 245 <span class="identifier">myterm</span> <span class="identifier">search_expression1</span> <span class="identifier">constrait_expression2</span> <span class="identifier">mycategory</span>
 246 </pre>
 247 <p>
 248       Will be combined into a single term equivalent to:
 249     </p>
 250 <pre class="programlisting"><span class="identifier">myterm</span> <span class="special">(?:</span><span class="identifier">search_expression1</span><span class="special">|</span><span class="identifier">search_expression1</span><span class="special">)</span> <span class="special">(?:</span><span class="identifier">constrait_expression2</span><span class="special">|</span><span class="identifier">constrait_expression2</span><span class="special">)</span> <span class="identifier">mycategory</span>
 251 </pre>
 252 <h5>
 253 <a name="boost_autoindex.script_ref.h2"></a>
 254       <span class="phrase"><a name="boost_autoindex.script_ref.source_file_scanning"></a></span><a class="link" href="script_ref.html#boost_autoindex.script_ref.source_file_scanning">Source
 255       File Scanning</a>
 256     </h5>
 257 <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>
 258 </pre>
 259 <p>
 260       Scans the C/C++ source file <span class="emphasis"><em>source-file-name</em></span> for definitions
 261       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
 262       or <span class="emphasis"><em>typedef</em></span>s and makes each of these a term to be indexed.
 263       Terms found are assigned to the index category "function_name", "class_name",
 264       "macro_name" or "typedef_name" depending on how they were
 265       seen in the source file. These may then be included in a specialised index
 266       whose "type" attribute has the same category name.
 267     </p>
 268 <div class="important"><table border="0" summary="Important">
 269 <tr>
 270 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
 271 <th align="left">Important</th>
 272 </tr>
 273 <tr><td align="left" valign="top"><p>
 274         When actually indexing a document, the scanner will not index just any old
 275         occurrence of the terms found in the source files. Instead it searches for
 276         class definitions or function or typedef declarations. This reduces the number
 277         of spurious matches placed in the index, but may also miss some legitimate
 278         terms: refer to the <span class="emphasis"><em>define-scanner</em></span> command for information
 279         on how to change this.
 280       </p></td></tr>
 281 </table></div>
 282 <h5>
 283 <a name="boost_autoindex.script_ref.h3"></a>
 284       <span class="phrase"><a name="boost_autoindex.script_ref.directory_and_source_file_scanning"></a></span><a class="link" href="script_ref.html#boost_autoindex.script_ref.directory_and_source_file_scanning">Directory
 285       and Source File Scanning</a>
 286     </h5>
 287 <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>
 288 </pre>
 289 <div class="variablelist">
 290 <p class="title"><b></b></p>
 291 <dl class="variablelist">
 292 <dt><span class="term">directory-name</span></dt>
 293 <dd><p>
 294             The directory to scan: this should be a path relative to the script file
 295             (or to the path specified with the prefix=path option on the command
 296             line) and should use all forward slashes in its file name.
 297           </p></dd>
 298 <dt><span class="term">file-name-regex</span></dt>
 299 <dd><p>
 300             A regular expression: any file in the directory whose name matches the
 301             regular expression will be scanned for terms to index.
 302           </p></dd>
 303 <dt><span class="term">recurse</span></dt>
 304 <dd><p>
 305             An optional boolean value - either "true" or "false"
 306             - that indicates whether to recurse into subdirectories. This defaults
 307             to "false".
 308           </p></dd>
 309 </dl>
 310 </div>
 311 <h5>
 312 <a name="boost_autoindex.script_ref.h4"></a>
 313       <span class="phrase"><a name="boost_autoindex.script_ref.excluding_terms"></a></span><a class="link" href="script_ref.html#boost_autoindex.script_ref.excluding_terms">Excluding
 314       Terms</a>
 315     </h5>
 316 <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>
 317 </pre>
 318 <p>
 319       Excludes all the terms in whitespace separated <span class="emphasis"><em>term-list</em></span>
 320       from being indexed. This should be placed <span class="emphasis"><em>after</em></span> any <span class="emphasis"><em>!scan</em></span>
 321       or <span class="emphasis"><em>!scan-path</em></span> rules which may result in the terms becoming
 322       included. In other words this removes terms from the scanners internal list
 323       of things to index.
 324     </p>
 325 <h5>
 326 <a name="boost_autoindex.script_ref.h5"></a>
 327       <span class="phrase"><a name="boost_autoindex.script_ref.rewriting_section_names"></a></span><a class="link" href="script_ref.html#boost_autoindex.script_ref.rewriting_section_names">Rewriting
 328       Section Names</a>
 329     </h5>
 330 <pre class="programlisting">!rewrite-id regular-expression new-name</pre>
 331 <div class="variablelist">
 332 <p class="title"><b></b></p>
 333 <dl class="variablelist">
 334 <dt><span class="term">regular-expression</span></dt>
 335 <dd><p>
 336             A regular expression: all section ID's that match the expression exactly
 337             will have index entries <span class="emphasis"><em>new-name</em></span> instead of their
 338             title(s).
 339           </p></dd>
 340 <dt><span class="term">new-name</span></dt>
 341 <dd><p>
 342             The name that the section will appear under in the index.
 343           </p></dd>
 344 </dl>
 345 </div>
 346 <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>
 347 </pre>
 348 <div class="variablelist">
 349 <p class="title"><b></b></p>
 350 <dl class="variablelist">
 351 <dt><span class="term">regular-expression</span></dt>
 352 <dd><p>
 353             A regular expression: all sections whose titles match the regular expression
 354             exactly, will have index entries composed of the regular expression match
 355             combined with the regex format string <span class="emphasis"><em>format-text</em></span>.
 356           </p></dd>
 357 <dt><span class="term">format-text</span></dt>
 358 <dd><p>
 359             The Perl-style format string used to reformat the title.
 360           </p></dd>
 361 </dl>
 362 </div>
 363 <p>
 364       For example:
 365     </p>
 366 <pre class="programlisting">!rewrite-name "(?:A|An|The)\s+(.*)" "\1"
 367 </pre>
 368 <p>
 369       Will remove any leading "A", "An" or "The" from
 370       all index entries - thus preventing lots of entries under "The" etc!
 371     </p>
 372 <h5>
 373 <a name="boost_autoindex.script_ref.h6"></a>
 374       <span class="phrase"><a name="boost_autoindex.script_ref.defining_or_changing_the_file_scanners"></a></span><a class="link" href="script_ref.html#boost_autoindex.script_ref.defining_or_changing_the_file_scanners">Defining
 375       or Changing the File Scanners</a>
 376     </h5>
 377 <pre class="programlisting"><span class="special">!</span><span class="identifier">define</span><span class="special">-</span><span class="identifier">scanner</span> <span class="identifier">type</span> <span class="identifier">file</span><span class="special">-</span><span class="identifier">search</span><span class="special">-</span><span class="identifier">expression</span> <span class="identifier">xml</span><span class="special">-</span><span class="identifier">regex</span><span class="special">-</span><span class="identifier">formatter</span> <span class="identifier">term</span><span class="special">-</span><span class="identifier">formatter</span> <span class="identifier">id</span><span class="special">-</span><span class="identifier">filter</span> <span class="identifier">filename</span><span class="special">-</span><span class="identifier">filter</span>
 378 </pre>
 379 <p>
 380       When a source file is scanned using the <code class="literal">!scan</code> or <code class="literal">!scan-path</code>
 381       rules, then the file is searched using a series of regular expressions to look
 382       for classes, functions, macros or typedefs that should be indexed. A set of
 383       default regular expressions are provided for this (see below), but sometimes
 384       you may want to replace the defaults, or add new scanners. The arguments to
 385       this rule are:
 386     </p>
 387 <div class="variablelist">
 388 <p class="title"><b></b></p>
 389 <dl class="variablelist">
 390 <dt><span class="term">type</span></dt>
 391 <dd><p>
 392             The <span class="emphasis"><em>type</em></span> to which items found using this rule will
 393             assigned, index terms created from the source file and then found in
 394             the XML, will have the type attribute set to this value, and may then
 395             appear in a specialized index with the same type attribute
 396           </p></dd>
 397 <dt><span class="term">file-search-expression</span></dt>
 398 <dd><p>
 399             A regular expression that is used to scan the source file for index terms,
 400             the result of a match against this expression will be transformed by
 401             the next two arguments.
 402           </p></dd>
 403 <dt><span class="term">xml-regex-formatter</span></dt>
 404 <dd><p>
 405             A regular expression format string that extracts the salient information
 406             from whatever matched the <span class="emphasis"><em>file-search-expression</em></span>
 407             in the source file, and creates <span class="emphasis"><em>a new regular expression</em></span>
 408             that will be used to search the document being indexed for occurrences
 409             of this index term.
 410           </p></dd>
 411 <dt><span class="term">term-formatter</span></dt>
 412 <dd><p>
 413             A regular expression format string that extracts the salient information
 414             from whatever matched the <span class="emphasis"><em>file-search-expression</em></span>
 415             in the source file, and creates the index term that will appear in the
 416             index.
 417           </p></dd>
 418 <dt><span class="term">id-filter</span></dt>
 419 <dd><p>
 420             Optional. A regular expression that restricts the section-id's that are
 421             searched in the document being indexed: only sections whose ID attribute
 422             matches this expression exactly will be considered for indexing terms
 423             found by this scanner.
 424           </p></dd>
 425 <dt><span class="term">filename-filter</span></dt>
 426 <dd><p>
 427             Optional. A regular expression that restricts which files are scanned
 428             by this scanner: only files whose file name matches this expression exactly
 429             will be scanned for index terms to use. Note that the filename matched
 430             against this may well be an absolute path, and contain either forward
 431             or backward slash path separators.
 432           </p></dd>
 433 </dl>
 434 </div>
 435 <p>
 436       If, when the first file is scanned, there are no scanners whose <span class="emphasis"><em>type</em></span>
 437       is "class_name", "typedef_name", "macro_name"
 438       or "function_name", then the defaults are installed. These are equivalent
 439       to:
 440     </p>
 441 <pre class="programlisting"><span class="special">!</span><span class="identifier">define</span><span class="special">-</span><span class="identifier">scanner</span> <span class="identifier">class_name</span> <span class="string">"^[[:space:]]*(template[[:space:]]*&lt;[^;:{]+&gt;[[:space:]]*)?(class|struct)[[:space:]]*(\&lt;\w+\&gt;([[:blank:]]*\([^)]*\))?[[:space:]]*)*(\&lt;\w*\&gt;)[[:space:]]*(&lt;[^;:{]+&gt;)?[[:space:]]*(\{|:[^;\{()]*\{)"</span> <span class="string">"(?:class|struct)[^;{]+\&lt;\5\&gt;[^;{]+\{"</span> <span class="special">\</span><span class="number">5</span>
 442 <span class="special">!</span><span class="identifier">define</span><span class="special">-</span><span class="identifier">scanner</span> <span class="identifier">typedef_name</span> <span class="string">"typedef[^;{}#]+?(\w+)\s*;"</span>  <span class="string">"typedef[^;]+\&lt;\1\&gt;\s*;"</span> <span class="string">"\1"</span>
 443 <span class="special">!</span><span class="identifier">define</span><span class="special">-</span><span class="identifier">scanner</span> <span class="string">"macro_name"</span> <span class="string">"^\s*#\s*define\s+(\w+)"</span> <span class="string">"\&lt;\1\&gt;"</span> <span class="string">"\1"</span>
 444 <span class="special">!</span><span class="identifier">define</span><span class="special">-</span><span class="identifier">scanner</span> <span class="string">"function_name"</span> <span class="string">"\w++(?:\s*+&lt;[^&gt;]++&gt;)?[\s&amp;*]+?(\w+)\s*(?:BOOST_[[:upper:]_]+\s*)?\([^;{}]*\)\s*[;{]"</span> <span class="string">"\\&lt;\\w+\\&gt;(?:\\s+&lt;[^&gt;]*&gt;)*[\\s&amp;*]+\\&lt;\1\\&gt;\\s*\\([^;{]*\\)"</span> <span class="string">"\1"</span>
 445 </pre>
 446 <p>
 447       Note that these defaults are not installed if you have provided your own versions
 448       with these <span class="emphasis"><em>type</em></span> names. In this case if you want the default
 449       scanners to be in effect as well as your own, you should include the above
 450       in your script file. It is also perfectly allowable to have multiple scanners
 451       with the same <span class="emphasis"><em>type</em></span>, but with the other fields differing.
 452     </p>
 453 <p>
 454       Finally you should note that the default scanners are quite strict in what
 455       they will find, for example the class scanner will only create index entries
 456       for classes that have class definitions of the form:
 457     </p>
 458 <pre class="programlisting"><span class="keyword">class</span> <span class="identifier">my_class</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">base_classes</span>
 459 <span class="special">{</span>
 460    <span class="comment">// etc</span>
 461 </pre>
 462 <p>
 463       In the documentation, so that simple mentions of the class name will <span class="emphasis"><em>not</em></span>
 464       get indexed, only the class synopsis if there is one. If this isn't how you
 465       want things, then include the <span class="emphasis"><em>class_name</em></span> scanner definition
 466       above in your script file, and change the <span class="emphasis"><em>xml-regex-formatter</em></span>
 467       field to something more permissive, for example:
 468     </p>
 469 <pre class="programlisting"><span class="special">!</span><span class="identifier">define</span><span class="special">-</span><span class="identifier">scanner</span> <span class="identifier">class_name</span> <span class="string">"^[[:space:]]*(template[[:space:]]*&lt;[^;:{]+&gt;[[:space:]]*)?(class|struct)[[:space:]]*(\&lt;\w+\&gt;([[:blank:]]*\([^)]*\))?[[:space:]]*)*(\&lt;\w*\&gt;)[[:space:]]*(&lt;[^;:{]+&gt;)?[[:space:]]*(\{|:[^;\{()]*\{)"</span> <span class="string">"\&lt;\5\&gt;"</span> <span class="special">\</span><span class="number">5</span>
 470 </pre>
 471 <p>
 472       Will look for <span class="emphasis"><em>any</em></span> occurrence of whatever class names the
 473       scanner may find in the documentation.
 474     </p>
 475 <h5>
 476 <a name="boost_autoindex.script_ref.h7"></a>
 477       <span class="phrase"><a name="boost_autoindex.script_ref.debugging_scanning"></a></span><a class="link" href="script_ref.html#boost_autoindex.script_ref.debugging_scanning">Debugging
 478       scanning</a>
 479     </h5>
 480 <p>
 481       If you see a term in the index, and you don't understand why it's there, add
 482       a <span class="emphasis"><em>debug</em></span> directive:
 483     </p>
 484 <pre class="programlisting">!debug regular-expression
 485 </pre>
 486 <p>
 487       Now, whenever <span class="emphasis"><em>regular-expression</em></span> matches either the found
 488       index term, or the section title it appears in, or the <span class="emphasis"><em>type</em></span>
 489       field of a scanner, then some diagnostic information will be printed that will
 490       look something like:
 491     </p>
 492 <pre class="programlisting">Debug term found, in block with ID: spirit.qi.reference.parser_concepts.parser
 493 Current section title is: Notation
 494 The main index entry will be : Notation
 495 The indexed term is: parser
 496 The search regex is: [P|p]arser
 497 The section constraint is: .<span class="bold"><strong>qi.reference.parser_concepts.</strong></span>
 498 The index type for this entry is: qi_index
 499 </pre>
 500 <p>
 501       This can produce a lot of output in your log file, but until you are satisfied
 502       with your file selection and scanning process, it is worth switching it on.
 503     </p>
 504 </div>
 505 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 506 <td align="left"></td>
 507 <td align="right"><div class="copyright-footer">Copyright &#169; 2008, 2011 John Maddock<p>
 508         Distributed under the Boost Software License, Version 1.0. (See accompanying
 509         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>)
 510       </p>
 511 </div></td>
 512 </tr></table>
 513 <hr>
 514 <div class="spirit-nav">
 515 <a accesskey="p" href="tut/refine.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="workflow.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 516 </div>
 517 </body>
 518 </html>