|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r72692 - in sandbox/tools/auto_index/doc/html: autoindex boost_autoindex boost_autoindex/tut boost_autoindex/tut/configure
From: john_at_[hidden]
Date: 2011-06-20 11:36:12
Author: johnmaddock
Date: 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
New Revision: 72692
URL: http://svn.boost.org/trac/boost/changeset/72692
Log:
Update docs with more consistent naming "Boost.AutoIndex".
Added:
sandbox/tools/auto_index/doc/html/boost_autoindex/
sandbox/tools/auto_index/doc/html/boost_autoindex/comm_ref.html (contents, props changed)
sandbox/tools/auto_index/doc/html/boost_autoindex/overview.html (contents, props changed)
sandbox/tools/auto_index/doc/html/boost_autoindex/qbk.html (contents, props changed)
sandbox/tools/auto_index/doc/html/boost_autoindex/script_ref.html (contents, props changed)
sandbox/tools/auto_index/doc/html/boost_autoindex/tut/
sandbox/tools/auto_index/doc/html/boost_autoindex/tut.html (contents, props changed)
sandbox/tools/auto_index/doc/html/boost_autoindex/tut/add_indexes.html (contents, props changed)
sandbox/tools/auto_index/doc/html/boost_autoindex/tut/build.html (contents, props changed)
sandbox/tools/auto_index/doc/html/boost_autoindex/tut/build_docs.html (contents, props changed)
sandbox/tools/auto_index/doc/html/boost_autoindex/tut/configure/
sandbox/tools/auto_index/doc/html/boost_autoindex/tut/configure.html (contents, props changed)
sandbox/tools/auto_index/doc/html/boost_autoindex/tut/configure/optional.html (contents, props changed)
sandbox/tools/auto_index/doc/html/boost_autoindex/tut/configure/options.html (contents, props changed)
sandbox/tools/auto_index/doc/html/boost_autoindex/tut/entries.html (contents, props changed)
sandbox/tools/auto_index/doc/html/boost_autoindex/tut/pis.html (contents, props changed)
sandbox/tools/auto_index/doc/html/boost_autoindex/tut/refine.html (contents, props changed)
sandbox/tools/auto_index/doc/html/boost_autoindex/tut/script.html (contents, props changed)
sandbox/tools/auto_index/doc/html/boost_autoindex/workflow.html (contents, props changed)
sandbox/tools/auto_index/doc/html/boost_autoindex/xml.html (contents, props changed)
Removed:
sandbox/tools/auto_index/doc/html/autoindex/
Added: sandbox/tools/auto_index/doc/html/boost_autoindex/comm_ref.html
==============================================================================
--- (empty file)
+++ sandbox/tools/auto_index/doc/html/boost_autoindex/comm_ref.html 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
@@ -0,0 +1,87 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Command Line Reference</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../index.html" title="Boost.AutoIndex">
+<link rel="up" href="../index.html" title="Boost.AutoIndex">
+<link rel="prev" href="qbk.html" title="Quickbook Support">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="qbk.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_autoindex.comm_ref"></a><a class="link" href="comm_ref.html" title="Command Line Reference">Command Line Reference</a>
+</h2></div></div></div>
+<p>
+ The following command line options are supported by Boost.AutoIndex:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">in=infilename</span></dt>
+<dd><p>
+ Specifies the name of the XML input file to be indexed.
+ </p></dd>
+<dt><span class="term">out=outfilename</span></dt>
+<dd><p>
+ Specifies the name of the new XML file to create.
+ </p></dd>
+<dt><span class="term">scan=source-filename</span></dt>
+<dd><p>
+ Specifies that <span class="emphasis"><em>source-filename</em></span> should be scanned
+ for terms to index.
+ </p></dd>
+<dt><span class="term">script=script-filename</span></dt>
+<dd><p>
+ Specifies the name of the script file to process.
+ </p></dd>
+<dt><span class="term">--no-duplicates</span></dt>
+<dd><p>
+ If a term occurs more than once in the same section, then include only
+ one index entry.
+ </p></dd>
+<dt><span class="term">--internal-index</span></dt>
+<dd><p>
+ Specifies that Boost.AutoIndex should generate the actual indexes rather
+ than inserting <code class="computeroutput"><span class="special"><</span><span class="identifier">indexterm</span><span class="special">></span></code>s and leaving index generation to
+ the XSL stylesheets.
+ </p></dd>
+<dt><span class="term">--no-section-names</span></dt>
+<dd><p>
+ Prevents Boost.AutoIndex from using section names as index entries.
+ </p></dd>
+<dt><span class="term">prefix=pathname</span></dt>
+<dd><p>
+ Specifies a directory to apply as a prefix to all relative file paths
+ in the script file.
+ </p></dd>
+<dt><span class="term">index-type=element-name</span></dt>
+<dd><p>
+ Specifies the name of the XML element to enclose internally generated
+ indexes in: defaults to <span class="emphasis"><em>section</em></span>, but could equally
+ be <span class="emphasis"><em>appendix</em></span> or <span class="emphasis"><em>chapter</em></span> or some
+ other block level element that has a formal title.
+ </p></dd>
+</dl>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="qbk.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a>
+</div>
+</body>
+</html>
Added: sandbox/tools/auto_index/doc/html/boost_autoindex/overview.html
==============================================================================
--- (empty file)
+++ sandbox/tools/auto_index/doc/html/boost_autoindex/overview.html 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
@@ -0,0 +1,162 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Overview</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../index.html" title="Boost.AutoIndex">
+<link rel="up" href="../index.html" title="Boost.AutoIndex">
+<link rel="prev" href="../index.html" title="Boost.AutoIndex">
+<link rel="next" href="tut.html" title="Getting Started and Tutorial">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="tut.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_autoindex.overview"></a><a class="link" href="overview.html" title="Overview">Overview</a>
+</h2></div></div></div>
+<p>
+ Boost.AutoIndex is a tool for taking the grunt work out of indexing a Boostbook/Docbook
+ document (perhaps generated by your Quickbook file mylibrary.qbk, and perhaps
+ using also Doxygen autodoc) that describes C/C++ code.
+ </p>
+<p>
+ Traditionally, in order to index a Docbook document you would have to manually
+ add a large amount of <code class="computeroutput"><span class="special"><</span><span class="identifier">indexterm</span><span class="special">></span></code> markup: in fact one <code class="computeroutput"><span class="special"><</span><span class="identifier">indexterm</span><span class="special">></span></code>
+ for each occurrence of each term to be indexed.
+ </p>
+<p>
+ Instead Boost.AutoIndex will automatically scan one or more C/C++ header files
+ and extract all the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>,
+ <span class="emphasis"><em>macro</em></span> and <span class="emphasis"><em>typedef</em></span> names that are
+ defined by those headers, and then insert the <code class="computeroutput"><span class="special"><</span><span class="identifier">indexterm</span><span class="special">></span></code>s
+ into the Docbook XML document for you.
+ </p>
+<p>
+ Boost.AutoIndex can also scan using a list of index terms specified in a script
+ file, for example index.idx. These manually provided terms can optionally be
+ regular expressions, and may allow the user to find references to terms that
+ may not occur in the C++ header files. Of course providing a manual list of
+ search terms in to index is a tedious task (especially handling plurals and
+ variants), and requires enough knowledge of the library to guess what users
+ may be seeking to know, but at least the real 'grunt work' of finding the term
+ and listing the page number is automated.
+ </p>
+<p>
+ Boost.AutoIndex creates index entries as follows:
+ </p>
+<p>
+ for each occurrence of each search term, it creates two index entries:
+ </p>
+<div class="orderedlist"><ol type="1">
+<li>
+ The search term as the <span class="emphasis"><em>primary index key</em></span> and the
+ <span class="emphasis"><em>title of the section it appears in</em></span> as a subterm.
+ </li>
+<li>
+ The section title as the main index entry and the search term as the subentry.
+ </li>
+</ol></div>
+<p>
+ Thus the user has two chances to find what they're looking for, based upon
+ either the section name or the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>,
+ <span class="emphasis"><em>macro</em></span> or <span class="emphasis"><em>typedef</em></span> name.
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ This behaviour can be changed so that only one index entry is created (using
+ the search term as the key and not using the section name except as a sub-entry
+ of the search term).
+ </p></td></tr>
+</table></div>
+<p>
+ So for example in Boost.Math the class name <code class="computeroutput"><span class="identifier">students_t_distribution</span></code>
+ has a primary entry that lists all sections the class name appears in:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../students_t_eg_1.png" alt="students_t_eg_1"></span>
+ </p>
+<p>
+ Then those sections also have primary entries, which list all the search terms
+ those sections contain:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../students_t_eg_2.png" alt="students_t_eg_2"></span>
+ </p>
+<p>
+ Of course these automated index entries may not be quite what you're looking
+ for: often you'll get a few spurious entries, a few missing entries, and a
+ few entries where the section name used as an index entry is less than ideal.
+ So Boost.AutoIndex provides some powerful regular expression based rules that
+ allow you to add, remove, constrain, or rewrite entries. Normally just a few
+ lines in Boost.AutoIndex's script file are enough to tailor the output to match
+ the author's expectations (and thus hopefully the index user's expectations
+ too!).
+ </p>
+<p>
+ Boost.AutoIndex also supports multiple indexes (as does Docbook), and since
+ it knows which search terms are <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>,
+ <span class="emphasis"><em>macro</em></span> or <span class="emphasis"><em>typedef</em></span> names, it can add
+ the necessary attributes to the XML so that you can have separate indexes for
+ each of these different types. These specialised indexes only contain entries
+ for the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>, <span class="emphasis"><em>macro</em></span>
+ or <span class="emphasis"><em>typedef</em></span> names, <span class="emphasis"><em>section names</em></span> are
+ never used as primary index terms here, unlike the main "include everything"
+ index.
+ </p>
+<p>
+ Finally, while the Docbook XSL stylesheets create nice indexes complete with
+ page numbers for PDF output, the HTML indexes look poorer by comparison, as
+ these use section titles in place of page numbers... but as Boost.AutoIndex
+ uses section titles as index entries this leads to a lot of repetition, so
+ as an alternative Boost.AutoIndex can be instructed to construct the index
+ itself. This is faster than using the XSL stylesheets, and now each index entry
+ is a hyperlink to the appropriate section:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../students_t_eg_3.png" alt="students_t_eg_3"></span>
+ </p>
+<p>
+ With internal index generation there is also a helpful navigation bar at the
+ start of each Index:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../students_t_eg_4.png" alt="students_t_eg_4"></span>
+ </p>
+<p>
+ Finally, you can choose what kind of XML container wraps an internally generated
+ index - this defaults to <code class="computeroutput"><span class="special"><</span><span class="identifier">section</span><span class="special">>...</</span><span class="identifier">section</span><span class="special">></span></code>
+ but you can use either command line options or Boost.Build Jamfile features,
+ to select an alternative wrapper - for example <span class="emphasis"><em>appendix</em></span>
+ or <span class="emphasis"><em>chapter</em></span> would be good choices, whatever fits best into
+ the flow of the document. You can even set the container wrapper to type <span class="emphasis"><em>index</em></span>
+ provided you turn off index generation by the XSL stylesheets, for example
+ by setting the following build requirements in the Jamfile:
+ </p>
+<pre class="programlisting"><format>html:<auto-index-internal>on # Use internally generated indexes.
+<auto-index-type>index # Use <index>...</index> as the XML wrapper.
+<format>html:<xsl:param>generate.index=0 # Don't let the XSL stylesheets generate indexes.
+</pre>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="tut.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/tools/auto_index/doc/html/boost_autoindex/qbk.html
==============================================================================
--- (empty file)
+++ sandbox/tools/auto_index/doc/html/boost_autoindex/qbk.html 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
@@ -0,0 +1,222 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Quickbook Support</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../index.html" title="Boost.AutoIndex">
+<link rel="up" href="../index.html" title="Boost.AutoIndex">
+<link rel="prev" href="xml.html" title="XML Handling">
+<link rel="next" href="comm_ref.html" title="Command Line Reference">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="xml.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="comm_ref.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_autoindex.qbk"></a><a class="link" href="qbk.html" title="Quickbook Support">Quickbook Support</a>
+</h2></div></div></div>
+<p>
+ The file <a class="link" href="qbk.html" title="Quickbook Support">auto_index_helpers.qbk</a>
+ in <span class="emphasis"><em>boost-path</em></span>/tools/auto_index/include contains various
+ Quickbook templates to assist with Boost.AutoIndex support. One would normally
+ add the above path to your include search path via an <code class="computeroutput"><span class="special"><</span><span class="identifier">include</span><span class="special">></span><span class="identifier">path</span></code> statement in your Jamfile, and then
+ make the templates available to your Quickbook source via a:
+ </p>
+<pre class="programlisting">[include auto_index_helpers.qbk]</pre>
+<p>
+ statement at the start of your Quickbook file.
+ </p>
+<p>
+ The available templates are then:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Template
+ </p>
+ </th>
+<th>
+ <p>
+ Description
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special">[</span><span class="identifier">index</span><span class="special">]</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ Creates a main index, with no "type" category set, which
+ will be titled simply "Index".
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special">[</span><span class="identifier">named_index</span>
+ <span class="identifier">type</span> <span class="identifier">title</span><span class="special">]</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ Creates an index with the type attribute set to "type"
+ and the title will be "title".<br> For example to create
+ an index containing only class names one would typically add <code class="computeroutput"><span class="special">[</span><span class="identifier">named_index</span>
+ <span class="identifier">class_name</span> <span class="identifier">Class</span>
+ <span class="identifier">Index</span><span class="special">]</span></code>
+ to your Quickbook source.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special">[</span><span class="identifier">AutoIndex</span>
+ <span class="identifier">Arg</span><span class="special">]</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ Creates a Docbook processing instruction that will be handled by
+ Boost.AutoIndex, valid values for "Arg" are either "IgnoreSection"
+ or "IgnoreBlock".
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special">[</span><span class="identifier">indexterm1</span>
+ <span class="identifier">primary</span><span class="special">-</span><span class="identifier">key</span><span class="special">]</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ Creates a manual index entry that will link to the current section,
+ and have a single primary key "primary-key". Note that
+ this index key will not have a "type" attribute set, and
+ so will only appear in the main index.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special">[</span><span class="identifier">indexterm2</span>
+ <span class="identifier">primary</span><span class="special">-</span><span class="identifier">key</span> <span class="identifier">secondary</span><span class="special">-</span><span class="identifier">key</span><span class="special">]</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ Creates a manual index entry that will link to the current section,
+ and has "primary-key" and "secondary key" as
+ the primary and secondary keys respectively. Note that this index
+ key will not have a "type" attribute set, and so will only
+ appear in the main index.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special">[</span><span class="identifier">indexterm3</span>
+ <span class="identifier">primary</span><span class="special">-</span><span class="identifier">key</span> <span class="identifier">secondary</span><span class="special">-</span><span class="identifier">key</span>
+ <span class="identifier">tertiary</span><span class="special">-</span><span class="identifier">key</span><span class="special">]</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ Creates a manual index entry that will link to the current section,
+ and have primary, secondary and tertiary keys: "primary-key",
+ "secondary key" and "tertiary key". Note that
+ this index key will not have a "type" attribute set, and
+ so will only appear in the main index.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special">[</span><span class="identifier">typed_indexterm1</span>
+ <span class="identifier">type</span> <span class="identifier">primary</span><span class="special">-</span><span class="identifier">key</span><span class="special">]</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ Creates a manual index entry that will link to the current section,
+ and have a single primary key "primary-key". Note that
+ this index key will have the "type" attribute set to the
+ "type" argument, and so may appear in named sub-indexes
+ that also have their type attribute set.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special">[</span><span class="identifier">typed_indexterm2</span>
+ <span class="identifier">type</span> <span class="identifier">primary</span><span class="special">-</span><span class="identifier">key</span>
+ <span class="identifier">secondary</span><span class="special">-</span><span class="identifier">key</span><span class="special">]</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ Creates a manual index entry that will link to the current section,
+ and has "primary-key" and "secondary key" as
+ the primary and secondary keys respectively. Note that this index
+ key will have the "type" attribute set to the "type"
+ argument, and so may appear in named sub-indexes that also have their
+ type attribute set.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special">[</span><span class="identifier">typed_indexterm3</span>
+ <span class="identifier">type</span> <span class="identifier">primary</span><span class="special">-</span><span class="identifier">key</span>
+ <span class="identifier">secondary</span><span class="special">-</span><span class="identifier">key</span> <span class="identifier">tertiary</span><span class="special">-</span><span class="identifier">key</span><span class="special">]</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ Creates a manual index entry that will link to the current section,
+ and have primary, secondary and tertiary keys: "primary-key",
+ "secondary key" and "tertiary key". Note that
+ this index key will have the "type" attribute set to the
+ "type" argument, and so may appear in named sub-indexes
+ that also have their type attribute set.
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="xml.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="comm_ref.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/tools/auto_index/doc/html/boost_autoindex/script_ref.html
==============================================================================
--- (empty file)
+++ sandbox/tools/auto_index/doc/html/boost_autoindex/script_ref.html 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
@@ -0,0 +1,518 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Script File (.idx) Reference</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../index.html" title="Boost.AutoIndex">
+<link rel="up" href="../index.html" title="Boost.AutoIndex">
+<link rel="prev" href="tut/refine.html" title="Step 8: Iterate - to refine your index">
+<link rel="next" href="workflow.html" title="Understanding The Boost.AutoIndex Workflow">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tut/refine.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="workflow.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_autoindex.script_ref"></a><a class="link" href="script_ref.html" title="Script File (.idx) Reference">Script File (.idx) Reference</a>
+</h2></div></div></div>
+<p>
+ The following elements can occur in a script:
+ </p>
+<a name="boost_autoindex.script_ref.comments_and_blank_lines"></a><h5>
+<a name="boost_autoindex.script_ref.comments_and_blank_lines-heading"></a>
+ <a class="link" href="script_ref.html#boost_autoindex.script_ref.comments_and_blank_lines">Comments
+ and blank lines</a>
+ </h5>
+<p>
+ Blank lines consisting of only whitespace are ignored, so are lines that <span class="bold"><strong>start with a #</strong></span>.
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ You can't append # comments onto the end of a line!
+ </p></td></tr>
+</table></div>
+<a name="boost_autoindex.script_ref.inclusion_of_index_terms"></a><h5>
+<a name="boost_autoindex.script_ref.inclusion_of_index_terms-heading"></a>
+ <a class="link" href="script_ref.html#boost_autoindex.script_ref.inclusion_of_index_terms">Inclusion
+ of Index terms</a>
+ </h5>
+<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>
+</pre>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">term</span></dt>
+<dd>
+<p>
+ <span class="emphasis"><em>Term to index.</em></span>
+ </p>
+<p>
+ The index term will form a primary entry in the Index with the section
+ title(s) containing the term as secondary entries, and also will be used
+ as a secondary entry beneath each of the section titles that the index
+ term occurs in.
+ </p>
+</dd>
+<dt><span class="term">regular-expression1</span></dt>
+<dd>
+<p>
+ <span class="emphasis"><em>Index term Searcher.</em></span>
+ </p>
+<p>
+ An optional regular expression: each occurrence of the regular expression
+ in the text of the document will result in one index term being emitted.
+ </p>
+<p>
+ If the regular expression is omitted (default) or is "", then
+ the <span class="emphasis"><em>index term</em></span> itself will be used as the search
+ text - and only occurrence of whole words matching <span class="emphasis"><em>index term</em></span>
+ will be indexed.
+ </p>
+<p>
+ For example:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">foobar</span></pre>
+<p>
+ </p>
+<p>
+ will index occurrences of "foobar" in any section, but
+ </p>
+<p>
+
+</p>
+<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>
+<p>
+ </p>
+<p>
+ will index any whole word containing either "foo" or "bar"
+ within it. This is useful when you want to index a lot of similar or
+ related words under one entry.
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">reflex</span></pre>
+<p>
+ </p>
+<p>
+ will only index occurrences of "reflex" as a whole word, but:
+ </p>
+<p>
+
+</p>
+<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>
+<p>
+ </p>
+<p>
+ will index occurrences of "reflex", "reflexes", "reflexing"
+ and "reflexed" ... all under the same entry reflex.
+ </p>
+<p>
+ You will very often need to use this to deal with plurals and other variants.
+ </p>
+</dd>
+<dt><span class="term">regular-expression2</span></dt>
+<dd>
+<p>
+ <span class="emphasis"><em>Section(s) Selector.</em></span>
+ </p>
+<p>
+ A constraint that specifies which sections are indexed for <span class="emphasis"><em>term</em></span>:
+ only if the ID of the section matches <span class="emphasis"><em>regular-expression2</em></span>
+ exactly will that section be indexed for occurrences of <span class="emphasis"><em>term</em></span>.
+ </p>
+<p>
+ For example, to limit indexing to just <span class="bold"><strong>one specific
+ section</strong></span> (but not sub-sections below):
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">myclass</span> <span class="string">""</span> <span class="string">"mylib\.examples"</span></pre>
+<p>
+ </p>
+<p>
+ For example, to limit indexing to specific sections, <span class="bold"><strong>and
+ sub-sections below</strong></span>:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">myclass</span> <span class="string">""</span> <span class="string">"mylib\.examples.*"</span></pre>
+<p>
+ </p>
+<p>
+ will index occurrences of "myclass" as a whole word, but only
+ in sections whose section ID <span class="bold"><strong>begins</strong></span>
+ "mylib.examples", while
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">myclass</span> <span class="string">"\<myclass\w*\>"</span> <span class="string">"mylib\.examples.*"</span></pre>
+<p>
+ </p>
+<p>
+ will also index plurals myclass, myclasses, myclasss ...
+ </p>
+<p>
+ and:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">myclass</span> <span class="string">""</span> <span class="string">"(?!mylib\.introduction).*"</span></pre>
+<p>
+ </p>
+<p>
+ will index occurrences of "myclass" in any section, except
+ those whose section IDs begin "mylib.introduction".
+ </p>
+<p>
+ Finally, two (or more) sections can be excluded by OR'ing them together:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">myclass</span> <span class="string">""</span> <span class="string">"(?!mylib\.introduction|mylib\.reference).*"</span></pre>
+<p>
+ </p>
+<p>
+ which excludes searching for this term in sections whose ID's start with
+ either "mylib.introduction" or "mylib.reference".
+ </p>
+<p>
+ If this third section selection field is omitted (the default) or is
+ "", then <span class="bold"><strong>all sections</strong></span> are
+ indexed for this term.
+ </p>
+</dd>
+<dt><span class="term">category</span></dt>
+<dd>
+<p>
+ <span class="emphasis"><em>Index Category Constraint.</em></span>
+ </p>
+<p>
+ Optionally a category to place occurrences of <span class="emphasis"><em>index term</em></span>
+ in. If you have multiple indexes then this is the name assigned to the
+ indexes "type" attribute.
+ </p>
+<p>
+ For example:
+ </p>
+<p>
+ myclass "" "" class_name
+ </p>
+<p>
+ Will index occurances of <span class="emphasis"><em>myclass</em></span> and place them
+ in the class-index if there is one.
+ </p>
+</dd>
+</dl>
+</div>
+<p>
+ You can have an index term appear more than once in the script file:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ If they have different <span class="emphasis"><em>category</em></span> names then they are
+ treated quite separately.
+ </li>
+<li>
+ Otherwise they are combined, so that the logical or of the regular expressions
+ provided are taken.
+ </li>
+</ul></div>
+<p>
+ Thus:
+ </p>
+<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>
+<span class="identifier">myterm</span> <span class="identifier">search_expression1</span> <span class="identifier">constrait_expression2</span> <span class="identifier">bar</span>
+</pre>
+<p>
+ Will be treated as different terms each with their own entries, while:
+ </p>
+<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>
+<span class="identifier">myterm</span> <span class="identifier">search_expression1</span> <span class="identifier">constrait_expression2</span> <span class="identifier">mycategory</span>
+</pre>
+<p>
+ Will be combined into a single term equivalent to:
+ </p>
+<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>
+</pre>
+<a name="boost_autoindex.script_ref.source_file_scanning"></a><h5>
+<a name="boost_autoindex.script_ref.source_file_scanning-heading"></a>
+ <a class="link" href="script_ref.html#boost_autoindex.script_ref.source_file_scanning">Source File
+ Scanning</a>
+ </h5>
+<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>
+</pre>
+<p>
+ Scans the C/C++ source file <span class="emphasis"><em>source-file-name</em></span> for definitions
+ 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
+ or <span class="emphasis"><em>typedef</em></span>s and makes each of these a term to be indexed.
+ Terms found are assigned to the index category "function_name", "class_name",
+ "macro_name" or "typedef_name" depending on how they were
+ seen in the source file. These may then be included in a specialised index
+ whose "type" attribute has the same category name.
+ </p>
+<div class="important"><table border="0" summary="Important">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../images/important.png"></td>
+<th align="left">Important</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ When actually indexing a document, the scanner will not index just any old
+ occurrence of the terms found in the source files. Instead it searches for
+ class definitions or function or typedef declarations. This reduces the number
+ of spurious matches placed in the index, but may also miss some legitimate
+ terms: refer to the <span class="emphasis"><em>define-scanner</em></span> command for information
+ on how to change this.
+ </p></td></tr>
+</table></div>
+<a name="boost_autoindex.script_ref.directory_and_source_file_scanning"></a><h5>
+<a name="boost_autoindex.script_ref.directory_and_source_file_scanning-heading"></a>
+ <a class="link" href="script_ref.html#boost_autoindex.script_ref.directory_and_source_file_scanning">Directory
+ and Source File Scanning</a>
+ </h5>
+<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>
+</pre>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">directory-name</span></dt>
+<dd><p>
+ The directory to scan: this should be a path relative to the script file
+ (or to the path specified with the prefix=path option on the command
+ line) and should use all forward slashes in its file name.
+ </p></dd>
+<dt><span class="term">file-name-regex</span></dt>
+<dd><p>
+ A regular expression: any file in the directory whose name matches the
+ regular expression will be scanned for terms to index.
+ </p></dd>
+<dt><span class="term">recurse</span></dt>
+<dd><p>
+ An optional boolean value - either "true" or "false"
+ - that indicates whether to recurse into subdirectories. This defaults
+ to "false".
+ </p></dd>
+</dl>
+</div>
+<a name="boost_autoindex.script_ref.excluding_terms"></a><h5>
+<a name="boost_autoindex.script_ref.excluding_terms-heading"></a>
+ <a class="link" href="script_ref.html#boost_autoindex.script_ref.excluding_terms">Excluding Terms</a>
+ </h5>
+<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>
+</pre>
+<p>
+ Excludes all the terms in whitespace separated <span class="emphasis"><em>term-list</em></span>
+ from being indexed. This should be placed <span class="emphasis"><em>after</em></span> any <span class="emphasis"><em>!scan</em></span>
+ or <span class="emphasis"><em>!scan-path</em></span> rules which may result in the terms becoming
+ included. In other words this removes terms from the scanners internal list
+ of things to index.
+ </p>
+<a name="boost_autoindex.script_ref.rewriting_section_names"></a><h5>
+<a name="boost_autoindex.script_ref.rewriting_section_names-heading"></a>
+ <a class="link" href="script_ref.html#boost_autoindex.script_ref.rewriting_section_names">Rewriting
+ Section Names</a>
+ </h5>
+<pre class="programlisting">!rewrite-id regular-expression new-name</pre>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">regular-expression</span></dt>
+<dd><p>
+ A regular expression: all section ID's that match the expression exactly
+ will have index entries <span class="emphasis"><em>new-name</em></span> instead of their
+ title(s).
+ </p></dd>
+<dt><span class="term">new-name</span></dt>
+<dd><p>
+ The name that the section will appear under in the index.
+ </p></dd>
+</dl>
+</div>
+<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>
+</pre>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">regular-expression</span></dt>
+<dd><p>
+ A regular expression: all sections whose titles match the regular expression
+ exactly, will have index entries composed of the regular expression match
+ combined with the regex format string <span class="emphasis"><em>format-text</em></span>.
+ </p></dd>
+<dt><span class="term">format-text</span></dt>
+<dd><p>
+ The Perl-style format string used to reformat the title.
+ </p></dd>
+</dl>
+</div>
+<p>
+ For example:
+ </p>
+<pre class="programlisting">!rewrite-name "(?:A|An|The)\s+(.*)" "\1"
+</pre>
+<p>
+ Will remove any leading "A", "An" or "The" from
+ all index entries - thus preventing lots of entries under "The" etc!
+ </p>
+<a name="boost_autoindex.script_ref.defining_or_changing_the_file_scanners"></a><h5>
+<a name="boost_autoindex.script_ref.defining_or_changing_the_file_scanners-heading"></a>
+ <a class="link" href="script_ref.html#boost_autoindex.script_ref.defining_or_changing_the_file_scanners">Defining
+ or Changing the File Scanners</a>
+ </h5>
+<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>
+</pre>
+<p>
+ When a source file is scanned using the <code class="literal">!scan</code> or <code class="literal">!scan-path</code>
+ rules, then the file is searched using a series of regular expressions to look
+ for classes, functions, macros or typedefs that should be indexed. A set of
+ default regular expressions are provided for this (see below), but sometimes
+ you may want to replace the defaults, or add new scanners. The arguments to
+ this rule are:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">type</span></dt>
+<dd><p>
+ The <span class="emphasis"><em>type</em></span> to which items found using this rule will
+ assigned, index terms created from the source file and then found in
+ the XML, will have the type attribute set to this value, and may then
+ appear in a specialized index with the same type attribute
+ </p></dd>
+<dt><span class="term">file-search-expression</span></dt>
+<dd><p>
+ A regular expression that is used to scan the source file for index terms,
+ the result of a match against this expression will be transformed by
+ the next two arguments.
+ </p></dd>
+<dt><span class="term">xml-regex-formatter</span></dt>
+<dd><p>
+ A regular expression format string that extracts the salient information
+ from whatever matched the <span class="emphasis"><em>file-search-expression</em></span>
+ in the source file, and creates <span class="emphasis"><em>a new regular expression</em></span>
+ that will be used to search the document being indexed for occurrences
+ of this index term.
+ </p></dd>
+<dt><span class="term">term-formatter</span></dt>
+<dd><p>
+ A regular expression format string that extracts the salient information
+ from whatever matched the <span class="emphasis"><em>file-search-expression</em></span>
+ in the source file, and creates the index term that will appear in the
+ index.
+ </p></dd>
+<dt><span class="term">id-filter</span></dt>
+<dd><p>
+ Optional. A regular expression that restricts the section-id's that are
+ searched in the document being indexed: only sections whose ID attribute
+ matches this expression exactly will be considered for indexing terms
+ found by this scanner.
+ </p></dd>
+<dt><span class="term">filename-filter</span></dt>
+<dd><p>
+ Optional. A regular expression that restricts which files are scanned
+ by this scanner: only files whose file name matches this expression exactly
+ will be scanned for index terms to use. Note that the filename matched
+ against this may well be an absolute path, and contain either forward
+ or backward slash path separators.
+ </p></dd>
+</dl>
+</div>
+<p>
+ If, when the first file is scanned, there are no scanners whose <span class="emphasis"><em>type</em></span>
+ is "class_name", "typedef_name", "macro_name"
+ or "function_name", then the defaults are installed. These are equivalent
+ to:
+ </p>
+<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>
+<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>
+<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>
+<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>
+</pre>
+<p>
+ Note that these defaults are not installed if you have provided your own versions
+ with these <span class="emphasis"><em>type</em></span> names. In this case if you want the default
+ scanners to be in effect as well as your own, you should include the above
+ in your script file. It is also perfectly allowable to have multiple scanners
+ with the same <span class="emphasis"><em>type</em></span>, but with the other fields differing.
+ </p>
+<p>
+ Finally you should note that the default scanners are quite strict in what
+ they will find, for example the class scanner will only create index entries
+ for classes that have class definitions of the form:
+ </p>
+<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>
+<span class="special">{</span>
+ <span class="comment">// etc</span>
+</pre>
+<p>
+ In the documentation, so that simple mentions of the class name will <span class="emphasis"><em>not</em></span>
+ get indexed, only the class synopsis if there is one. If this isn't how you
+ want things, then include the <span class="emphasis"><em>class_name</em></span> scanner definition
+ above in your script file, and change the <span class="emphasis"><em>xml-regex-formatter</em></span>
+ field to something more permissive, for example:
+ </p>
+<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>
+</pre>
+<p>
+ Will look for <span class="emphasis"><em>any</em></span> occurrence of whatever class names the
+ scanner may find in the documentation.
+ </p>
+<a name="boost_autoindex.script_ref.debugging_scanning"></a><h5>
+<a name="boost_autoindex.script_ref.debugging_scanning-heading"></a>
+ <a class="link" href="script_ref.html#boost_autoindex.script_ref.debugging_scanning">Debugging scanning</a>
+ </h5>
+<p>
+ If you see a term in the index, and you don't understand why it's there, add
+ a <span class="emphasis"><em>debug</em></span> directive:
+ </p>
+<pre class="programlisting">!debug regular-expression
+</pre>
+<p>
+ Now, whenever <span class="emphasis"><em>regular-expression</em></span> matches either the found
+ index term, or the section title it appears in, or the <span class="emphasis"><em>type</em></span>
+ field of a scanner, then some diagnostic information will be printed that will
+ look something like:
+ </p>
+<pre class="programlisting">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: .<span class="bold"><strong>qi.reference.parser_concepts.</strong></span>
+The index type for this entry is: qi_index
+</pre>
+<p>
+ This can produce a lot of output in your log file, but until you are satisfied
+ with your file selection and scanning process, it is worth switching it on.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tut/refine.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="workflow.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/tools/auto_index/doc/html/boost_autoindex/tut.html
==============================================================================
--- (empty file)
+++ sandbox/tools/auto_index/doc/html/boost_autoindex/tut.html 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
@@ -0,0 +1,59 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Getting Started and Tutorial</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../index.html" title="Boost.AutoIndex">
+<link rel="up" href="../index.html" title="Boost.AutoIndex">
+<link rel="prev" href="overview.html" title="Overview">
+<link rel="next" href="tut/build.html" title="Step 1: Build the Boost.AutoIndex tool">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="overview.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="tut/build.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_autoindex.tut"></a><a class="link" href="tut.html" title="Getting Started and Tutorial">Getting Started and Tutorial</a>
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="tut/build.html">Step 1: Build the Boost.AutoIndex
+ tool</a></span></dt>
+<dt><span class="section"><a href="tut/configure.html">Step 2: Configure Boost.Build
+ jamfile to use Boost.AutoIndex</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="tut/configure/options.html">Available Indexing
+ Options</a></span></dt>
+<dt><span class="section"><a href="tut/configure/optional.html">Making Boost.AutoIndex
+ optional</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="tut/add_indexes.html">Step 3: Add indexes
+ to your documentation</a></span></dt>
+<dt><span class="section"><a href="tut/script.html">Step 4: Create the .idx script
+ file - to control what to terms to index</a></span></dt>
+<dt><span class="section"><a href="tut/entries.html">Step 5: Add Manual Index
+ Entries to Docbook XML - Optional</a></span></dt>
+<dt><span class="section"><a href="tut/pis.html">Step 6: Using XML processing
+ instructions to control what gets indexed.</a></span></dt>
+<dt><span class="section">Step 7: Build the Docs</span></dt>
+<dt><span class="section"><a href="tut/refine.html">Step 8: Iterate - to refine
+ your index</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="overview.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="tut/build.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/tools/auto_index/doc/html/boost_autoindex/tut/add_indexes.html
==============================================================================
--- (empty file)
+++ sandbox/tools/auto_index/doc/html/boost_autoindex/tut/add_indexes.html 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
@@ -0,0 +1,168 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Step 3: Add indexes to your documentation</title>
+<link rel="stylesheet" href="../../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../../index.html" title="Boost.AutoIndex">
+<link rel="up" href="../tut.html" title="Getting Started and Tutorial">
+<link rel="prev" href="configure/optional.html" title="Making Boost.AutoIndex optional">
+<link rel="next" href="script.html" title="Step 4: Create the .idx script file - to control what to terms to index">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="configure/optional.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="script.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_autoindex.tut.add_indexes"></a><a class="link" href="add_indexes.html" title="Step 3: Add indexes to your documentation">Step 3: Add indexes
+ to your documentation</a>
+</h3></div></div></div>
+<p>
+ To add a single "include everything" index to a BoostBook/Docbook
+ document, (perhaps generated using Quickbook, and perhaps also using Doxygen
+ reference section), add <code class="computeroutput"><span class="special"><</span><span class="identifier">index</span><span class="special">/></span></code>
+ at the location where you want the index to appear. The index will be rendered
+ as a separate section called "Index" when the documentation is
+ built.
+ </p>
+<p>
+ To add multiple indexes, then give each one a title and set its <code class="computeroutput"><span class="identifier">type</span></code> attribute to specify which terms will
+ be included, for example to place the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>,
+ <span class="emphasis"><em>macro</em></span> or <span class="emphasis"><em>typedef</em></span> names indexed
+ by Boost.AutoIndex in separate indexes along with a main "include everything"
+ index as well, one could add:
+ </p>
+<pre class="programlisting"><index type="class_name">
+<title>Class Index</title>
+</index>
+
+<index type="typedef_name">
+<title>Typedef Index</title>
+</index>
+
+<index type="function_name">
+<title>Function Index</title>
+</index>
+
+<index type="macro_name">
+<title>Macro Index</title>
+</index>
+
+<index/>
+</pre>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ Multiple indexes like this only work correctly if you tell the XSL stylesheets
+ to honor the "type" attribute on each index as by default . You
+ can turn the feature on by adding <code class="computeroutput"><span class="special"><</span><span class="identifier">xsl</span><span class="special">:</span><span class="identifier">param</span><span class="special">></span><span class="identifier">index</span><span class="special">.</span><span class="identifier">on</span><span class="special">.</span><span class="identifier">type</span><span class="special">=</span><span class="number">1</span></code> to your
+ projects requirements in the Jamfile.
+ </p></td></tr>
+</table></div>
+<p>
+ In Quickbook, you add the same markup but enclose it between two triple-tick
+ ''' escapes, thus
+ </p>
+<pre class="programlisting">'''<index/>''' </pre>
+<p>
+ Or more easily via the helper file <a class="link" href="../qbk.html" title="Quickbook Support">auto_index_helpers.qbk</a>,
+ so that given:
+ </p>
+<pre class="programlisting">[include auto_index_helpers.qbk]</pre>
+<p>
+ one can simply write:
+ </p>
+<pre class="programlisting">[named_index class_name Class Index]
+[named_index function_name Function Index]
+[named_index typedef_name Typedef Index]
+[named_index macro_name Macro Index]
+[index]
+</pre>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ Boost.AutoIndex knows nothing of the XML <code class="computeroutput"><span class="identifier">xinclude</span></code>
+ element, so if you're writing raw Docbook XML then you may want to run
+ this through an XSL processor to flatten everything to one XML file before
+ passing to Boost.AutoIndex. If you're using Boostbook or quickbook though,
+ this all happens for you anyway, and Boost.AutoIndex will index the whole
+ document including any sections included with <code class="computeroutput"><span class="identifier">xinclude</span></code>.
+ </p></td></tr>
+</table></div>
+<p>
+ If you are using Boost.AutoIndex's internal index generation:
+ </p>
+<pre class="programlisting"><auto-index-internal>on
+</pre>
+<p>
+ (usually recommended for HTML output, but <span class="emphasis"><em>not</em></span> the default)
+ then you can also decide what kind of XML wrapper the generated index is
+ placed in. By default this is a <code class="computeroutput"><span class="special"><</span><span class="identifier">section</span><span class="special">>...</</span><span class="identifier">section</span><span class="special">></span></code>
+ XML block (this replaces the original <code class="computeroutput"><span class="special"><</span><span class="identifier">index</span><span class="special">>...</</span><span class="identifier">index</span><span class="special">></span></code>
+ block). However, depending upon the structure of the document and whether
+ or not you want the index on a separate page - or else on the front page
+ after the TOC - you may want to place the index inside a different type of
+ XML block. For example if your document uses <code class="computeroutput"><span class="special"><</span><span class="identifier">chapter</span><span class="special">></span></code>
+ top level content rather than <code class="computeroutput"><span class="special"><</span><span class="identifier">section</span><span class="special">></span></code>s
+ then it may be preferable to place the index in a <code class="computeroutput"><span class="special"><</span><span class="identifier">chapter</span><span class="special">></span></code>
+ or <code class="computeroutput"><span class="special"><</span><span class="identifier">appendix</span><span class="special">></span></code> block. You can also place the index inside
+ an <code class="computeroutput"><span class="special"><</span><span class="identifier">index</span><span class="special">></span></code> block if you prefer, in which case the
+ index does not appear in on a page of its own, but after the TOC in the HTML
+ output.
+ </p>
+<p>
+ You control the type of XML block used by setting the <code class="literal"><auto-index-type>element-name</code>
+ attribute in the Jamfile, or via the <code class="computeroutput"><span class="identifier">index</span><span class="special">-</span><span class="identifier">type</span><span class="special">=</span><span class="identifier">element</span><span class="special">-</span><span class="identifier">name</span></code> command line option to Boost.AutoIndex
+ itself. For example, to place the index in an appendix, your Jamfile might
+ look like:
+ </p>
+<pre class="programlisting">using quickbook ;
+using auto-index ;
+
+xml mylibrary : mylibary.qbk ;
+boostbook standalone
+ :
+ mylibrary
+ :
+ # auto-indexing is on:
+ <auto-index>on
+
+ # PDFs rely on the XSL stylesheets to generate the index:
+ <format>pdf:<auto-index-internal>off
+
+ # HTML output uses auto-index to generate the index:
+ <format>html:<auto-index-internal>on
+
+ # Name of script file to use:
+ <auto-index-script>index.idx
+
+ # Set the XML wrapper for HML Indexes to "appendix":
+ <format>html:<auto-index-type>appendix
+
+ # Turn on multiple index support:
+ <xsl:param>index.on.type=1
+</pre>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="configure/optional.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="script.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/tools/auto_index/doc/html/boost_autoindex/tut/build.html
==============================================================================
--- (empty file)
+++ sandbox/tools/auto_index/doc/html/boost_autoindex/tut/build.html 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
@@ -0,0 +1,70 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Step 1: Build the Boost.AutoIndex tool</title>
+<link rel="stylesheet" href="../../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../../index.html" title="Boost.AutoIndex">
+<link rel="up" href="../tut.html" title="Getting Started and Tutorial">
+<link rel="prev" href="../tut.html" title="Getting Started and Tutorial">
+<link rel="next" href="configure.html" title="Step 2: Configure Boost.Build jamfile to use Boost.AutoIndex">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../tut.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="configure.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_autoindex.tut.build"></a><a class="link" href="build.html" title="Step 1: Build the Boost.AutoIndex tool">Step 1: Build the Boost.AutoIndex
+ tool</a>
+</h3></div></div></div>
+<p>
+ cd into <code class="computeroutput"><span class="identifier">tools</span><span class="special">/</span><span class="identifier">auto_index</span><span class="special">/</span><span class="identifier">build</span></code> and invoke bjam as:
+ </p>
+<pre class="programlisting"><span class="identifier">bjam</span> <span class="identifier">release</span>
+</pre>
+<p>
+ Optionally pass the name of the compiler toolset you want to use to bjam
+ as well:
+ </p>
+<pre class="programlisting"><span class="identifier">bjam</span> <span class="identifier">release</span> <span class="identifier">gcc</span>
+</pre>
+<p>
+ Now open up your <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code> file and at the end of the file add
+ the line:
+ </p>
+<pre class="programlisting">using auto-index : <span class="emphasis"><em>full-path-of-executable-auto-index.exe</em></span> ;
+</pre>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ This declaration must go towards the end of <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code>,
+ or in any case after the Boostbook initialisation.
+ </p>
+<p>
+ Also note that Windows users must use forward slashes in the paths in
+ <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code>
+ </p>
+</td></tr>
+</table></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../tut.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="configure.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/tools/auto_index/doc/html/boost_autoindex/tut/build_docs.html
==============================================================================
--- (empty file)
+++ sandbox/tools/auto_index/doc/html/boost_autoindex/tut/build_docs.html 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
@@ -0,0 +1,71 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Step 7: Build the Docs</title>
+<link rel="stylesheet" href="../../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../../index.html" title="Boost.AutoIndex">
+<link rel="up" href="../tut.html" title="Getting Started and Tutorial">
+<link rel="prev" href="pis.html" title="Step 6: Using XML processing instructions to control what gets indexed.">
+<link rel="next" href="refine.html" title="Step 8: Iterate - to refine your index">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="pis.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="refine.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_autoindex.tut.build_docs"></a><a class="link" href="build_docs.html" title="Step 7: Build the Docs">Step 7: Build the Docs</a>
+</h3></div></div></div>
+<p>
+ Using Boost.Build you build the docs with either:
+ </p>
+<pre class="programlisting"><span class="identifier">bjam</span> <span class="identifier">release</span> <span class="special">></span> <span class="identifier">mylibrary_html</span><span class="special">.</span><span class="identifier">log</span>
+</pre>
+<p>
+ To build the html docs or:
+ </p>
+<pre class="programlisting"><span class="identifier">bjam</span> <span class="identifier">pdf</span> <span class="identifier">release</span> <span class="special">></span> <span class="identifier">mylibrary_pdf</span><span class="special">.</span><span class="identifier">log</span>
+</pre>
+<p>
+ To build the pdf.
+ </p>
+<p>
+ During the build process you should see Boost.AutoIndex emit a message in
+ the log file such as:
+ </p>
+<pre class="programlisting">Indexing 990 terms... </pre>
+<p>
+ If you don't see that, or if it's indexing 0 terms then something is wrong!
+ </p>
+<p>
+ Likewise when index generation is complete, Boost.AutoIndex will emit another
+ message:
+ </p>
+<pre class="programlisting">38 Index entries were created.</pre>
+<p>
+ Again, if you see that 0 entries were created then something is wrong!
+ </p>
+<p>
+ Examine the log file, and if the cause is not obvious, make sure that you
+ have <code class="literal"><auto-index-verbose>on</code> and that any needed
+ <code class="literal">!debug regular-expression</code> directives are in your script
+ file.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="pis.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="refine.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/tools/auto_index/doc/html/boost_autoindex/tut/configure.html
==============================================================================
--- (empty file)
+++ sandbox/tools/auto_index/doc/html/boost_autoindex/tut/configure.html 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
@@ -0,0 +1,132 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Step 2: Configure Boost.Build jamfile to use Boost.AutoIndex</title>
+<link rel="stylesheet" href="../../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../../index.html" title="Boost.AutoIndex">
+<link rel="up" href="../tut.html" title="Getting Started and Tutorial">
+<link rel="prev" href="build.html" title="Step 1: Build the Boost.AutoIndex tool">
+<link rel="next" href="configure/options.html" title="Available Indexing Options">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="build.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="configure/options.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_autoindex.tut.configure"></a><a class="link" href="configure.html" title="Step 2: Configure Boost.Build jamfile to use Boost.AutoIndex">Step 2: Configure Boost.Build
+ jamfile to use Boost.AutoIndex</a>
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="configure/options.html">Available Indexing
+ Options</a></span></dt>
+<dt><span class="section"><a href="configure/optional.html">Making Boost.AutoIndex
+ optional</a></span></dt>
+</dl></div>
+<p>
+ Assuming you have a Jamfile for building your documentation that looks something
+ like:
+ </p>
+<pre class="programlisting">boostbook standalone
+ :
+ mylibrary
+ :
+ # build requirements go here:
+ ;
+</pre>
+<p>
+ Then add the line:
+ </p>
+<pre class="programlisting">using auto-index ; </pre>
+<p>
+ to the start of the Jamfile, and then add whatever Boost.AutoIndex options
+ you want to the <span class="emphasis"><em>build requirements section</em></span>, for example:
+ </p>
+<pre class="programlisting">boostbook standalone
+ :
+ mylibrary
+ :
+ # Build requirements go here:
+
+ # <auto-index>on (or off) one turns on (or off) indexing:
+ <auto-index>on
+
+ # Turns on (or off) auto-index-verbose for diagnostic info.
+ # This is highly recommended until you have got all the many details correct!
+ <auto-index-verbose>on
+
+ # Choose the indexing method (separately for html and PDF) - see manual.
+ # Choose indexing method for PDFs:
+ <format>pdf:<auto-index-internal>off
+
+ # Choose indexing method for html:
+ <format>html:<auto-index-internal>on
+
+ # Set the name of the script file to use (index.idx is popular):
+ <auto-index-script>index.idx
+ # Commands in the script file should all use RELATIVE PATHS
+ # otherwise the script will not be portable to other machines.
+ # Relative paths are normally taken as relative to the location
+ # of the script file, but we can add a prefix to all
+ # those relative paths using the <auto-index-prefix> feature.
+ # The path specified by <auto-index-prefix> may be either relative or
+ # absolute, for example the following will get us up to the boost root
+ # directory for most Boost libraries:
+ <auto-index-prefix>../../..
+
+ # Tell Quickbook that it should enable indexing.
+ <quickbook-define>enable_index ;
+
+ ;
+</pre>
+<div class="tip"><table border="0" summary="Tip">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../images/tip.png"></td>
+<th align="left">Tip</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ Always send the output to a log file. It will contain of lot of stuff,
+ but is invaluable to check if all has gone right, and else diagnose what
+ has gone wrong.
+ </p></td></tr>
+</table></div>
+<div class="tip"><table border="0" summary="Tip">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../images/tip.png"></td>
+<th align="left">Tip</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ A return code of 0 is not a reliable indication that you have got what
+ you really want - inspecting the log file is the only certain way.
+ </p></td></tr>
+</table></div>
+<div class="tip"><table border="0" summary="Tip">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../images/tip.png"></td>
+<th align="left">Tip</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ If you upgrade compiler version, for example MSVC from 9 to 10, then you
+ may need to rebuild Boost.AutoIndex to avoid what Microsoft call a 'side-by-side'
+ error. And make sure that the autoindex.exe version you are using is the
+ new one.
+ </p></td></tr>
+</table></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="build.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="configure/options.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/tools/auto_index/doc/html/boost_autoindex/tut/configure/optional.html
==============================================================================
--- (empty file)
+++ sandbox/tools/auto_index/doc/html/boost_autoindex/tut/configure/optional.html 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
@@ -0,0 +1,99 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Making Boost.AutoIndex optional</title>
+<link rel="stylesheet" href="../../../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../../../index.html" title="Boost.AutoIndex">
+<link rel="up" href="../configure.html" title="Step 2: Configure Boost.Build jamfile to use Boost.AutoIndex">
+<link rel="prev" href="options.html" title="Available Indexing Options">
+<link rel="next" href="../add_indexes.html" title="Step 3: Add indexes to your documentation">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="options.html"><img src="../../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../configure.html"><img src="../../../images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../images/home.png" alt="Home"></a><a accesskey="n" href="../add_indexes.html"><img src="../../../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_autoindex.tut.configure.optional"></a><a class="link" href="optional.html" title="Making Boost.AutoIndex optional">Making Boost.AutoIndex
+ optional</a>
+</h4></div></div></div>
+<p>
+ It is considerate to make the <span class="bold"><strong>use of Boost.AutoIndex
+ optional</strong></span> in Boost.Build, to allow users who do not have Boost.AutoIndex
+ installed to still be able to build your documentation.
+ </p>
+<p>
+ This also very convenient while you are refining your documentation, to
+ allow you to decide to build indexes, or not: building indexes can take
+ long time, if you are just correcting typos, you won't want to wait while
+ you keep rebuilding the index!
+ </p>
+<p>
+ One method of setting up optional Boost.AutoIndex support is to place all
+ Boost.AutoIndex configuration in a the body of a bjam if statement:
+ </p>
+<pre class="programlisting">if --enable-index in [ modules.peek : ARGV ]
+ {
+ ECHO "Building the docs with automatic index generation enabled." ;
+
+ using auto-index ;
+ project : requirements
+ <auto-index>on
+ <auto-index-script>index.idx
+
+ ... other auto-index options here...
+
+ # And tell Quickbook that it should enable indexing.
+ <quickbook-define>enable_index
+ ;
+ }
+ else
+ {
+ ECHO "Building the my_library docs with automatic index generation disabled. To get an index, try building with --enable-index." ;
+ }
+</pre>
+<p>
+ You will also need to add a conditional statement at the end of your Quickbook
+ file, so that the index(es) is/are only added after the last section if
+ indexing is enabled.
+ </p>
+<pre class="programlisting">[? enable_index
+'''
+ <index/>
+'''
+]
+</pre>
+<p>
+ To use this jamfile, you need to cd to your docs folder, for example:
+ </p>
+<pre class="programlisting"><span class="identifier">cd</span> <span class="special">\</span><span class="identifier">boost</span><span class="special">-</span><span class="identifier">sandbox</span><span class="special">\</span><span class="identifier">guild</span><span class="special">\</span><span class="identifier">mylibrary</span><span class="special">\</span><span class="identifier">libs</span><span class="special">\</span><span class="identifier">mylibrary</span><span class="special">\</span><span class="identifier">doc</span>
+</pre>
+<p>
+ and then run <code class="computeroutput"><span class="identifier">bjam</span></code> to build
+ the docs without index, for example:
+ </p>
+<pre class="programlisting"><span class="identifier">bjam</span> <span class="special">-</span><span class="identifier">a</span> <span class="identifier">html</span> <span class="special">></span> <span class="identifier">mylibrary_html</span><span class="special">.</span><span class="identifier">log</span>
+</pre>
+<p>
+ or with index(es)
+ </p>
+<pre class="programlisting"><span class="identifier">bjam</span> <span class="special">-</span><span class="identifier">a</span> <span class="identifier">html</span> <span class="special">--</span><span class="identifier">enable</span><span class="special">-</span><span class="identifier">index</span> <span class="special">></span> <span class="identifier">mylibrary_html_index</span><span class="special">.</span><span class="identifier">log</span>
+</pre>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="options.html"><img src="../../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../configure.html"><img src="../../../images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../images/home.png" alt="Home"></a><a accesskey="n" href="../add_indexes.html"><img src="../../../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/tools/auto_index/doc/html/boost_autoindex/tut/configure/options.html
==============================================================================
--- (empty file)
+++ sandbox/tools/auto_index/doc/html/boost_autoindex/tut/configure/options.html 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
@@ -0,0 +1,412 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Available Indexing Options</title>
+<link rel="stylesheet" href="../../../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../../../index.html" title="Boost.AutoIndex">
+<link rel="up" href="../configure.html" title="Step 2: Configure Boost.Build jamfile to use Boost.AutoIndex">
+<link rel="prev" href="../configure.html" title="Step 2: Configure Boost.Build jamfile to use Boost.AutoIndex">
+<link rel="next" href="optional.html" title="Making Boost.AutoIndex optional">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../configure.html"><img src="../../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../configure.html"><img src="../../../images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../images/home.png" alt="Home"></a><a accesskey="n" href="optional.html"><img src="../../../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_autoindex.tut.configure.options"></a><a class="link" href="options.html" title="Available Indexing Options">Available Indexing
+ Options</a>
+</h4></div></div></div>
+<p>
+ The available options are:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term"><auto-index>off/on</span></dt>
+<dd><p>
+ Turns indexing of the document on, defaults to "off", so
+ be sure to set this if you want AutoIndex invoked!
+ </p></dd>
+<dt><span class="term"><auto-index-internal>off/on</span></dt>
+<dd><p>
+ Chooses whether AutoIndex creates the index itself (feature on),
+ or whether it simply inserts the necessary DocBook markup so that
+ the DocBook XSL stylesheets can create the index. Defaults to "off".
+ </p></dd>
+<dt><span class="term"><auto-index-script>filename</span></dt>
+<dd><p>
+ Specifies the name of the script to load.
+ </p></dd>
+<dt><span class="term"><auto-index-no-duplicates>off/on</span></dt>
+<dd><p>
+ When <span class="emphasis"><em>on</em></span> AutoIndex will only index a term once
+ in any given section, otherwise (the default) multiple index entries
+ per term may be created if the term occurs more than once in the
+ section.
+ </p></dd>
+<dt><span class="term"><auto-index-section-names>off/on</span></dt>
+<dd><p>
+ When <span class="emphasis"><em>on</em></span> AutoIndex will use create two index
+ entries for each term found - one uses the term itself as the primary
+ index key, the other uses the enclosing section name. When off the
+ index entry that uses the section title is not created. Defaults
+ to "on"
+ </p></dd>
+<dt><span class="term"><auto-index-verbose>off/on</span></dt>
+<dd><p>
+ Defaults to "off". When turned on AutoIndex prints progress
+ information - useful for debugging purposes during setup.
+ </p></dd>
+<dt><span class="term"><auto-index-prefix>filename</span></dt>
+<dd>
+<p>
+ Optionally specifies a directory to apply as a prefix to all relative
+ file paths in the script file.
+ </p>
+<p>
+ You may wish to do this to reduce typing of pathnames, and/or where
+ the paths can't be located relative to the script file location,
+ typically if the headers are in the Boost trunk, but the script file
+ is in Boost sandbox.
+ </p>
+<p>
+ For Boost standard library layout, <code class="literal"><auto-index-prefix>../../..</code>
+ will get you back up to the 'root' of the Boost tree, so <code class="literal">!scan-path
+ boost/mylibrary/</code> is where your headers will be, and <code class="literal">libs/mylibrary</code>
+ for other files. Without a prefix all relative paths are relative
+ to the location of the script file.
+ </p>
+</dd>
+<dt><span class="term"><auto-index-type>element-name</span></dt>
+<dd><p>
+ Specifies the name of the XML element in which to enclose an internally
+ generated indexes: defaults to <span class="emphasis"><em>section</em></span>, but
+ could equally be <span class="emphasis"><em>appendix</em></span> or <span class="emphasis"><em>chapter</em></span>
+ or some other block level element that has a formal title. The actual
+ list of available options depends upon the Quickbook document type,
+ the following table gives the available options, assuming that the
+ index is placed at the top level, and not in some sub-section or
+ other container:
+ </p></dd>
+</dl>
+</div>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Document Type
+ </p>
+ </th>
+<th>
+ <p>
+ Permitted Index Types
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ book
+ </p>
+ </td>
+<td>
+ <p>
+ appendix index article chapter reference part
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ article
+ </p>
+ </td>
+<td>
+ <p>
+ section appendix index sect1
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ chapter
+ </p>
+ </td>
+<td>
+ <p>
+ section index sect1
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ library
+ </p>
+ </td>
+<td>
+ <p>
+ The same as Chapter (section index sect1)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ part
+ </p>
+ </td>
+<td>
+ <p>
+ appendix index article chapter reference
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ appendix
+ </p>
+ </td>
+<td>
+ <p>
+ section index sect1
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ preface
+ </p>
+ </td>
+<td>
+ <p>
+ section index sect1
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ qandadiv
+ </p>
+ </td>
+<td>
+ <p>
+ N/A: an index would have to be placed within a subsection of
+ the document.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ qandaset
+ </p>
+ </td>
+<td>
+ <p>
+ N/A: an index would have to be placed within a subsection of
+ the document.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ reference
+ </p>
+ </td>
+<td>
+ <p>
+ N/A: an index would have to be placed within a subsection of
+ the document.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ set
+ </p>
+ </td>
+<td>
+ <p>
+ N/A: an index would have to be placed within a subsection of
+ the document.
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<p>
+ In large part then the choice of <code class="computeroutput"><span class="special"><</span><span class="keyword">auto</span><span class="special">-</span><span class="identifier">index</span><span class="special">-</span><span class="identifier">type</span><span class="special">></span><span class="identifier">element</span><span class="special">-</span><span class="identifier">name</span></code>
+ depends on the formatting you want to be applied to the index:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ XML Container Used for the Index
+ </p>
+ </th>
+<th>
+ <p>
+ Formatting Applied by the XSL Stylesheets
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ appendix
+ </p>
+ </td>
+<td>
+ <p>
+ Starts a new page.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ article
+ </p>
+ </td>
+<td>
+ <p>
+ Starts a new page.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ chapter
+ </p>
+ </td>
+<td>
+ <p>
+ Starts a new page.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ index
+ </p>
+ </td>
+<td>
+ <p>
+ Starts a new page only if it's contained within an article or
+ book.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ part
+ </p>
+ </td>
+<td>
+ <p>
+ Starts a new page.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ reference
+ </p>
+ </td>
+<td>
+ <p>
+ Starts a new page.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ sect1
+ </p>
+ </td>
+<td>
+ <p>
+ Starts a new page as long as it's not the first section (but
+ is controlled by the XSL parameters chunk.section.depth and/or
+ chunk.first.sections).
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ section
+ </p>
+ </td>
+<td>
+ <p>
+ Starts a new page as long as it's not the first section or nested
+ within another section (but is controlled by the XSL parameters
+ chunk.section.depth and/or chunk.first.sections).
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<p>
+ In almost all cases the default (section) is the correct choice - the exception
+ is when the index is to be placed directly inside a <span class="emphasis"><em>book</em></span>
+ or <span class="emphasis"><em>part</em></span>, in which case you should probably use the
+ same XML container for the index as you use for whatever subdivisions are
+ in the <span class="emphasis"><em>book</em></span> or <span class="emphasis"><em>part</em></span>. In any event
+ placing a <span class="emphasis"><em>section</em></span> within a <span class="emphasis"><em>book</em></span>
+ or <span class="emphasis"><em>part</em></span> will result in invalid XML.
+ </p>
+<p>
+ Finally, if you are using Quickbook to generate the documentation, then
+ you may wish to add:
+ </p>
+<pre class="programlisting"><include>$boost-root/tools/auto_index/include</pre>
+<p>
+ to your projects requirements (replacing $boost-root with the path to the
+ root of the Boost tree), so that the file <a class="link" href="../../qbk.html" title="Quickbook Support">auto_index_helpers.qbk</a>
+ can be included in your quickbook source with simply a:
+ </p>
+<pre class="programlisting">[include auto_index_helpers.qbk]</pre>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../configure.html"><img src="../../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../configure.html"><img src="../../../images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../images/home.png" alt="Home"></a><a accesskey="n" href="optional.html"><img src="../../../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/tools/auto_index/doc/html/boost_autoindex/tut/entries.html
==============================================================================
--- (empty file)
+++ sandbox/tools/auto_index/doc/html/boost_autoindex/tut/entries.html 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
@@ -0,0 +1,55 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Step 5: Add Manual Index Entries to Docbook XML - Optional</title>
+<link rel="stylesheet" href="../../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../../index.html" title="Boost.AutoIndex">
+<link rel="up" href="../tut.html" title="Getting Started and Tutorial">
+<link rel="prev" href="script.html" title="Step 4: Create the .idx script file - to control what to terms to index">
+<link rel="next" href="pis.html" title="Step 6: Using XML processing instructions to control what gets indexed.">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="script.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="pis.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_autoindex.tut.entries"></a><a class="link" href="entries.html" title="Step 5: Add Manual Index Entries to Docbook XML - Optional">Step 5: Add Manual Index
+ Entries to Docbook XML - Optional</a>
+</h3></div></div></div>
+<p>
+ If you add manual <code class="computeroutput"><span class="special"><</span><span class="identifier">indexentry</span><span class="special">></span></code> markup to your Docbook XML then these
+ will be passed through unchanged. Please note however, that if you are using
+ Boost.AutoIndex's internal index generation then it only recognises <code class="computeroutput"><span class="special"><</span><span class="identifier">primary</span><span class="special">></span></code>, <code class="computeroutput"><span class="special"><</span><span class="identifier">secondary</span><span class="special">></span></code>
+ and <code class="computeroutput"><span class="special"><</span><span class="identifier">tertiary</span><span class="special">></span></code> elements within the <code class="computeroutput"><span class="special"><</span><span class="identifier">indexterm</span><span class="special">></span></code>.
+ <code class="computeroutput"><span class="special"><</span><span class="identifier">see</span><span class="special">></span></code> and <code class="computeroutput"><span class="special"><</span><span class="identifier">seealso</span><span class="special">></span></code>
+ elements are not currently recognised and Boost.AutoIndex will emit a warning
+ if these are used.
+ </p>
+<p>
+ Likewise none of the attributes which can be applied to these elements are
+ used when Boost.AutoIndex generates the index itself, with the exception
+ of the <code class="computeroutput"><span class="special"><</span><span class="identifier">type</span><span class="special">></span></code> attribute.
+ </p>
+<p>
+ For Quickbook users, there are some templates in <a class="link" href="../qbk.html" title="Quickbook Support">auto_index_helpers.qbk</a>
+ that assist in adding manual entries without having to escape to Docbook.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="script.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="pis.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/tools/auto_index/doc/html/boost_autoindex/tut/pis.html
==============================================================================
--- (empty file)
+++ sandbox/tools/auto_index/doc/html/boost_autoindex/tut/pis.html 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
@@ -0,0 +1,125 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Step 6: Using XML processing instructions to control what gets indexed.</title>
+<link rel="stylesheet" href="../../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../../index.html" title="Boost.AutoIndex">
+<link rel="up" href="../tut.html" title="Getting Started and Tutorial">
+<link rel="prev" href="entries.html" title="Step 5: Add Manual Index Entries to Docbook XML - Optional">
+<link rel="next" href="build_docs.html" title="Step 7: Build the Docs">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="entries.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="build_docs.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_autoindex.tut.pis"></a><a class="link" href="pis.html" title="Step 6: Using XML processing instructions to control what gets indexed.">Step 6: Using XML processing
+ instructions to control what gets indexed.</a>
+</h3></div></div></div>
+<p>
+ Sometimes when you need to exclude certain sections of text from indexing,
+ then you can achieve this with the following XML processing instructions:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Instruction
+ </p>
+ </th>
+<th>
+ <p>
+ Effect
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special"><?</span><span class="identifier">BoostAutoIndex</span>
+ <span class="identifier">IgnoreSection</span><span class="special">?></span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ Causes the whole of the current section to be excluded from indexing.
+ By "section" we mean either a true "section"
+ or any sibling XML element: "dedication", "toc",
+ "lot", "glossary", "bibliography",
+ "preface", "chapter", "reference",
+ "part", "article", "appendix", "index",
+ "setindex", "colophon", "sect1",
+ "refentry", "simplesect", "section"
+ or "partintro".
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special"><?</span><span class="identifier">BoostAutoIndex</span>
+ <span class="identifier">IgnoreBlock</span><span class="special">?></span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ Causes the whole of the current text block to be excluded from
+ indexing. A text block may be any of the section/chapter elements
+ listed above, or a paragraph, code listing, table etc. The complete
+ list is: "calloutlist", "glosslist", "bibliolist",
+ "itemizedlist", "orderedlist", "segmentedlist",
+ "simplelist", "variablelist", "caution",
+ "important", "note", "tip", "warning",
+ "literallayout", "programlisting", "programlistingco",
+ "screen", "screenco", "screenshot",
+ "synopsis", "cmdsynopsis", "funcsynopsis",
+ "classsynopsis", "fieldsynopsis", "constructorsynopsis",
+ "destructorsynopsis", "methodsynopsis", "formalpara",
+ "para", "simpara", "address", "blockquote",
+ "graphic", "graphicco", "mediaobject",
+ "mediaobjectco", "informalequation", "informalexample",
+ "informalfigure", "informaltable", "equation",
+ "example", "figure", "table", "msgset",
+ "procedure", "sidebar", "qandaset",
+ "task", "productionset", "constraintdef",
+ "anchor", "bridgehead", "remark",
+ "highlights", "abstract", "authorblurb"
+ or "epigraph".
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<p>
+ For Quickbook users the file <a class="link" href="../qbk.html" title="Quickbook Support">auto_index_helpers.qbk</a>
+ contains a helper template that assists in inserting these processing instructions,
+ for example:
+ </p>
+<pre class="programlisting">[AutoIndex IgnoreSection]</pre>
+<p>
+ Will cause that section to not be indexed.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="entries.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="build_docs.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/tools/auto_index/doc/html/boost_autoindex/tut/refine.html
==============================================================================
--- (empty file)
+++ sandbox/tools/auto_index/doc/html/boost_autoindex/tut/refine.html 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
@@ -0,0 +1,92 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Step 8: Iterate - to refine your index</title>
+<link rel="stylesheet" href="../../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../../index.html" title="Boost.AutoIndex">
+<link rel="up" href="../tut.html" title="Getting Started and Tutorial">
+<link rel="prev" href="build_docs.html" title="Step 7: Build the Docs">
+<link rel="next" href="../script_ref.html" title="Script File (.idx) Reference">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="build_docs.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../script_ref.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_autoindex.tut.refine"></a><a class="link" href="refine.html" title="Step 8: Iterate - to refine your index">Step 8: Iterate - to refine
+ your index</a>
+</h3></div></div></div>
+<p>
+ Creating a good index is an iterative process, often the first step is just
+ to add a header scanning rule to the script file and then generate the documentation
+ and see:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ What's missing.
+ </li>
+<li>
+ What's been included that shouldn't be.
+ </li>
+<li>
+ What's been included under a poor name.
+ </li>
+</ul></div>
+<p>
+ Further rules can then be added to the script to handle these cases and the
+ next iteration examined, and so on.
+ </p>
+<div class="tip"><table border="0" summary="Tip">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../images/tip.png"></td>
+<th align="left">Tip</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ If you don't understand why a particular term is (or is not) present in
+ the index, try adding a <span class="emphasis"><em>!debug regular-expression</em></span>
+ directive to the <a class="link" href="../script_ref.html" title="Script File (.idx) Reference">script file</a>.
+ </p></td></tr>
+</table></div>
+<a name="boost_autoindex.tut.refine.restricting_which_sections_are_indexed_for_a_particular_term"></a><h5>
+<a name="boost_autoindex.tut.refine.restricting_which_sections_are_indexed_for_a_particular_term-heading"></a>
+ <a class="link" href="refine.html#boost_autoindex.tut.refine.restricting_which_sections_are_indexed_for_a_particular_term">Restricting
+ which Sections are indexed for a particular term</a>
+ </h5>
+<p>
+ You can restrict which sections are indexed for a particular term. So assuming
+ that the docbook document has the usual hierarchical names for section ID's
+ (as Quickbook generates, for example), you can easily place a constraint
+ on which sections are examined for a particular term.
+ </p>
+<p>
+ For example, if you want to index occurrences of Lord Kelvin's name, but
+ only in the introduction section, you might then add:
+ </p>
+<pre class="programlisting"><span class="identifier">Kelvin</span> <span class="string">""</span> <span class="string">".*introduction.*"</span>
+</pre>
+<p>
+ to the script file, assuming that the section ID of the intro is "some_library_or_chapter_name.introduction".
+ </p>
+<p>
+ This would avoid an index entry every time 'Kelvin' is found, something the
+ user is unlikely to find helpful.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="build_docs.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../script_ref.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/tools/auto_index/doc/html/boost_autoindex/tut/script.html
==============================================================================
--- (empty file)
+++ sandbox/tools/auto_index/doc/html/boost_autoindex/tut/script.html 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
@@ -0,0 +1,154 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Step 4: Create the .idx script file - to control what to terms to index</title>
+<link rel="stylesheet" href="../../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../../index.html" title="Boost.AutoIndex">
+<link rel="up" href="../tut.html" title="Getting Started and Tutorial">
+<link rel="prev" href="add_indexes.html" title="Step 3: Add indexes to your documentation">
+<link rel="next" href="entries.html" title="Step 5: Add Manual Index Entries to Docbook XML - Optional">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="add_indexes.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="entries.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<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
+ file - to control what to terms to index</a>
+</h3></div></div></div>
+<p>
+ Boost.AutoIndex works by reading a script file that tells it what terms to
+ index.
+ </p>
+<p>
+ If your document contains largely text, and only a small amount of simple
+ C++, and/or if you are using Doxygen to provide a C++ Reference section (that
+ lists the C++ elements), and/or if you are relying on the indexing provided
+ from a Standalone Doxygen Index, you may decide that a index is not needed
+ and that you may only want the text part indexed.
+ </p>
+<p>
+ But if you want C++ classes functions, typedefs and/or macros AutoIndexed,
+ optionally, the script file also tells which other C++ files to scan.
+ </p>
+<p>
+ At its simplest, it will scan one or more headers for terms that should be
+ indexed in the documentation. So for example to scan "myheader.hpp"
+ the script file would just contain:
+ </p>
+<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>
+<span class="special">!</span><span class="identifier">scan</span> <span class="identifier">mydetailsheader</span><span class="special">.</span><span class="identifier">hpp</span>
+</pre>
+<p>
+ Or, more likely in practice, so we can recursively scan through directories
+ looking for all the files to scan whose <span class="bold"><strong>name matches
+ a particular regular expression</strong></span>:
+ </p>
+<pre class="programlisting">!scan-path "boost/mylibrary" ".*.hpp" true </pre>
+<p>
+ Each argument is whitespace separated and can be optionally enclosed in "double
+ quotes" (recommended).
+ </p>
+<p>
+ The final <span class="emphasis"><em>true</em></span> argument indicates that subdirectories
+ 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
+ in addition to that directory.
+ </p>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ The second <span class="emphasis"><em>file-name-regex</em></span> argument is a regular expression
+ and not a filename GLOB!
+ </p></td></tr>
+</table></div>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ The scan-path is modified by any setting of <auto-index-prefix>.
+ The examples here assume that this is <code class="literal"><auto-index-prefix>../../..</code>
+ 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,
+ <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
+ 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.
+ </p></td></tr>
+</table></div>
+<p>
+ 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>.
+ </p>
+<pre class="programlisting"># All example source files, assuming no sub-folders.
+!scan-path "libs/mylibrary/example" ".*\.cpp"
+</pre>
+<p>
+ Often the <span class="emphasis"><em>scan</em></span> or <span class="emphasis"><em>scan-path</em></span> rules
+ will bring in too many terms to search for, so we need to be able to exclude
+ terms as well:
+ </p>
+<pre class="programlisting"><span class="special">!</span><span class="identifier">exclude</span> <span class="identifier">type</span>
+</pre>
+<p>
+ Which excludes the term "type" from being indexed.
+ </p>
+<p>
+ We can also add terms manually:
+ </p>
+<pre class="programlisting"><span class="identifier">foobar</span>
+</pre>
+<p>
+ will index occurrences of "foobar" and:
+ </p>
+<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>
+<p>
+ will index any whole word containing either "foo" or "bar"
+ within it, this is useful when you want to index a lot of similar or related
+ words under one entry, for example:
+ </p>
+<pre class="programlisting"><span class="identifier">reflex</span>
+</pre>
+<p>
+ Will only index occurrences of "reflex" as a whole word, but:
+ </p>
+<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>
+<p>
+ will index occurrences of "reflex", "reflexing" and "reflexed"
+ all under the same entry <span class="emphasis"><em>reflex</em></span>. You will very often
+ need to use this to deal with plurals and other variants.
+ </p>
+<p>
+ This inclusion rule can also restrict the term to certain sections, and add
+ an index category that the term should belong to (so it only appears in certain
+ indexes).
+ </p>
+<p>
+ Finally the script can add rewrite rules, that rename section names that
+ are automatically used as index entries. For example we might want to remove
+ leading "A" or "The" prefixes from section titles when
+ Boost.AutoIndex uses them as an index entry:
+ </p>
+<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>
+</pre>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="add_indexes.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="entries.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/tools/auto_index/doc/html/boost_autoindex/workflow.html
==============================================================================
--- (empty file)
+++ sandbox/tools/auto_index/doc/html/boost_autoindex/workflow.html 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
@@ -0,0 +1,84 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Understanding The Boost.AutoIndex Workflow</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../index.html" title="Boost.AutoIndex">
+<link rel="up" href="../index.html" title="Boost.AutoIndex">
+<link rel="prev" href="script_ref.html" title="Script File (.idx) Reference">
+<link rel="next" href="xml.html" title="XML Handling">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="script_ref.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="xml.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_autoindex.workflow"></a><a class="link" href="workflow.html" title="Understanding The Boost.AutoIndex Workflow">Understanding The Boost.AutoIndex
+ Workflow</a>
+</h2></div></div></div>
+<div class="orderedlist"><ol type="1">
+<li>
+ Load the script file (usually index.idx) and process it one line at a time,
+ producing one or more index term per (non-comment) line.
+ </li>
+<li>
+ Reading all lines builds a list of <span class="emphasis"><em>terms to index</em></span>.
+ Some of those may be terms defined (by you) directly in the script file,
+ others may be terms found by scanning C++ header and source files that
+ were specified by the <span class="emphasis"><em>!scan-path</em></span> directive.
+ </li>
+<li>
+ Once the complete list of <span class="emphasis"><em>terms to index</em></span> is complete,
+ it loads the Docbook XML file. (If this comes from Quickbook/Doxygen/Boostbook/Docbook
+ then this is the complete documentation after conversion to Docbook format).
+ </li>
+<li>
+ Boost.AutoIndex builds an internal <a href="http://en.wikipedia.org/wiki/Document_Object_Model" target="_top">Document
+ Object Model (DOM)</a> of the Docbook XML. This internal representation
+ then gets scanned for occurrences of the <span class="emphasis"><em>terms to index</em></span>.
+ This scanning works at the XML paragraph level (or equivalent sibling such
+ as a table or code block) - so all the XML encoding within a paragraph
+ gets flattened to plain text.<br> This flattening means the regular expressions
+ used to search for <span class="emphasis"><em>terms to index</em></span> can find anything
+ that is completely contained within a paragraph (or code block etc).
+ </li>
+<li>
+ For each term found then an <span class="emphasis"><em>indexterm</em></span> Docbook element
+ is inserted into the <a href="http://en.wikipedia.org/wiki/Document_Object_Model" target="_top">Document
+ Object Model (DOM)</a> (provided internal index generation is off),
+ </li>
+<li>
+ Also the Boost.AutoIndex's internal index representation gets updated.
+ </li>
+<li>
+ Once the whole XML document has been indexed, then, if Boost.AutoIndex
+ has been instructed to generate the index itself, it creates the necessary
+ XML and inserts this into the <a href="http://en.wikipedia.org/wiki/Document_Object_Model" target="_top">Document
+ Object Model (DOM)</a>.
+ </li>
+<li>
+ Finally the whole <a href="http://en.wikipedia.org/wiki/Document_Object_Model" target="_top">Document
+ Object Model (DOM)</a> is written out as a new Docbook XML file, and
+ normal processing of this continues via the XSL stylesheets (with xsltproc)
+ to actually build the final human-readable docs.
+ </li>
+</ol></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="script_ref.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="xml.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/tools/auto_index/doc/html/boost_autoindex/xml.html
==============================================================================
--- (empty file)
+++ sandbox/tools/auto_index/doc/html/boost_autoindex/xml.html 2011-06-20 11:36:09 EDT (Mon, 20 Jun 2011)
@@ -0,0 +1,58 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>XML Handling</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../index.html" title="Boost.AutoIndex">
+<link rel="up" href="../index.html" title="Boost.AutoIndex">
+<link rel="prev" href="workflow.html" title="Understanding The Boost.AutoIndex Workflow">
+<link rel="next" href="qbk.html" title="Quickbook Support">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="workflow.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="qbk.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_autoindex.xml"></a><a class="link" href="xml.html" title="XML Handling">XML Handling</a>
+</h2></div></div></div>
+<p>
+ Boost.AutoIndex is rather simplistic in its handling of XML:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ When indexing a document, all block content at the paragraph level gets
+ collapsed into a single string for matching against the regular expressions
+ representing each index term. In other words, for the most part, you can
+ assume that you're indexing plain text when writing regular expressions.
+ </li>
+<li>
+ Named XML entities for &, ", ', < or > are converted to
+ their corresponding characters before indexing a section of text. However,
+ decimal or hex escape sequences are not currently converted.
+ </li>
+<li>
+ Index terms are assumed to be plain text (whether they originate from the
+ script file or from scanning source files) and the characters &, ",
+ < and > will be escaped to &amp; &quot; &lt; and &gt;
+ respectively.
+ </li>
+</ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="workflow.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="qbk.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk