ceph/src/boost/tools/auto_index/doc/html/boost_autoindex/tut/script.html

   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 &lt;auto-index-prefix&gt;.
  84           The examples here assume that this is <code class="literal">&lt;auto-index-prefix&gt;../../..</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">\&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>
 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">\&lt;</span><span class="identifier">reflex</span><span class="special">\</span><span class="identifier">w</span><span class="special">*\&gt;</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 &#169; 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>