boost_mirror/auto_index
1
0
Fork 0
mirror of https://github.com/boostorg/auto_index.git synced 2025-05-09 23:24:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Version with index

Browse Source 
[SVN r68719]
This commit is contained in:
Paul A. Bristow 2011-02-08 15:30:08 +00:00
parent 827b4b71ba
commit 3cc1511631
5 changed files with 54 additions and 816 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
doc/html/autoindex/comm_ref.html
View File

@ -7,12 +7,13 @@
<link rel="home" href="../index.html" title="AutoIndex">
<link rel="up" href="../index.html" title="AutoIndex">
<link rel="prev" href="xml.html" title="XML Handling">
<link rel="next" href="index.html" title="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="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="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="index.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">
@ -64,9 +65,9 @@
<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 "section", but could equally be "appendix"
or "chapter" or some other block level element that has a formal
title.
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>
@ -81,7 +82,7 @@
</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="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="index.html"><img src="../images/next.png" alt="Next"></a>
</div>
</body>
</html>

10
doc/html/autoindex/overview.html
View File

@ -134,11 +134,11 @@
Finally, you can choose what kind of XML container wraps an internally generated
index - this defaults to <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">section</span><span class="special">&gt;...&lt;/</span><span class="identifier">section</span><span class="special">&gt;</span></code>
but you can use either command line options or Boost.Build Jamfile features,
to select an alternative wrapper - for example "appendix" or "chapter"
would be good choices, whatever fits best into the flow of the document. You
can even set the container wrapper to type "index" provided you turn
off index generation by the XSL stylesheets, for example by setting the following
build requirements in the Jamfile:
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">&lt;format&gt;html:&lt;auto-index-internal&gt;on # Use internally generated indexes.
&lt;auto-index-type&gt;index # Use &lt;index&gt;...&lt;/index&gt; as the XML wrapper.

26
doc/html/autoindex/script_ref.html
View File

@ -1,29 +1,29 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Script File Reference</title>
<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="AutoIndex">
<link rel="up" href="../index.html" title="AutoIndex">
<link rel="prev" href="tut.html" title="Getting Started and Tutorial">
<link rel="prev" href="tut/refine/debug.html" title="Why particular term is (or is not) present in the index">
<link rel="next" href="workflow.html" title="Understanding The 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.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>
<a accesskey="p" href="tut/refine/debug.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="autoindex.script_ref"></a><a class="link" href="script_ref.html" title="Script File Reference">Script File Reference</a>
<a name="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="autoindex.script_ref.comments_and_blank_lines"></a><h5>
<a name="id1002121"></a>
<a name="id871865"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.comments_and_blank_lines">Comments and
blank lines</a>
</h5>
@ -32,7 +32,7 @@
comments onto the end of a line!).
</p>
<a name="autoindex.script_ref.inclusion_of_index_terms"></a><h5>
<a name="id1002142"></a>
<a name="id871888"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.inclusion_of_index_terms">Inclusion of
Index terms</a>
</h5>
@ -207,7 +207,7 @@
</dl>
</div>
<a name="autoindex.script_ref.source_file_scanning"></a><h5>
<a name="id1003183"></a>
<a name="id872352"></a>
<a class="link" href="script_ref.html#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>
@ -236,7 +236,7 @@
</p></td></tr>
</table></div>
<a name="autoindex.script_ref.directory_and_source_file_scanning"></a><h5>
<a name="id1003261"></a>
<a name="id872429"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.directory_and_source_file_scanning">Directory
and Source File Scanning</a>
</h5>
@ -265,7 +265,7 @@
</dl>
</div>
<a name="autoindex.script_ref.excluding_terms"></a><h5>
<a name="id1003386"></a>
<a name="id872554"></a>
<a class="link" href="script_ref.html#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>
@ -278,7 +278,7 @@
of things to index.
</p>
<a name="autoindex.script_ref.rewriting_section_names"></a><h5>
<a name="id1003441"></a>
<a name="id872609"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.rewriting_section_names">Rewriting Section
Names</a>
</h5>
@ -325,7 +325,7 @@
all index entries - thus preventing lots of entries under "The" etc!
</p>
<a name="autoindex.script_ref.defining_or_changing_the_file_scanners"></a><h5>
<a name="id1003593"></a>
<a name="id872763"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.defining_or_changing_the_file_scanners">Defining
or Changing the File Scanners</a>
</h5>
@ -428,7 +428,7 @@
scanner may find in the documentation.
</p>
<a name="autoindex.script_ref.debugging_scanning"></a><h5>
<a name="id1004096"></a>
<a name="id873953"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.debugging_scanning">Debugging scanning</a>
</h5>
<p>
@ -466,7 +466,7 @@ The index type for this entry is: qi_index
</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="../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>
<a accesskey="p" href="tut/refine/debug.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>

821
doc/html/autoindex/tut.html
View File

@ -7,807 +7,44 @@
<link rel="home" href="../index.html" title="AutoIndex">
<link rel="up" href="../index.html" title="AutoIndex">
<link rel="prev" href="overview.html" title="Overview">
<link rel="next" href="script_ref.html" title="Script File Reference">
<link rel="next" href="tut/build.html" title="Step 1: Build the 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="script_ref.html"><img src="../images/next.png" alt="Next"></a>
<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="autoindex.tut"></a><a class="link" href="tut.html" title="Getting Started and Tutorial">Getting Started and Tutorial</a>
</h2></div></div></div>
<a name="autoindex.tut.step_1__build_the_autoindex_tool"></a><h5>
<a name="id992417"></a>
<a class="link" href="tut.html#autoindex.tut.step_1__build_the_autoindex_tool">Step 1: Build
the AutoIndex tool</a>
</h5>
<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>
<p>
Finally note that [=tools/auto_index/auto-index.jam] gets copied into the same
directory as the rest of the Boost.Build tools (under <code class="computeroutput"><span class="identifier">tools</span><span class="special">/</span><span class="identifier">build</span><span class="special">/</span><span class="identifier">v2</span><span class="special">/</span><span class="identifier">tools</span></code>
in your main Boost tree): this is a temporary fix that will go away if the
tool is accepted into Boost.
</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>
If you move to a new machine you will need to do this! An error message will
warn about missing <code class="computeroutput"><span class="keyword">auto</span><span class="special">-</span><span class="identifier">index</span><span class="special">.</span><span class="identifier">jam</span></code>.
</p></td></tr>
</table></div>
<a name="autoindex.tut.step_2__configure_boost_build_to_use_autoindex"></a><h5>
<a name="id992642"></a>
<a class="link" href="tut.html#autoindex.tut.step_2__configure_boost_build_to_use_autoindex">Step
2: Configure Boost.Build to use AutoIndex</a>
</h5>
<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 auto-index 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:
# &lt;auto-index&gt;on (or off) one turns on (or off) indexing:
&lt;auto-index&gt;on
# Turns on (or off) auto-index-verbose for diagnostic info.
# This is highly recommended until you have got all the many details correct!
&lt;auto-index-verbose&gt;on
# Choose the indexing method (separately for html and PDF) - see manual.
# Choose indexing method for PDFs:
&lt;format&gt;pdf:&lt;auto-index-internal&gt;off
# Choose indexing method for html:
&lt;format&gt;html:&lt;auto-index-internal&gt;on
# Set the name of the script file to use (index.idx is popular):
&lt;auto-index-script&gt;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 &lt;auto-index-prefix&gt; feature.
# The path specified by &lt;auto-index-prefix&gt; may be either relative or
# absolute, for example the following will get us up to the boost root
# directory for most Boost libraries:
&lt;auto-index-prefix&gt;../../..
# Tell Quickbook that it should enable indexing.
&lt;quickbook-define&gt;enable_index ;
;
</pre>
<p>
The available options are:
</p>
<div class="variablelist">
<p class="title"><b></b></p>
<dl>
<dt><span class="term">&lt;auto-index&gt;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">&lt;auto-index-internal&gt;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">&lt;auto-index-script&gt;filename</span></dt>
<dd><p>
Specifies the name of the script to load.
</p></dd>
<dt><span class="term">&lt;auto-index-no-duplicates&gt;off/on</span></dt>
<dd><p>
When "on" 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">&lt;auto-index-section-names&gt;off/on</span></dt>
<dd><p>
When "on" 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">&lt;auto-index-verbose&gt;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">&lt;auto-index-prefix&gt;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">&lt;auto-index-prefix&gt;../../..</code>
will get you back up to the 'root' of the Boost tree, so !scan-path
<em class="replaceable"><code>boost/mylibrary/</code></em> is where your headers will
be, and <em class="replaceable"><code>libs/mylibrary</code></em> for other files. Without
a prefix all relative paths are relative to the location of the script
file.
</p>
</dd>
<dt><span class="term">&lt;auto-index-type&gt;element-name</span></dt>
<dd><p>
Specifies the name of the XML element to enclose internally generated
indexes in: defaults to "section", but could equally be "appendix"
or "chapter" or some other block level element that has a formal
title. The actual list of available options depends upon the document
type, the following table gives the available options:
</p></dd>
</dl>
</div>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Document Type
</p>
</th>
<th>
<p>
Available 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>
library
</p>
</td>
<td>
<p>
See Chapter
</p>
</td>
</tr>
<tr>
<td>
<p>
chapter
</p>
</td>
<td>
<p>
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>
It is considerate to make the <span class="bold"><strong>use of auto-index optional</strong></span>
in Boost.Build, to allow users who do not have auto-index 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 wait while you keep rebuilding
the index!
</p>
<p>
One method of setting up optional auto-index support is to place all auto-index
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
&lt;auto-index&gt;on
&lt;auto-index-script&gt;index.idx
... other auto-index options here...
;
}
else
{
ECHO "Building the my_library docs with automatic index generation disabled. To get an auto-index, try building with --enable-index." ;
}
</pre>
<p>
To use this, 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">&gt;</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">&gt;</span> <span class="identifier">mylibrary_html_index</span><span class="special">.</span><span class="identifier">log</span>
</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 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>
<a name="autoindex.tut.step_3__add_indexes_to_your_documentation"></a><h5>
<a name="id1000965"></a>
<a class="link" href="tut.html#autoindex.tut.step_3__add_indexes_to_your_documentation">Step
3: Add indexes to your documentation</a>
</h5>
<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">&lt;</span><span class="identifier">index</span><span class="special">/&gt;</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
<span class="emphasis"><em>auto_index</em></span> in separate indexes along with a main "include
everything" index as well, one could add:
</p>
<pre class="programlisting">&lt;index type="class_name"&gt;
&lt;title&gt;Class Index&lt;/title&gt;
&lt;/index&gt;
&lt;index type="typedef_name"&gt;
&lt;title&gt;Typedef Index&lt;/title&gt;
&lt;/index&gt;
&lt;index type="function_name"&gt;
&lt;title&gt;Function Index&lt;/title&gt;
&lt;/index&gt;
&lt;index type="macro_name"&gt;
&lt;title&gt;Macro Index&lt;/title&gt;
&lt;/index&gt;
&lt;index/&gt;
</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">&lt;</span><span class="identifier">xsl</span><span class="special">:</span><span class="identifier">param</span><span class="special">&gt;</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">'''&lt;index/&gt;''' </pre>
<p>
If you are writing a Quickbook document with Doxygen reference documentation,
the position of a <code class="computeroutput"><span class="special">[</span><span class="identifier">xinclude</span>
<span class="identifier">autodoc</span><span class="special">.</span><span class="identifier">xml</span><span class="special">]</span></code> line
in the Quickbook file determines the location of the Doxygen references section.
You will almost certainly want this as well.
</p>
<pre class="programlisting">[xinclude autodoc.xml] # Using <span class="emphasis"><em>Doxygen reference documentation</em></span>.
</pre>
<p>
You can control the <span class="emphasis"><em>displayed name</em></span> of the Doxygen reference
section thus by adding to the end of the Doxygen autodoc section in your jamfile.
</p>
<pre class="programlisting">&lt;xsl:param&gt;"boost.doxygen.reftitle=Boost.mylibrary C++ Reference"
</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>
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 AutoIndex. If you're using Boostbook or quickbook though, this all happens
for you anyway, and 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 auto-index's internal index generation on
</p>
<pre class="programlisting">&lt;auto-index-internal&gt;on
</pre>
<p>
(usually recommended for HTML output, and not 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">&lt;</span><span class="identifier">section</span><span class="special">&gt;...&lt;/</span><span class="identifier">section</span><span class="special">&gt;</span></code> XML block (this replaces the original
<code class="computeroutput"><span class="special">&lt;</span><span class="identifier">index</span><span class="special">&gt;...&lt;/</span><span class="identifier">index</span><span class="special">&gt;</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">&lt;</span><span class="identifier">chapter</span><span class="special">&gt;</span></code> top level content rather than <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">section</span><span class="special">&gt;</span></code>s then it may be preferable to place the
index in a <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">chapter</span><span class="special">&gt;</span></code> or <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">appendix</span><span class="special">&gt;</span></code>
block. You can also place the index inside an <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">index</span><span class="special">&gt;</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">&lt;auto-index-type&gt;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 auto-index 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:
&lt;auto-index&gt;on
# PDFs rely on the XSL stylesheets to generate the index:
&lt;format&gt;pdf:&lt;auto-index-internal&gt;off
# HTML output uses auto-index to generate the index:
&lt;format&gt;html:&lt;auto-index-internal&gt;on
# Name of script file to use:
&lt;auto-index-script&gt;index.idx
# Set the XML wrapper for HML Indexes to "appendix":
&lt;format&gt;html:&lt;auto-index-type&gt;appendix
# Turn on multiple index support:
&lt;xsl:param&gt;index.on.type=1
</pre>
<a name="autoindex.tut.step_4__create_the_script_file____to_control_what_to_terms_to_index"></a><h5>
<a name="id1001337"></a>
<a class="link" href="tut.html#autoindex.tut.step_4__create_the_script_file____to_control_what_to_terms_to_index">Step
4: Create the script file - to control what to terms to index</a>
</h5>
<p>
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 &lt;auto-index-prefix&gt;. The
examples here assume that this is [=&lt;auto-index-prefix&gt;..<span class="emphasis"><em>..</em></span>..
</p></td></tr>
</table></div>
<p>
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>
<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">\&lt;\</span><span class="identifier">w</span><span class="special">*(</span><span class="identifier">foo</span><span class="special">|</span><span class="identifier">bar</span><span class="special">)\</span><span class="identifier">w</span><span class="special">*\&gt;</span>
</pre>
<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">\&lt;</span><span class="identifier">reflex</span><span class="special">\</span><span class="identifier">w</span><span class="special">*\&gt;</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 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>
<a name="autoindex.tut.step_5__add_manual_index_entries_to_docbook_xml___optional"></a><h5>
<a name="id1001751"></a>
<a class="link" href="tut.html#autoindex.tut.step_5__add_manual_index_entries_to_docbook_xml___optional">Step
5: Add Manual Index Entries to Docbook XML - Optional</a>
</h5>
<p>
If you add manual <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">indexentry</span><span class="special">&gt;</span></code> markup to your Docbook XML then these will
be passed through unchanged. Please note however, that if you are using auto-index's
internal index generation then it only recognises <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">primary</span><span class="special">&gt;</span></code>
and <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">secondary</span><span class="special">&gt;</span></code> elements within the <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">indexterm</span><span class="special">&gt;</span></code>.
<code class="computeroutput"><span class="special">&lt;</span><span class="identifier">tertiary</span><span class="special">&gt;</span></code>, <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">see</span><span class="special">&gt;</span></code> and
<code class="computeroutput"><span class="special">&lt;</span><span class="identifier">seealso</span><span class="special">&gt;</span></code> elements are not currently recognised and
auto-index 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 auto-index generates the index itself, with the exception of the
"type" attribute.
</p>
<a name="autoindex.tut.step_6__build_the_docs"></a><h5>
<a name="id1001872"></a>
<a class="link" href="tut.html#autoindex.tut.step_6__build_the_docs">Step 6: Build the Docs</a>
</h5>
<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">&gt;</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">&gt;</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 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, auto-index 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">&lt;auto-index-verbose&gt;on</code> and that any needed <code class="literal">!debug
regular-expression</code> directives are in your script file.
</p>
<a name="autoindex.tut.step_7__iterate___to_refine_your_index"></a><h5>
<a name="id1002000"></a>
<a class="link" href="tut.html#autoindex.tut.step_7__iterate___to_refine_your_index">Step 7:
Iterate - to refine your index</a>
</h5>
<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>
<a name="autoindex.tut.restricting_which_sections_are_indexed_for_a_particular_term"></a><h5>
<a name="id1002048"></a>
<a class="link" href="tut.html#autoindex.tut.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
hierarchical names for section IDs(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>
<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 Reference">script file</a>.
</p></td></tr>
</table></div>
<div class="toc"><dl>
<dt><span class="section"><a href="tut/build.html">Step 1: Build the AutoIndex tool</a></span></dt>
<dt><span class="section"><a href="tut/configure.html">Step 2: Configure Boost.Build
jamfile to use 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 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/build_docs.html">Step 6: Build the Docs</a></span></dt>
<dt><span class="section"><a href="tut/refine.html">Step 7: Iterate - to refine your
index</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="tut/refine/restrict.html">Restricting which Sections
are indexed for a particular term</a></span></dt>
<dt><span class="section"><a href="tut/refine/debug.html">Why particular term is
(or is not) present in the index</a></span></dt>
</dl></dd>
</dl></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
@ -819,7 +56,7 @@ boostbook standalone
</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="script_ref.html"><img src="../images/next.png" alt="Next"></a>
<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>

2
doc/html/autoindex/xml.html
View File

@ -20,7 +20,7 @@
<a name="autoindex.xml"></a><a class="link" href="xml.html" title="XML Handling">XML Handling</a>
</h2></div></div></div>
<p>
Auto-index is rather simplistic in its handling of XML:
AutoIndex is rather simplistic in its handling of XML:
</p>
<div class="itemizedlist"><ul type="disc">
<li>