1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 4<title>Step 4: Create the .idx script file - to control what to terms to index</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="../tut.html" title="Getting Started and Tutorial"> 9<link rel="prev" href="add_indexes.html" title="Step 3: Add indexes to your documentation"> 10<link rel="next" href="entries.html" title="Step 5: Add Manual Index Entries to Docbook XML - Optional"> 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="add_indexes.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.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="entries.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h3 class="title"> 27<a name="boost_autoindex.tut.script"></a><a class="link" href="script.html" title="Step 4: Create the .idx script file - to control what to terms to index">Step 4: Create the .idx script 28 file - to control what to terms to index</a> 29</h3></div></div></div> 30<p> 31 AutoIndex works by reading a script file that tells it what terms to index. 32 </p> 33<p> 34 If your document contains largely text, and only a small amount of simple 35 C++, and/or if you are using Doxygen to provide a C++ Reference section (that 36 lists the C++ elements), and/or if you are relying on the indexing provided 37 from a Standalone Doxygen Index, you may decide that a index is not needed 38 and that you may only want the text part indexed. 39 </p> 40<p> 41 But if you want C++ classes functions, typedefs and/or macros AutoIndexed, 42 optionally, the script file also tells which other C++ files to scan. 43 </p> 44<p> 45 At its simplest, it will scan one or more headers for terms that should be 46 indexed in the documentation. So for example to scan "myheader.hpp" 47 the script file would just contain: 48 </p> 49<pre class="programlisting"><span class="special">!</span><span class="identifier">scan</span> <span class="identifier">myheader</span><span class="special">.</span><span class="identifier">hpp</span> 50<span class="special">!</span><span class="identifier">scan</span> <span class="identifier">mydetailsheader</span><span class="special">.</span><span class="identifier">hpp</span> 51</pre> 52<p> 53 Or, more likely in practice, so we can recursively scan through directories 54 looking for all the files to scan whose <span class="bold"><strong>name matches 55 a particular regular expression</strong></span>: 56 </p> 57<pre class="programlisting">!scan-path "boost/mylibrary" ".*.hpp" true </pre> 58<p> 59 Each argument is whitespace separated and can be optionally enclosed in "double 60 quotes" (recommended). 61 </p> 62<p> 63 The final <span class="emphasis"><em>true</em></span> argument indicates that subdirectories 64 in <code class="computeroutput"><span class="special">/</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">mylibrary</span></code> should be searched recursively 65 in addition to that directory. 66 </p> 67<div class="caution"><table border="0" summary="Caution"> 68<tr> 69<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../doc/src/images/caution.png"></td> 70<th align="left">Caution</th> 71</tr> 72<tr><td align="left" valign="top"><p> 73 The second <span class="emphasis"><em>file-name-regex</em></span> argument is a regular expression 74 and not a filename GLOB! 75 </p></td></tr> 76</table></div> 77<div class="caution"><table border="0" summary="Caution"> 78<tr> 79<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../doc/src/images/caution.png"></td> 80<th align="left">Caution</th> 81</tr> 82<tr><td align="left" valign="top"><p> 83 The scan-path is modified by any setting of <auto-index-prefix>. 84 The examples here assume that this is <code class="literal"><auto-index-prefix>../../..</code> 85 so that <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mylibrary</span></code> will be your header files, 86 <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">mylibrary</span><span class="special">/</span><span class="identifier">doc</span></code> will contain your documentation files 87 and <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">mylibrary</span><span class="special">/</span><span class="identifier">example</span></code> will contain your examples. 88 </p></td></tr> 89</table></div> 90<p> 91 You could also scan any examples (.cpp) files, typically in folder <code class="computeroutput"><span class="special">/</span><span class="identifier">mylibrary</span><span class="special">/</span><span class="identifier">lib</span><span class="special">/</span><span class="identifier">example</span></code>. 92 </p> 93<pre class="programlisting"># All example source files, assuming no sub-folders. 94!scan-path "libs/mylibrary/example" ".*.cpp" 95</pre> 96<p> 97 Often the <span class="emphasis"><em>scan</em></span> or <span class="emphasis"><em>scan-path</em></span> rules 98 will bring in too many terms to search for, so we need to be able to exclude 99 terms as well: 100 </p> 101<pre class="programlisting"><span class="special">!</span><span class="identifier">exclude</span> <span class="identifier">type</span> 102</pre> 103<p> 104 Which excludes the term "type" from being indexed. 105 </p> 106<p> 107 We can also add terms manually: 108 </p> 109<pre class="programlisting"><span class="identifier">foobar</span> 110</pre> 111<p> 112 will index occurrences of "foobar" and: 113 </p> 114<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> 115</pre> 116<p> 117 will index any whole word containing either "foo" or "bar" 118 within it, this is useful when you want to index a lot of similar or related 119 words under one entry, for example: 120 </p> 121<pre class="programlisting"><span class="identifier">reflex</span> 122</pre> 123<p> 124 Will only index occurrences of "reflex" as a whole word, but: 125 </p> 126<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> 127</pre> 128<p> 129 will index occurrences of "reflex", "reflexing" and "reflexed" 130 all under the same entry <span class="emphasis"><em>reflex</em></span>. You will very often 131 need to use this to deal with plurals and other variants. 132 </p> 133<p> 134 This inclusion rule can also restrict the term to certain sections, and add 135 an index category that the term should belong to (so it only appears in certain 136 indexes). 137 </p> 138<p> 139 Finally the script can add rewrite rules, that rename section names that 140 are automatically used as index entries. For example we might want to remove 141 leading "A" or "The" prefixes from section titles when 142 AutoIndex uses them as an index entry: 143 </p> 144<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> 145</pre> 146</div> 147<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 148<td align="left"></td> 149<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p> 150 Distributed under the Boost Software License, Version 1.0. (See accompanying 151 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>) 152 </p> 153</div></td> 154</tr></table> 155<hr> 156<div class="spirit-nav"> 157<a accesskey="p" href="add_indexes.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.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="entries.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 158</div> 159</body> 160</html> 161
