Update docs, add build Jamfile.

[SVN r49860]
This commit is contained in:
John Maddock 2008-11-21 18:21:43 +00:00
parent 80dd8e2df7
commit 8336f4d099
7 changed files with 410 additions and 15 deletions

11
build/Jamfile.v2 Normal file
View File

@ -0,0 +1,11 @@
import quickbook ;
exe auto_index : ../src/auto_index.cpp ../src/tiny_xml.cpp /boost/regex /boost/filesystem
: <define>BOOST_ALL_NO_LIB=1 <link>static
;
install dist : auto_index ;

View File

@ -161,9 +161,20 @@ We can also add terms manually:
will index occurances of "foobar" and:
foo bar
foobar \<\w*(foo|bar)\w*\>
will index occurances of "foo" under the name "bar".
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:
reflex
Will only index occurances of "reflex" as a whole word, but:
reflex \<reflex\w*\>
will index occurances of "reflex", reflexing" and
"reflexed" all under the same entry ['reflex].
This inclusion rule can also restict the term to
certain sections, and add an index category that
@ -194,10 +205,124 @@ and the next iteration examined, and so on.
[section:script_ref Script File Reference]
The following elements can occur in a script:
[h4 Simple Inclusions]
term [regular-expression1 [regular-expression2 [category]]]
[variablelist
[[term][The term to index: this 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 term occurs in.]]
[[regular-expression1][An optional regular expression: each occurance
of the regular expression in the text of the document will result
in one index term being emitted.
If the regular expression is omitted or is "", then the ['term] itself
will be used as the search text - and only occurance of whole words matching
['term] will be indexed.]]
[[regular-expression2][A constraint that specifies which sections are
indexed for ['term]: only if the ID of the section matches
['regular-expression2] exactly will that section be indexed for occurances
of ['term].
For example:
`myclass "" "mylib.examples.*"`
Will index occurances of "myclass" as a whole word only in sections
whose ID begins "mylib.examples", while:
`myclass "" "(?!mylib.introduction.*).*"`
will index occurances of "myclass" in any section, except those whose
ID's begin "mylib.introduction".]]
[[category][Optionally an index category to place occurances of
['term] in. If you have multiple indexes then this is the name
assigned to the indexes "type" attribute.
]]
]
[h4 Source File Scanning]
!scan source-file-name
Scans the C\/C++ source file ['source-file-name] for definitions of
['function]'s, ['class]'s, ['macro]'s or ['typedef]'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.
[h4 Directory and Source File Scanning]
!scan-path directory-name file-name-regex [recurse]
[variablelist
[[directory-name][The directory to scan: this should be a path relative
to the script file and should use all forward slashes in it's file name.]]
[[file-name-regex][A regular expression: any file in the directory whose name
matches the regular expression will be scanned for terms to index.]]
[[recurse][An optional boolian value - either "true" or "false" - that
indicates whether to recurse into subdirectories.]]
]
[h4 Excluding Terms]
!exclude term-list
Excludes all the terms in whitespace separated ['term-list] from being indexed.
This should be placed /after/ any ['!scan] or ['!scan-path] rules which may
result in the terms becoming included.
[h4 Rewriting Section Names]
!rewrite-id regular-expression new-name
[variablelist
[[regular-expression][A regular expression: all section ID's that match
the expression exactly will have index entries ['new-name] instead of
their title(s).]]
[[new-name][The name that the section will appear under in the index.]]
]
!rewrite-name regular-expression format-text
[variablelist
[[regular-expression][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
['format-text].]]
[[format-text][The Perl-style format string used to reformat the title.]]
]
[endsect]
[section:comm_ref Command Line Reference]
The following command line options are supported by auto_index:
[variablelist
[[in=infilename][Specifies the name of the XML input file to be indexed.]]
[[out=outfilename][Specifies the name of the new XML file to create.]]
[[scan=source-filename][Specifies that ['source-filename] should be scanned
for terms to index.]]
[[script=script-filename][Specifies the name of the script file to process.]]
[[--no-duplicates][If a term occurs more than once in the same section, then
include only one index entry.]]
[[--internal-index][Specifies that auto_index should generate the actual
indexes rather than inserting `<indexterm>`'s and leaving index generation
to the XSL stylesheets.]]
]
[endsect]

View File

@ -21,9 +21,47 @@
<div class="spirit-nav">
<a accesskey="p" href="script_ref.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a>
</div>
<div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both">
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="autoindex.comm_ref"></a><a class="link" href="comm_ref.html" title="Command Line Reference"> Command Line Reference</a>
</h2></div></div></div></div>
</h2></div></div></div>
<p>
The following command line options are supported by auto_index:
</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 auto_index should generate the actual indexes rather than
inserting <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">indexterm</span><span class="special">&gt;</span></code>'s and leaving index generation to the
XSL stylesheets.
</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 John Maddock<p>

View File

@ -22,9 +22,170 @@
<div class="spirit-nav">
<a accesskey="p" href="tut.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="comm_ref.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
</div>
<div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both">
<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>
</h2></div></div></div></div>
</h2></div></div></div>
<p>
The following elements can occur in a script:
</p>
<a name="autoindex.script_ref.simple_inclusions"></a><h5>
<a name="id527549"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.simple_inclusions">Simple Inclusions</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>
The term to index: this 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
term occurs in.
</p></dd>
<dt><span class="term">regular-expression1</span></dt>
<dd>
<p>
An optional regular expression: each occurance 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 or is "", then the <span class="emphasis"><em>term</em></span>
itself will be used as the search text - and only occurance of whole words
matching <span class="emphasis"><em>term</em></span> will be indexed.
</p>
</dd>
<dt><span class="term">regular-expression2</span></dt>
<dd>
<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 occurances of <span class="emphasis"><em>term</em></span>.
</p>
<p>
For example:
</p>
<p>
<code class="computeroutput"><span class="identifier">myclass</span> <span class="string">""</span>
<span class="string">"mylib.examples.*"</span></code>
</p>
<p>
Will index occurances of "myclass" as a whole word only in sections
whose ID begins "mylib.examples", while:
</p>
<p>
<code class="computeroutput"><span class="identifier">myclass</span> <span class="string">""</span>
<span class="string">"(?!mylib.introduction.*).*"</span></code>
</p>
<p>
will index occurances of "myclass" in any section, except those
whose ID's begin "mylib.introduction".
</p>
</dd>
<dt><span class="term">category</span></dt>
<dd><p>
Optionally an index category to place occurances of <span class="emphasis"><em>term</em></span>
in. If you have multiple indexes then this is the name assigned to the
indexes "type" attribute.
</p></dd>
</dl>
</div>
<a name="autoindex.script_ref.source_file_scanning"></a><h5>
<a name="id527817"></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>
</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>
<a name="autoindex.script_ref.directory_and_source_file_scanning"></a><h5>
<a name="id527916"></a>
<a class="link" href="script_ref.html#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
and should use all forward slashes in it's 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 boolian value - either "true" or "false"
- that indicates whether to recurse into subdirectories.
</p></dd>
</dl>
</div>
<a name="autoindex.script_ref.excluding_terms"></a><h5>
<a name="id528079"></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>
</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.
</p>
<a name="autoindex.script_ref.rewriting_section_names"></a><h5>
<a name="id528160"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.rewriting_section_names">Rewriting Section
Names</a>
</h5>
<pre class="programlisting"><span class="special">!</span><span class="identifier">rewrite</span><span class="special">-</span><span class="identifier">id</span> <span class="identifier">regular</span><span class="special">-</span><span class="identifier">expression</span> <span class="keyword">new</span><span class="special">-</span><span class="identifier">name</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 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>
</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 John Maddock<p>

View File

@ -27,7 +27,7 @@
<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_tool"></a><h5>
<a name="id473685"></a>
<a name="id473689"></a>
<a class="link" href="tut.html#autoindex.tut.step_1__build_the_tool">Step 1: Build the tool</a>
</h5>
<p>
@ -42,7 +42,7 @@
<pre class="programlisting"><span class="identifier">bjam</span> <span class="identifier">release</span> <span class="identifier">gcc</span>
</pre>
<a name="autoindex.tut.step_2__configure_boost_build"></a><h5>
<a name="id473793"></a>
<a name="id473797"></a>
<a class="link" href="tut.html#autoindex.tut.step_2__configure_boost_build">Step 2: Configure
Boost.Build</a>
</h5>
@ -53,7 +53,7 @@
Currently the tool can only be run manually.
</p>
<a name="autoindex.tut.step_3__add_indexes_to_your_documentation"></a><h5>
<a name="id475028"></a>
<a name="id475023"></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>
@ -93,7 +93,7 @@
<pre class="programlisting"><span class="char">''</span><span class="char">'&lt;index/&gt;'</span><span class="char">''</span>
</pre>
<a name="autoindex.tut.step_4__create_the_script_file"></a><h5>
<a name="id473476"></a>
<a name="id473477"></a>
<a class="link" href="tut.html#autoindex.tut.step_4__create_the_script_file">Step 4: Create
the script file</a>
</h5>
@ -135,10 +135,23 @@
<p>
will index occurances of "foobar" and:
</p>
<pre class="programlisting"><span class="identifier">foo</span> <span class="identifier">bar</span>
<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 occurances of "foo" under the name "bar".
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 occurances 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 occurances of "reflex", reflexing" and "reflexed"
all under the same entry <span class="emphasis"><em>reflex</em></span>.
</p>
<p>
This inclusion rule can also restict the term to certain sections, and add
@ -154,7 +167,7 @@
<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__iterate"></a><h5>
<a name="id527366"></a>
<a name="id527476"></a>
<a class="link" href="tut.html#autoindex.tut.step_5__iterate">Step 5: Iterate</a>
</h5>
<p>

View File

@ -28,7 +28,7 @@
</h3></div></div></div>
<div><p class="copyright">Copyright © 2008 John Maddock</p></div>
<div><div class="legalnotice">
<a name="id473180"></a><p>
<a name="id473182"></a><p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
@ -47,7 +47,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"><p><small>Last revised: November 21, 2008 at 13:57:27 GMT</small></p></td>
<td align="left"><p><small>Last revised: November 21, 2008 at 17:25:20 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

47
project-root.jam Normal file
View File

@ -0,0 +1,47 @@
#
# Copyright (c) 2006 João Abecasis
#
# 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)
#
##
## IMPORTANT NOTE: This file MUST NOT be copied over a boost installation
##
path-constant top : . ;
import modules ;
import path ;
local boost-root = [ modules.peek : BOOST_ROOT ] ;
local math-header-include = $(top)/../.. ;
if ! $(boost-root)
{
local boost-search-dirs = [ modules.peek : BOOST_BUILD_PATH ] ;
for local dir in $(boost-search-dirs)
{
if [ path.glob $(dir)/../../../ : boost/version.hpp ]
{
boost-root += $(dir)/../../../ ;
}
}
if $(boost-root)
{
boost-root = [ path.make $(boost-root[1]) ] ;
}
else
{
ECHO "Warning: couldn't find BOOST_ROOT in" $(boost-root) ;
}
}
use-project /boost/regex : $(boost-root)/libs/regex/build ;
use-project /boost/unit_test : $(boost-root)/libs/test/build ;
use-project /boost/filesystem : $(boost-root)/libs/filesystem/build ;