]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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">\<\</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">*\></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">\<</span><span class="identifier">reflex</span><span class="special">\</span><span class="identifier">w</span><span class="special">*\></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">"\<myclass\w*\>"</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:]]*<[^;:{]+>[[:space:]]*)?(class|struct)[[:space:]]*(\<\w+\>([[:blank:]]*\([^)]*\))?[[:space:]]*)*(\<\w*\>)[[:space:]]*(<[^;:{]+>)?[[:space:]]*(\{|:[^;\{()]*\{)"</span> <span class="string">"(?:class|struct)[^;{]+\<\5\>[^;{]+\{"</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[^;]+\<\1\>\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">"\<\1\>"</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*+<[^>]++>)?[\s&*]+?(\w+)\s*(?:BOOST_[[:upper:]_]+\s*)?\([^;{}]*\)\s*[;{]"</span> <span class="string">"\\<\\w+\\>(?:\\s+<[^>]*>)*[\\s&*]+\\<\1\\>\\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:]]*<[^;:{]+>[[:space:]]*)?(class|struct)[[:space:]]*(\<\w+\>([[:blank:]]*\([^)]*\))?[[:space:]]*)*(\<\w*\>)[[:space:]]*(<[^;:{]+>)?[[:space:]]*(\{|:[^;\{()]*\{)"</span> <span class="string">"\<\5\>"</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 © 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> |