Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r68534 - in sandbox/tools/auto_index/doc/html: . autoindex
From: pbristow_at_[hidden]
Date: 2011-01-28 10:07:55

Next message: christophe.j.henry_at_[hidden]: "[Boost-commit] svn:boost r68535 - trunk/boost/msm/back"
Previous message: pbristow_at_[hidden]: "[Boost-commit] svn:boost r68533 - sandbox/tools/auto_index/doc"

Author: pbristow
Date: 2011-01-28 10:07:52 EST (Fri, 28 Jan 2011)
New Revision: 68534
URL: http://svn.boost.org/trac/boost/changeset/68534

Log:
Some tips added and some editorial corrections.
Merged with John Maddock's additions 27 Jan, hopefully without causing trouble. See also pdf version.
Text files modified:
   sandbox/tools/auto_index/doc/html/autoindex/comm_ref.html | 4
   sandbox/tools/auto_index/doc/html/autoindex/overview.html | 24 ++
   sandbox/tools/auto_index/doc/html/autoindex/script_ref.html | 36 ++-
   sandbox/tools/auto_index/doc/html/autoindex/tut.html | 375 ++++++++++++++++++++++++++++++---------
   sandbox/tools/auto_index/doc/html/autoindex/xml.html | 4
   sandbox/tools/auto_index/doc/html/index.html | 6
   6 files changed, 328 insertions(+), 121 deletions(-)

Modified: sandbox/tools/auto_index/doc/html/autoindex/comm_ref.html
==============================================================================
--- sandbox/tools/auto_index/doc/html/autoindex/comm_ref.html (original)
+++ sandbox/tools/auto_index/doc/html/autoindex/comm_ref.html 2011-01-28 10:07:52 EST (Fri, 28 Jan 2011)
@@ -49,7 +49,7 @@
<dt>--internal-index</dt>
<dd>
 Specifies that auto_index should generate the actual indexes rather than
- inserting <code class="computeroutput"><indexterm></code>'s and leaving index generation to
+ inserting <code class="computeroutput"><indexterm></code>s and leaving index generation to
 the XSL stylesheets.
 </dd>
<dt>--no-section-names</dt>
@@ -73,7 +73,7 @@
</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
+<td align="right"><div class="copyright-footer">Copyright © 2008 , 2011 John Maddock
 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)

Modified: sandbox/tools/auto_index/doc/html/autoindex/overview.html
==============================================================================
--- sandbox/tools/auto_index/doc/html/autoindex/overview.html (original)
+++ sandbox/tools/auto_index/doc/html/autoindex/overview.html 2011-01-28 10:07:52 EST (Fri, 28 Jan 2011)
@@ -29,10 +29,24 @@
 for each occurrence of each term to be indexed.
 

- Instead AutoIndex will scan one or more C/C++ header files and extract all
- the function, class, macro
- and typedef names that are defined by those headers, and
- then insert the <code class="computeroutput"><indexterm></code>'s into the XML document for you.
+ Instead AutoIndex will automatically scan one or more C/C++ header files and
+ extract all the function, class,
+ macro and typedef names that are
+ defined by those headers, and then insert the <code class="computeroutput"><indexterm></code>s
+ into the XML document for you.
+ 
+
+ AutoIndex can also scan text files, usually Quickbook
+ files, but in this case you need to manually provide a simple list of index
+ terms (in a script file, optionally using regular expressions). This may allow
+ the user to find references to more descriptive items that may not occur in
+ the C++ classes and functions header files.
+ 
+
+ Providing a manual list of terms in the text 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.
 

 AutoIndex creates index entries as follows - for each occurrence of each search
@@ -116,7 +130,7 @@
</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
+<td align="right"><div class="copyright-footer">Copyright © 2008 , 2011 John Maddock
 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)

Modified: sandbox/tools/auto_index/doc/html/autoindex/script_ref.html
==============================================================================
--- sandbox/tools/auto_index/doc/html/autoindex/script_ref.html (original)
+++ sandbox/tools/auto_index/doc/html/autoindex/script_ref.html 2011-01-28 10:07:52 EST (Fri, 28 Jan 2011)
@@ -23,16 +23,16 @@
 The following elements can occur in a script:
 
<a name="autoindex.script_ref.comments_and_blank_lines"></a><h5>
-<a name="id1016394"></a>
+<a name="id869246"></a>
 <a class="link" href="script_ref.html#autoindex.script_ref.comments_and_blank_lines">Comments and
 blank lines</a>
 </h5>

- Blank lines consisting of only whitespace are ignored, so are lines that start
- with a '#'.
+ Blank lines consisting of only whitespace are ignored, so are lines that start with a '#'. (But, of course, you can't append
+ # comments onto the end of a line!).
 
<a name="autoindex.script_ref.simple_inclusions"></a><h5>
-<a name="id1016410"></a>
+<a name="id869267"></a>
 <a class="link" href="script_ref.html#autoindex.script_ref.simple_inclusions">Simple Inclusions</a>
 </h5>
<pre class="programlisting">term [regular-expression1 [regular-expression2 [category]]]
@@ -99,15 +99,15 @@
</dl>
</div>
<a name="autoindex.script_ref.source_file_scanning"></a><h5>
-<a name="id1016619"></a>
+<a name="id870626"></a>
 <a class="link" href="script_ref.html#autoindex.script_ref.source_file_scanning">Source File Scanning</a>
 </h5>
<pre class="programlisting">!scan source-file-name
</pre>

 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.
+ of functions, classs, macros
+ or typedefs 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
@@ -128,7 +128,7 @@
 </td></tr>
</table></div>
<a name="autoindex.script_ref.directory_and_source_file_scanning"></a><h5>
-<a name="id1016697"></a>
+<a name="id870704"></a>
 <a class="link" href="script_ref.html#autoindex.script_ref.directory_and_source_file_scanning">Directory
 and Source File Scanning</a>
 </h5>
@@ -141,7 +141,7 @@
<dd>
 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 it's file name.
+ line) and should use all forward slashes in its file name.
 </dd>
<dt>file-name-regex</dt>
<dd>
@@ -157,7 +157,7 @@
</dl>
</div>
<a name="autoindex.script_ref.excluding_terms"></a><h5>
-<a name="id1016822"></a>
+<a name="id870828"></a>
 <a class="link" href="script_ref.html#autoindex.script_ref.excluding_terms">Excluding Terms</a>
 </h5>
<pre class="programlisting">!exclude term-list
@@ -170,7 +170,7 @@
 of things to index.
 
<a name="autoindex.script_ref.rewriting_section_names"></a><h5>
-<a name="id1016877"></a>
+<a name="id870884"></a>
 <a class="link" href="script_ref.html#autoindex.script_ref.rewriting_section_names">Rewriting Section
 Names</a>
 </h5>
@@ -217,7 +217,7 @@
 all index entries - thus preventing lots of entries under "The" etc!
 
<a name="autoindex.script_ref.defining_or_changing_the_file_scanners"></a><h5>
-<a name="id1017030"></a>
+<a name="id871036"></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>
@@ -319,9 +319,9 @@
 Will look for any occurrence of whatever class names the
 scanner may find in the documentation.
 
-<a name="autoindex.script_ref.debugging"></a><h5>
-<a name="id1017532"></a>
- <a class="link" href="script_ref.html#autoindex.script_ref.debugging">Debugging</a>
+<a name="autoindex.script_ref.debugging_scanning"></a><h5>
+<a name="id871539"></a>
+ <a class="link" href="script_ref.html#autoindex.script_ref.debugging_scanning">Debugging scanning</a>
 </h5>

 If you see a term in the index, and you don't understand why it's there, add
@@ -343,10 +343,14 @@
The section constraint is: .qi.reference.parser_concepts.
The index type for this entry is: qi_index
</pre>
+
+ 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.
+ 
</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
+<td align="right"><div class="copyright-footer">Copyright © 2008 , 2011 John Maddock
 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)

Modified: sandbox/tools/auto_index/doc/html/autoindex/tut.html
==============================================================================
--- sandbox/tools/auto_index/doc/html/autoindex/tut.html (original)
+++ sandbox/tools/auto_index/doc/html/autoindex/tut.html 2011-01-28 10:07:52 EST (Fri, 28 Jan 2011)
@@ -19,9 +19,10 @@
<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_tool"></a><h5>
-<a name="id1010871"></a>
- <a class="link" href="tut.html#autoindex.tut.step_1__build_the_tool">Step 1: Build the tool</a>
+<a name="autoindex.tut.step_1__build_the_autoindex_tool"></a><h5>
+<a name="id867220"></a>
+ <a class="link" href="tut.html#autoindex.tut.step_1__build_the_autoindex_tool">Step 1: Build
+ the AutoIndex tool</a>
 </h5>

 cd into <code class="computeroutput">tools/auto_index/build</code> and invoke bjam as:
@@ -35,9 +36,10 @@
<pre class="programlisting">bjam release gcc
</pre>

- Now open up your user-config.jam file and at the end add the line:
+ Now open up your <code class="computeroutput">user-config.jam</code>
+ file and at the end of the file add the line:
 
-<pre class="programlisting">using auto-index : full-path-of-executable ;
+<pre class="programlisting">using auto-index : full-path-of-executable-auto-index.exe ;
</pre>
<div class="note"><table border="0" summary="Note">
<tr>
@@ -46,11 +48,11 @@
</tr>
<tr><td align="left" valign="top">

- This declaration must go towards the end of user-config.jam, or in any case
- after the Boostbook initialisation.
+ This declaration must go towards the end of <code class="computeroutput">user-config.jam</code>, or
+ in any case after the Boostbook initialisation.
 

- Also note that Windows users must use forward slashes in the paths in user-config.jam
+ Also note that Windows users must use forward slashes in the paths in <code class="computeroutput">user-config.jam</code>
 
</td></tr>
</table></div>
@@ -61,10 +63,20 @@
 your main Boost tree): this is a temporary fix that will go away if the tool
 is accepted into Boost.
 
-<a name="autoindex.tut.step_2__configure_boost_build"></a><h5>
-<a name="id1011036"></a>
- <a class="link" href="tut.html#autoindex.tut.step_2__configure_boost_build">Step 2: Configure
- Boost.Build</a>
+<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">
+ If you move to a new machine you will need to do this! An error message will
+ warn about missing <code class="computeroutput">auto-index.jam</code>.
+ </td></tr>
+</table></div>
+<a name="autoindex.tut.step_2__configure_boost_build_to_use_autoindex"></a><h5>
+<a name="id867482"></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>

 Assuming you have a Jamfile for building your documentation that looks something
@@ -72,7 +84,7 @@
 
<pre class="programlisting">boostbook standalone
 :
- type_traits
+ mylibrary
 :
 # build requirements go here:
 ;
@@ -83,22 +95,42 @@
<pre class="programlisting">using auto-index ; </pre>

 to the start of the Jamfile, and then add whatever auto-index options you want
- to the build requirements section, for example:
+ to the build requirements section, for example:
 
<pre class="programlisting">boostbook standalone
 :
- type_traits
+ mylibrary
 :
- # build requirements go here:
+ # Build requirements go here:

- # this one turns on indexing:
+ # <auto-index>on (or off) one turns on (or off) indexing:
 <auto-index>on
- # choose indexing method for pdf's:
+
+ # Turns on (or off) auto-index-verbose for diagnostic info.
+ # This is highly recommended until you have got all the many details correct!
+ # (uses /bin auto-index-verbose folders).
+ <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:
+
+ # Choose indexing method for html:
 <format>html:<auto-index-internal>on
- # set the name of the script file to use:
+
+ # Set the name of the script file to use (index.idx is popular):
 <auto-index-script>index.idx
+ # But see <auto-index-prefix> to use for the scan path to scan for script files.
+
+ # <auto-index-prefix>../../.. will get you back up to /mylibrary,
+ # so !scan-path "boost/mylibrary/" is where headers *.hpp will be.
+ # and /libs/mylibrary for other files.
+ # Without this you would need !scan-path "../../../boost/mylibrary"
+ <auto-index-prefix>../../..
+
+ # Tell Quickbook that is should enable indexing.
+ <quickbook-define>enable_index ;
+
 ;
</pre>

@@ -138,12 +170,15 @@
<dt><auto-index-verbose>off/on</dt>
<dd>
 Defaults to "off". When turned on AutoIndex prints progress
- information - generally useful only for debugging purposes.
+ information - useful for debugging purposes during setup.
 </dd>
<dt><auto-index-prefix>filename</dt>
<dd>
 Specifies a directory to apply as a prefix to all relative file paths
- in the script file.
+ in the script file. For Boost standard layout, <auto-index-prefix>../../..
+ will get you back up to /mylibrary, so !scan-path "boostmylibrary"
+ is where headers *.hpp will be and /libs/mylibrary for other files. Without
+ this you would need !scan-path "../../../boost/mylibrary"
 </dd>
<dt><auto-index-type>element-name</dt>
<dd>
@@ -312,33 +347,103 @@
</tbody>
</table></div>

- It is possible to make the use of auto-index optional in Boost.Build, to allow
- users who do not have auto-index installed to build your documentation. One
- method of setting up optional auto-index support is to place all auto-index
+ It is considerate to make the use of auto-index optional
+ in Boost.Build, to allow users who do not have auto-index installed to still
+ be able to build your documentation.
+ 
+
+ 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.
+ 
+
+ 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!
+ 
+
+ 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:
 
-<pre class="programlisting">if --enable-index in [ modules.peek : ARGV ]
-{
- using auto-index ;
- project : requirements
- <auto-index>on
- <auto-index-script>index.idx
- #... other auto-index options here...
- ;
-}
+<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...
+ ;
+ }
+ else
+ {
+ ECHO "Building the my_library docs with automatic index generation disabled. To get an auto-index, try building with --enable-index." ;
+ }
+</pre>
+
+ To use this, you need to cd to your docs folder, for example:
+ 
+<pre class="programlisting">cd \boost-sandbox\guild\mylibrary\libs\mylibrary\doc
+</pre>
+
+ and then run <code class="computeroutput">bjam</code> to build
+ the docs without index, for example:
+ 
+<pre class="programlisting">bjam -a html > mylibrary_html.log
+</pre>
+
+ or with index(es)
+ 
+<pre class="programlisting">bjam -a html --enable-index > mylibrary_html_index.log
</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">
+ 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.
+ </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">
+ 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.
+ </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">
+ If you upgrade compiler version, for example MSVC from 9 to 10, then you
+ will 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.
+ </td></tr>
+</table></div>
<a name="autoindex.tut.step_3__add_indexes_to_your_documentation"></a><h5>
-<a name="id1011645"></a>
+<a name="id868109"></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>

- To add a single index to a BoostBook/Docbook document, then add <code class="computeroutput"><index/></code> at the location where you want the index
+ To add a single "include everything" index to a Quickbook/BoostBook/Docbook
+ document, then add <code class="computeroutput"><index/></code> at the location where you want the index
 to appear. The index will be rendered as a separate section when the documentation
 is built.
 

- To add multiple indexes, then give each one a title and set it's <code class="computeroutput">type</code> attribute to specify which terms will
+ To add multiple indexes, then give each one a title and set its <code class="computeroutput">type</code> attribute to specify which terms will
 be included, for example to place the function, class,
 macro or typedef names indexed by
 auto_index in separate indexes along with a main "include
@@ -375,60 +480,82 @@
 </td></tr>
</table></div>

- In quickbook, you add the same markup but enclose it in an escape:
+ In Quickbook, you add the same markup but enclose it between two triple-tick
+ ''' escapes, thus
 
-<pre class="programlisting">'''<index/>'''
+<pre class="programlisting">'''<index/>''' </pre>
+
+ If you are writing a Quickbook document with Doxygen reference documentation,
+ the position of a <code class="computeroutput">[xinclude
+ autodoc.xml]</code> line
+ in the Quickbook file determines the location of the Doxygen references section.
+ You will almost certainly want this as well.
+ 
+<pre class="programlisting">[xinclude autodoc.xml] # Using Doxygen reference documentation.
+</pre>
+
+ You can control the displayed name of the Doxygen reference
+ section thus by adding to the end of the Doxygen autodoc section in your jamfile.
+ 
+<pre class="programlisting"><xsl:param>"boost.doxygen.reftitle=Boost.mylibrary C++ Reference"
</pre>

- If you are using auto-index's internal index generation (usually recommended
- for HTML output) then you can also decide what kind of XML wrapper the generated
- index is placed in. By default this is a <code class="computeroutput"><section>...</section></code>
- XML block (this replaces the original <code class="computeroutput"><index>...</index></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"><chapter></code>
- top level content rather than <code class="computeroutput"><section></code>'s
- then it may be preferable to place the index in a <code class="computeroutput"><chapter></code>
- or <code class="computeroutput"><appendix></code> block. You can also place the index inside
- an <code class="computeroutput"><index></code> block if you prefer, in which case the
- index does not appear in on a page of it's own, but after the TOC in the HTML
- output.
+ If you are using auto-index's internal index generation on
+ 
+<pre class="programlisting"><auto-index-internal>on
+</pre>
+
+ (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"><section>...</section></code> XML block (this replaces the original
+ <code class="computeroutput"><index>...</index></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"><chapter></code> top level content rather than <code class="computeroutput"><section></code>s then it may be preferable to place the
+ index in a <code class="computeroutput"><chapter></code> or <code class="computeroutput"><appendix></code>
+ block. You can also place the index inside an <code class="computeroutput"><index></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.
 

 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">index-type=element-name</code> command line option to auto-index itself.
- For example, to place the index in an appendix your Jamfile might look like:
+ For example, to place the index in an appendix, your Jamfile might look like:
 
<pre class="programlisting">using quickbook ;
using auto-index ;

-xml type_traits : type_traits.qbk ;
+xml mylibrary : mylibary.qbk ;
boostbook standalone
 :
- type_traits
+ mylibrary
 :
- # indexing is on:
- <auto-index>on
- # PDF's rely on the XSL stylesheets to generate the index:
- <format>pdf:<auto-index-internal>off
+ # 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>
-<a name="autoindex.tut.step_4__create_the_script_file"></a><h5>
-<a name="id1011948"></a>
- <a class="link" href="tut.html#autoindex.tut.step_4__create_the_script_file">Step 4: Create
- the script file</a>
+<a name="autoindex.tut.step_4__create_the_script_file____to_control_what_to_index"></a><h5>
+<a name="id868460"></a>
+ <a class="link" href="tut.html#autoindex.tut.step_4__create_the_script_file____to_control_what_to_index">Step
+ 4: Create the script file - to control what to index</a>
 </h5>

- AutoIndex works by reading a script file that tells it what to index, at it's
- simplest it will scan one or more headers for terms that should be indexed
+ AutoIndex works by reading a script file that tells it what to index. 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:
 
@@ -438,14 +565,39 @@
 Or we can recursively scan through directories looking for all the files to
 scan whose name matches a particular regular expression:
 
-<pre class="programlisting">!scan-path "../../../../boost/math" ".*.hpp" true </pre>
+<pre class="programlisting">!scan-path "boost/mylibrary" ".*.hpp" true </pre>

- Note how each argument is whitespace separated and can be optionally enclosed
- in "double quotes". The final true argument
- indicates that subdirectories in <code class="computeroutput">../../../../boost/math</code>
- should be searched in addition to that directory.
+ Each argument is whitespace separated and can be optionally enclosed in "double
+ quotes" (recommended).
 

+ The final true argument indicates that subdirectories
+ in <code class="computeroutput">/boost/math/mylibrary</code> should be searched recursively
+ in addition to that directory.
+ 
+<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">
+ The second file-name-regex argument is a regular expression!
+ </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">
+ The scan-path is modified by any setting of <auto-index-prefix>. The
+ examples here assume that this is <code class="computeroutput"><auto-index-prefix>../../..</code> so that <code class="computeroutput">boost/mylibrary</code>
+ will be your header files, <code class="computeroutput">libs/mylibrary/docs</code> will
+ be your docs, like .qbk <code class="computeroutput">libs/mylibrary/examples</code>
+ will be your examples, usually .cpp.
+ </td></tr>
+</table></div>
+
 Often the scan or scan-path rules
 will bring in too many terms to search for, so we need to be able to exclude
 terms as well:
@@ -478,8 +630,9 @@
<pre class="programlisting">reflex \<reflex\w*\>
</pre>

- will index occurrences of "reflex", reflexing" and "reflexed"
- all under the same entry reflex.
+ will index occurrences of "reflex", "reflexing" and "reflexed"
+ all under the same entry reflex. You will very often need
+ to use this to deal with plurals and other variants.
 

 This inclusion rule can also restrict the term to certain sections, and add
@@ -494,43 +647,73 @@
 
<pre class="programlisting">!rewrite-name "(?i)(?:A|The)\s+(.*)" "\1"
</pre>
-<a name="autoindex.tut.step_5__add_manual_index_entries___optional"></a><h5>
-<a name="id1012202"></a>
- <a class="link" href="tut.html#autoindex.tut.step_5__add_manual_index_entries___optional">Step
- 5: Add Manual Index Entries - Optional</a>
+
+ Adding manual terms is most useful if you are using Quickbook to prepare your
+ documentation.
+ 
+
+ If many terms that you believe users would seek in the index are used in the
+ textual sections (and that these terms may not used in the C++ code itself,
+ or that you want to direct the user to the text rather than functions or classes),
+ then you need to add terms.
+ 
+
+ This may lead to too much indexing (especially if you have provided a Doxygen
+ autodoc C++ reference section that provides a good way of getting the C++ functions
+ etc). So it may be more useful to only index
+ the text part?
+ 
+<pre class="programlisting">!scan-path "boost/mylibrary" ".*.qbk" true </pre>
+
+ You could also scan the examples (.cpp) files. This will scan and may index
+ any explanatory C++ comments too. If an example's output is appended as a comment
+ then this text will also be scanned.
+ 
+<a name="autoindex.tut.step_5__add_manual_index_entries_to_docbook_xml___optional"></a><h5>
+<a name="id868851"></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>

- If you add manual <code class="computeroutput"><indexentry></code> markup to your docbook XML then these will
+ If you add manual <code class="computeroutput"><indexentry></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"><primary></code>
 and <code class="computeroutput"><secondary></code> elements within the <code class="computeroutput"><indexterm></code>.
 <code class="computeroutput"><tertiary></code>, <code class="computeroutput"><see></code> and
 <code class="computeroutput"><seealso></code> elements are not currently recognised and
- auto-index will emit a warning if these are used. 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.
+ auto-index will emit a warning if these are used.
+ 
+
+ 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.
 
<a name="autoindex.tut.step_6__build_the_docs"></a><h5>
-<a name="id1016192"></a>
+<a name="id868972"></a>
 <a class="link" href="tut.html#autoindex.tut.step_6__build_the_docs">Step 6: Build the Docs</a>
 </h5>

 Make sure that auto-index.jam is in your BOOST_BUILD_PATH, by either setting
 the environment variable BOOST_BUILD_PATH to point to the directory containing
- it, or by copying the file into <code class="computeroutput">boost-root/tools/build/v2/tools</code>. Then you build the docs with either:
+ it, or by copying the <code class="computeroutput">auto-index.jam</code>
+ file into <code class="computeroutput">boost-root/tools/build/v2/tools</code>.
 
-<pre class="programlisting">bjam release
+
+ Then you build the docs with either:
+ 
+<pre class="programlisting">bjam release > mylibrary_html.log
</pre>

 To build the html docs or:
 
-<pre class="programlisting">bjam pdf release
+<pre class="programlisting">bjam pdf release > mylibrary_pdf.log
</pre>

 To build the pdf.
 

- During the build process you should see AutoIndex emit a message such as:
+ During the build process you should see AutoIndex emit a message in the log
+ file such as:
 
<pre class="programlisting">Indexing 990 terms... </pre>

@@ -543,9 +726,15 @@

 Again if you see that 0 entries were created then something is wrong!
 
-<a name="autoindex.tut.step_7__iterate"></a><h5>
-<a name="id1016314"></a>
- <a class="link" href="tut.html#autoindex.tut.step_7__iterate">Step 7: Iterate</a>
+
+ 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 <code class="literal">!debug regular-expression
+ directive</code> is at the head of the script file.
+ 
+<a name="autoindex.tut.step_7__iterate___to_refine_your_index"></a><h5>
+<a name="id869166"></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>

 Creating a good index is an iterative process, often the first step is just
@@ -573,15 +762,15 @@
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top">
- If you don't understand why a particular term is present in the index, try
- adding a !debug regular-expression directive to the
- <a class="link" href="script_ref.html" title="Script File Reference">script file</a>.
+ If you don't understand why a particular term is (or is not) present in the
+ index, try adding a !debug regular-expression directive
+ to the <a class="link" href="script_ref.html" title="Script File Reference">script file</a>.
 </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 John Maddock
+<td align="right"><div class="copyright-footer">Copyright © 2008 , 2011 John Maddock
 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)

Modified: sandbox/tools/auto_index/doc/html/autoindex/xml.html
==============================================================================
--- sandbox/tools/auto_index/doc/html/autoindex/xml.html (original)
+++ sandbox/tools/auto_index/doc/html/autoindex/xml.html 2011-01-28 10:07:52 EST (Fri, 28 Jan 2011)
@@ -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>

- Auto-index is rather simplistic in it's handling of XML:
+ Auto-index is rather simplistic in its handling of XML:
 
<div class="itemizedlist"><ul type="disc">
<li>
@@ -44,7 +44,7 @@
</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
+<td align="right"><div class="copyright-footer">Copyright © 2008 , 2011 John Maddock
 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)

Modified: sandbox/tools/auto_index/doc/html/index.html
==============================================================================
--- sandbox/tools/auto_index/doc/html/index.html (original)
+++ sandbox/tools/auto_index/doc/html/index.html 2011-01-28 10:07:52 EST (Fri, 28 Jan 2011)
@@ -19,9 +19,9 @@
<div><div class="authorgroup"><div class="author"><h3 class="author">
John Maddock
</h3></div></div></div>
-<div>Copyright © 2008 John Maddock</div>
+<div>Copyright © 2008 , 2011 John Maddock</div>
<div><div class="legalnotice">
-<a name="id1010583"></a>
+<a name="id857440"></a>
 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)
 
@@ -41,7 +41,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left">Last revised: January 26, 2011 at 18:45:43 GMT</td>
+<td align="left">Last revised: January 28, 2011 at 15:01:40 GMT</td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

Next message: christophe.j.henry_at_[hidden]: "[Boost-commit] svn:boost r68535 - trunk/boost/msm/back"
Previous message: pbristow_at_[hidden]: "[Boost-commit] svn:boost r68533 - sandbox/tools/auto_index/doc"

Date view	Thread view	Subject view	Author view

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