|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r68604 - in sandbox/tools/auto_index/doc: . html html/autoindex
From: pbristow_at_[hidden]
Date: 2011-02-01 12:57:11
Author: pbristow
Date: 2011-02-01 12:56:53 EST (Tue, 01 Feb 2011)
New Revision: 68604
URL: http://svn.boost.org/trac/boost/changeset/68604
Log:
Some corrections to handling of text part
Binary files modified:
sandbox/tools/auto_index/doc/auto_index.pdf
Text files modified:
sandbox/tools/auto_index/doc/auto_index.qbk | 196 ++++++++++++++++++++++++++++-----------
sandbox/tools/auto_index/doc/html/autoindex/overview.html | 70 +++++++++-----
sandbox/tools/auto_index/doc/html/autoindex/script_ref.html | 22 ++--
sandbox/tools/auto_index/doc/html/autoindex/tut.html | 122 ++++++++++++++----------
sandbox/tools/auto_index/doc/html/index.html | 5
5 files changed, 269 insertions(+), 146 deletions(-)
Modified: sandbox/tools/auto_index/doc/auto_index.pdf
==============================================================================
Binary files. No diff available.
Modified: sandbox/tools/auto_index/doc/auto_index.qbk
==============================================================================
--- sandbox/tools/auto_index/doc/auto_index.qbk (original)
+++ sandbox/tools/auto_index/doc/auto_index.qbk 2011-02-01 12:56:53 EST (Tue, 01 Feb 2011)
@@ -10,10 +10,22 @@
[/last-revision $Date: 2008-11-04 17:11:53 +0000 (Tue, 04 Nov 2008) $]
]
+[def __quickbook [@http://www.boost.org/doc/tools/quickbook/index.html Quickbook]]
+[def __boostbook [@http://www.boost.org/doc/html/boostbook.html BoostBook]]
+[def __boostbook_docs [@http://www.boost.org/doc/libs/1_41_0/doc/html/boostbook.html BoostBook documentation]]
+[def __quickbook_syntax [@http://www.boost.org/doc/libs/1_41_0/doc/html/quickbook/ref.html Quickbook Syntax Compendium]]
+[def __docbook [@http://www.docbook.org/ DocBook]]
+[def __doxygen [@http://www.doxygen.org/ Doxygen]]
+[def __autoindex [@boost:\tools\auto_index\doc\html\index.html AutoIndex]]
+[def __pdf [@http://www.adobe.com/products/acrobat/adobepdf.html PDF]]
+
[section:overview Overview]
AutoIndex is a tool for taking the grunt work out of indexing a
-Quickbook\/Boostbook\/Docbook document that describes C\/C++ code.
+Boostbook\/Docbook document
+(perhaps generated by your Quickbook file mylibrary.qbk,
+and perhaps using also Doxygen autodoc)
+that describes C\/C++ code.
Traditionally, in order to index a Docbook document you would
have to manually add a large amount of `<indexterm>` markup:
@@ -23,32 +35,40 @@
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
-`<indexterm>`s into the XML document for you.
+`<indexterm>`s into the Docbook 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
+AutoIndex will also scan using a list of index terms that
+you need to manually provide a simple list of index terms
+(in a script file, for example index.idx , optionally using regular expressions).
+This may allow the user to find references to textual 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
+Providing a manual list of search 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,
+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 term, it creates two index entries - one has the search term
-as the primary index key and the title of the section it appears in as
-a subterm, the other has the section title as the main index entry and the
-search term as the subentry. Thus the user has two chances to find what their
-looking for, based upon either the section name or the ['function], ['class], ['macro]
-or ['typedef] name. Note that this behaviour can be changed so that only one
-index entry is created - using the search term as the key - and not using the
-section name except as a sub-entry of the search term.
+AutoIndex creates index entries as follows:
+
+for each occurrence of each search term, it creates two index entries:
+
+# The search term as the ['primary index key] and
+ the ['title of the section it appears in] as a subterm.
+
+# The section title as the main index entry and the search term as the subentry.
+
+Thus the user has two chances to find what their
+looking for, based upon either the section name
+or the ['function], ['class], ['macro] or ['typedef] name.
+
+[note This behaviour can be changed so that only one index entry is created
+ (using the search term as the key and
+ not using the section name except as a sub-entry of the search term).]
So for example in Boost.Math the class name `students_t_distribution` has a primary
-entry that lists all sections it appears in:
+entry that lists all sections the class name appears in:
[$../students_t_eg_1.png]
@@ -63,11 +83,11 @@
So AutoIndex provides some powerful regular expression based rules that allow you
to add, remove, constrain, or rewrite entries. Normally just a few lines in
AutoIndex's script file are enough to tailor the output to match the author's
-expectations.
+expectations (and thus hopefully the index user's expectations too!).
AutoIndex also supports multiple indexes (as does Docbook), and since it knows
which search terms are ['function], ['class], ['macro] or ['typedef] names, it
-can add the necessary attribubes to the XML so that you can have separate
+can add the necessary attributes to the XML so that you can have separate
indexes for each of these different types. These specialised indexes only contain
entries for the ['function], ['class], ['macro] or ['typedef] names, ['section
names] are never used as primary index terms here, unlike the main "include everything"
@@ -97,8 +117,8 @@
build requirements in the Jamfile:
[pre
-<format>html:<auto-index-internal>on # Use internally generated indexes
-<auto-index-type>index # Use <index>...</index> as the XML wrapper
+<format>html:<auto-index-internal>on # Use internally generated indexes.
+<auto-index-type>index # Use <index>...</index> as the XML wrapper.
<format>html:<xsl:param>generate.index=0 # Don't let the XSL stylesheets generate indexes.
]
@@ -181,15 +201,15 @@
# 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.
-
+ # But see <auto-index-prefix> to use for the optional scan path to scan for script files,
+ # for example:
# <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"
+ # and \/libs\/mylibrary for other files (doc, example...).
+ # Without a prefix you would need !scan-path "..\/..\/..\/boost\/mylibrary"
<auto-index-prefix>..\/..\/..
- # Tell Quickbook that is should enable indexing.
+ # Tell Quickbook that it should enable indexing.
<quickbook-define>enable_index ;
;
@@ -213,12 +233,19 @@
entry that uses the section title is not created. Defaults to "on"]]
[[<auto-index-verbose>off/on][Defaults to "off". When turned on AutoIndex
prints progress information - useful for debugging purposes during setup.]]
-[[<auto-index-prefix>filename][Specifies a directory to apply as a prefix to all relative file paths in the script file.
-For Boost standard layout, <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>filename][Optionally specifies a directory to apply
+as a prefix to all relative file paths in the script file.[br]
+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.[br]
+For Boost standard library layout,
+[^<auto-index-prefix>..\/..\/..] will get you back up to the 'root' of your library /mylibrary,
+so !scan-path [~boost\/mylibrary/] is where headers *.hpp will be, and [~\/libs\/mylibrary] for other files.
+Without a prefix all relative paths are relative to the location of the script file.[br]
+]]
[[<auto-index-type>element-name][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.
+ 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:]]
]
@@ -265,9 +292,9 @@
;
}
else
- {
- ECHO "Building the my_library docs with automatic index generation disabled. To get an auto-index, try building with --enable-index." ;
- }
+ {
+ 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:
@@ -301,10 +328,11 @@
[h4 Step 3: Add indexes to your documentation]
-To add a single "include everything" index to a Quickbook\/BoostBook\/Docbook document,
-then add `<index/>` 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 a single "include everything" index to a BoostBook\/Docbook document,
+(perhaps generated using Quickbook, and perhaps also using Doxygen reference section),
+add `<index/>` 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.
To add multiple indexes, then give each one a title and set its
`type` attribute to specify which terms will be included, for example
@@ -407,7 +435,7 @@
<xsl:param>index.on.type=1
]
-[h4 Step 4: Create the script file - to control what to index]
+[h4 Step 4: Create the script file - to control what to terms to index]
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
@@ -416,7 +444,8 @@
!scan myheader.hpp
-Or we can recursively scan through directories looking for all
+Or, more likely in practice,
+we can recursively scan through directories looking for all
the files to scan whose name matches a particular regular expression:
[pre !scan-path "boost\/mylibrary" ".*\.hpp" true ]
@@ -433,10 +462,18 @@
[caution The scan-path is modified by any setting of <auto-index-prefix>.
The examples here assume that this is `<auto-index-prefix>../../..`
so that `boost/mylibrary` will be your header files,
-`libs/mylibrary/docs` will be your docs, like .qbk
-`libs/mylibrary/examples` will be your examples, usually .cpp.
+`libs/mylibrary/doc` will be your docs, like .qbk
+`libs/mylibrary/example` will be your examples, usually .cpp.
]
+You could also scan any examples (.cpp) files,
+typically in folder `\/mylibrary\/lib\/example`.
+
+[pre
+# All example source files, assuming no sub-folders.
+!scan-path "libs\/mylibrary\/example" ".*\\.cpp"
+] [/pre]
+
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,25 +515,13 @@
!rewrite-name "(?i)(?:A|The)\s+(.*)" "\1"
-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 !scan-path "boost\/mylibrary" ".*\.qbk" true ]
-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
+If an example's output is appended as a comment,
then this text will also be scanned.
[h4 Step 5: Add Manual Index Entries to Docbook XML - Optional]
@@ -546,7 +571,6 @@
make sure that you have [^<auto-index-verbose>on] and that
[^!debug regular-expression directive] is at the head of the script file.
-
[h4 Step 7: Iterate - to refine your index]
Creating a good index is an iterative process, often the first step is
@@ -560,6 +584,21 @@
Further rules can then be added to the script to handle these cases
and the next iteration examined, and so on.
+[h4 Restricting which Sections are indexed for a particular term]
+
+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.
+
+For example, if you want to index occurrences of Lord Kelvin's name,
+but only in the introduction section, you might then add:
+
+Kelvin "" ".*introduction.*"
+
+to the script file,
+assuming that the section ID of the intro is "some_library_or_chapter_name.introduction".
+
[tip 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 [link autoindex.script_ref script file].
@@ -567,6 +606,47 @@
[endsect] [/section:tut Getting Started and Tutorial]
+[section:workflow AutoIndex Workflow]
+
+
+# Load the script file (usually index.idx)
+ and process it one line at a time,
+ probably producing one index term per (non-comment) line.
+
+# Reading all lines builds a list of ['terms to index].
+ Some of those may be terms defined (by you) directly in the script file,
+ others may be terms found by the scanning C++ header and source files
+ that were specified by the ['!scan-path].
+
+# Once the complete list of ['terms to index] is complete,
+ it loads the Docbook XML file.
+ (If this comes from Quickbook\/Doxygen\/Boostbook\/Docbook then this is
+ the complete documentation after conversion to Docbook format).
+
+# Builds an internal DOM of the Docbook XML.
+ This internal representation then gets scanned for occurrences of the ['terms to index].
+ This scanning works at the paragraph level
+ (or equivalent sibling such as a table or code block)
+ - so all the XML encoding within a paragraph gets flattened to plain text.[br]
+ This flattening means the regular expressions used to search for ['terms to index]
+ can find anything that is completely contained within a paragraph
+ (or code block etc).
+
+# For each term found then an ['indexterm] docbook element is inserted
+ into the DOM (if internal index generation is off),
+
+# Also the tools internal index gets updated.
+
+# Once the whole XML document has been indexed,
+ then, if auto-index has been instructed to generate the index itself,
+ it creates the necessary XML and inserts this into the DOM.
+
+# Finally the whole DOM is written out as a new Docbook XML file,
+ and normal processing of this continues via the XSL stylesheets and program XSLTproc.exe
+ to actually build the final human-readable docs.
+
+[endsect] [/section:workflow Auto-index Workflow]
+
[section:script_ref Script File Reference]
@@ -817,7 +897,7 @@
[[--no-section-names][Prevents auto_index from using section names as index entries.]]
[[prefix=pathname][Specifies a directory to apply as a prefix to all relative file paths in the script file.]]
[[index-type=element-name][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.]]
+ defaults to "section", but could equally be "appendix" or "chapter" or some other block level element that has a formal title.]]
]
[endsect] [/section:comm_ref Command Line Reference]
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-02-01 12:56:53 EST (Tue, 01 Feb 2011)
@@ -20,8 +20,9 @@
<a name="autoindex.overview"></a><a class="link" href="overview.html" title="Overview">Overview</a>
</h2></div></div></div>
<p>
- AutoIndex is a tool for taking the grunt work out of indexing a Quickbook/Boostbook/Docbook
- document that describes C/C++ code.
+ AutoIndex is a tool for taking the grunt work out of indexing a Boostbook/Docbook
+ document (perhaps generated by your Quickbook file mylibrary.qbk, and perhaps
+ using also Doxygen autodoc) that describes C/C++ code.
</p>
<p>
Traditionally, in order to index a Docbook document you would have to manually
@@ -33,36 +34,55 @@
extract all the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>,
<span class="emphasis"><em>macro</em></span> and <span class="emphasis"><em>typedef</em></span> names that are
defined by those headers, and then insert the <code class="computeroutput"><span class="special"><</span><span class="identifier">indexterm</span><span class="special">></span></code>s
- into the XML document for you.
+ into the Docbook XML document for you.
</p>
<p>
- AutoIndex can also scan <span class="emphasis"><em>text files</em></span>, 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.
+ AutoIndex will also scan using a list of index terms that you need to manually
+ provide a simple list of index terms (in a script file, for example index.idx
+ , optionally using regular expressions). This may allow the user to find references
+ to textual items that may not occur in the C++ classes and functions header
+ files.
</p>
<p>
- 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.
+ Providing a manual list of search 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.
</p>
<p>
- AutoIndex creates index entries as follows - for each occurrence of each search
- term, it creates two index entries - one has the search term as the primary
- index key and the title of the section it appears in as a subterm, the other
- has the section title as the main index entry and the search term as the subentry.
+ AutoIndex creates index entries as follows:
+ </p>
+<p>
+ for each occurrence of each search term, it creates two index entries:
+ </p>
+<div class="orderedlist"><ol type="1">
+<li>
+ The search term as the <span class="emphasis"><em>primary index key</em></span> and the
+ <span class="emphasis"><em>title of the section it appears in</em></span> as a subterm.
+ </li>
+<li>
+ The section title as the main index entry and the search term as the subentry.
+ </li>
+</ol></div>
+<p>
Thus the user has two chances to find what their looking for, based upon either
the section name or the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>,
- <span class="emphasis"><em>macro</em></span> or <span class="emphasis"><em>typedef</em></span> name. Note that
- this behaviour can be changed so that only one index entry is created - using
- the search term as the key - and not using the section name except as a sub-entry
- of the search term.
+ <span class="emphasis"><em>macro</em></span> or <span class="emphasis"><em>typedef</em></span> name.
</p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ This behaviour can be changed so that only one index entry is created (using
+ the search term as the key and not using the section name except as a sub-entry
+ of the search term).
+ </p></td></tr>
+</table></div>
<p>
So for example in Boost.Math the class name <code class="computeroutput"><span class="identifier">students_t_distribution</span></code>
- has a primary entry that lists all sections it appears in:
+ has a primary entry that lists all sections the class name appears in:
</p>
<p>
<span class="inlinemediaobject"><img src="../../students_t_eg_1.png" alt="students_t_eg_1"></span>
@@ -81,13 +101,13 @@
So AutoIndex provides some powerful regular expression based rules that allow
you to add, remove, constrain, or rewrite entries. Normally just a few lines
in AutoIndex's script file are enough to tailor the output to match the author's
- expectations.
+ expectations (and thus hopefully the index user's expectations too!).
</p>
<p>
AutoIndex also supports multiple indexes (as does Docbook), and since it knows
which search terms are <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>,
<span class="emphasis"><em>macro</em></span> or <span class="emphasis"><em>typedef</em></span> names, it can add
- the necessary attribubes to the XML so that you can have separate indexes for
+ the necessary attributes to the XML so that you can have separate indexes for
each of these different types. These specialised indexes only contain entries
for the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>, <span class="emphasis"><em>macro</em></span>
or <span class="emphasis"><em>typedef</em></span> names, <span class="emphasis"><em>section names</em></span> are
@@ -123,8 +143,8 @@
off index generation by the XSL stylesheets, for example by setting the following
build requirements in the Jamfile:
</p>
-<pre class="programlisting"><format>html:<auto-index-internal>on # Use internally generated indexes
-<auto-index-type>index # Use <index>...</index> as the XML wrapper
+<pre class="programlisting"><format>html:<auto-index-internal>on # Use internally generated indexes.
+<auto-index-type>index # Use <index>...</index> as the XML wrapper.
<format>html:<xsl:param>generate.index=0 # Don't let the XSL stylesheets generate indexes.
</pre>
</div>
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-02-01 12:56:53 EST (Tue, 01 Feb 2011)
@@ -6,14 +6,14 @@
<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="workflow.html" title="AutoIndex Workflow">
<link rel="next" href="xml.html" title="XML Handling">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="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="xml.html"><img src="../images/next.png" alt="Next"></a>
+<a accesskey="p" href="workflow.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="xml.html"><img src="../images/next.png" alt="Next"></a>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -23,7 +23,7 @@
The following elements can occur in a script:
</p>
<a name="autoindex.script_ref.comments_and_blank_lines"></a><h5>
-<a name="id869246"></a>
+<a name="id874964"></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.simple_inclusions"></a><h5>
-<a name="id869267"></a>
+<a name="id874986"></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>
@@ -99,7 +99,7 @@
</dl>
</div>
<a name="autoindex.script_ref.source_file_scanning"></a><h5>
-<a name="id870626"></a>
+<a name="id875195"></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>
@@ -128,7 +128,7 @@
</p></td></tr>
</table></div>
<a name="autoindex.script_ref.directory_and_source_file_scanning"></a><h5>
-<a name="id870704"></a>
+<a name="id875273"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.directory_and_source_file_scanning">Directory
and Source File Scanning</a>
</h5>
@@ -157,7 +157,7 @@
</dl>
</div>
<a name="autoindex.script_ref.excluding_terms"></a><h5>
-<a name="id870828"></a>
+<a name="id875398"></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>
@@ -170,7 +170,7 @@
of things to index.
</p>
<a name="autoindex.script_ref.rewriting_section_names"></a><h5>
-<a name="id870884"></a>
+<a name="id875453"></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!
</p>
<a name="autoindex.script_ref.defining_or_changing_the_file_scanners"></a><h5>
-<a name="id871036"></a>
+<a name="id875605"></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>
@@ -320,7 +320,7 @@
scanner may find in the documentation.
</p>
<a name="autoindex.script_ref.debugging_scanning"></a><h5>
-<a name="id871539"></a>
+<a name="id876108"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.debugging_scanning">Debugging scanning</a>
</h5>
<p>
@@ -358,7 +358,7 @@
</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="xml.html"><img src="../images/next.png" alt="Next"></a>
+<a accesskey="p" href="workflow.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="xml.html"><img src="../images/next.png" alt="Next"></a>
</div>
</body>
</html>
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-02-01 12:56:53 EST (Tue, 01 Feb 2011)
@@ -7,20 +7,20 @@
<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="workflow.html" title="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="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="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.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="id867220"></a>
+<a name="id871627"></a>
<a class="link" href="tut.html#autoindex.tut.step_1__build_the_autoindex_tool">Step 1: Build
the AutoIndex tool</a>
</h5>
@@ -74,7 +74,7 @@
</p></td></tr>
</table></div>
<a name="autoindex.tut.step_2__configure_boost_build_to_use_autoindex"></a><h5>
-<a name="id867482"></a>
+<a name="id871889"></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>
@@ -120,15 +120,15 @@
# 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.
-
+ # But see <auto-index-prefix> to use for the optional scan path to scan for script files,
+ # for example:
# <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"
+ # and /libs/mylibrary for other files (doc, example...).
+ # Without a prefix you would need !scan-path "../../../boost/mylibrary"
<auto-index-prefix>../../..
- # Tell Quickbook that is should enable indexing.
+ # Tell Quickbook that it should enable indexing.
<quickbook-define>enable_index ;
;
@@ -174,11 +174,17 @@
</p></dd>
<dt><span class="term"><auto-index-prefix>filename</span></dt>
<dd><p>
- Specifies a directory to apply as a prefix to all relative file paths
- in the script file. For Boost standard layout, <auto-index-prefix>../../..
- will get you back up to /mylibrary, so !scan-path "boost<span class="emphasis"><em>mylibrary</em></span>"
- is where headers *.hpp will be and /libs/mylibrary for other files. Without
- this you would need !scan-path "../../../boost/mylibrary"
+ Optionally specifies a directory to apply as a prefix to all relative
+ file paths in the script file.<br> 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.<br> For Boost standard
+ library layout, <code class="literal"><auto-index-prefix>../../..</code>
+ will get you back up to the 'root' of your library /mylibrary, so !scan-path
+ <em class="replaceable"><code>boost/mylibrary/</code></em> is where headers *.hpp 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.<br>
</p></dd>
<dt><span class="term"><auto-index-type>element-name</span></dt>
<dd><p>
@@ -378,9 +384,9 @@
;
}
else
- {
- ECHO "Building the my_library docs with automatic index generation disabled. To get an auto-index, try building with --enable-index." ;
- }
+ {
+ 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:
@@ -432,15 +438,16 @@
</p></td></tr>
</table></div>
<a name="autoindex.tut.step_3__add_indexes_to_your_documentation"></a><h5>
-<a name="id868109"></a>
+<a name="id872532"></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 Quickbook/BoostBook/Docbook
- document, then add <code class="computeroutput"><span class="special"><</span><span class="identifier">index</span><span class="special">/></span></code> at the location where you want the index
- to appear. The index will be rendered as a separate section when the documentation
- is built.
+ To add a single "include everything" index to a BoostBook/Docbook
+ document, (perhaps generated using Quickbook, and perhaps also using Doxygen
+ reference section), add <code class="computeroutput"><span class="special"><</span><span class="identifier">index</span><span class="special">/></span></code> at the location where you want the index
+ to appear. The index will be rendered as a separate section called "Index"
+ when the documentation is built.
</p>
<p>
To add multiple indexes, then give each one a title and set its <code class="computeroutput"><span class="identifier">type</span></code> attribute to specify which terms will
@@ -548,10 +555,10 @@
# Turn on multiple index support:
<xsl:param>index.on.type=1
</pre>
-<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>
+<a name="autoindex.tut.step_4__create_the_script_file____to_control_what_to_terms_to_index"></a><h5>
+<a name="id872883"></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 to index. At its
@@ -562,8 +569,8 @@
<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>
</pre>
<p>
- Or we can recursively scan through directories looking for all the files to
- scan whose name matches a particular regular expression:
+ Or, more likely in practice, we can recursively scan through directories looking
+ for all the files to scan whose name matches a particular regular expression:
</p>
<pre class="programlisting">!scan-path "boost/mylibrary" ".*.hpp" true </pre>
<p>
@@ -592,12 +599,18 @@
<tr><td align="left" valign="top"><p>
The scan-path is modified by any setting of <auto-index-prefix>. The
examples here assume that this is <code class="computeroutput"><span class="special"><</span><span class="keyword">auto</span><span class="special">-</span><span class="identifier">index</span><span class="special">-</span><span class="identifier">prefix</span><span class="special">>../../..</span></code> so that <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mylibrary</span></code>
- will be your header files, <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">mylibrary</span><span class="special">/</span><span class="identifier">docs</span></code> will
- be your docs, like .qbk <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">mylibrary</span><span class="special">/</span><span class="identifier">examples</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
+ be your docs, like .qbk <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 be your examples, usually .cpp.
</p></td></tr>
</table></div>
<p>
+ You could also scan any examples (.cpp) files, typically in folder <code class="computeroutput"><span class="special">\/</span><span class="identifier">mylibrary</span><span class="special">\/</span><span class="identifier">lib</span><span class="special">\/</span><span class="identifier">example</span></code>.
+ </p>
+<pre class="programlisting"># All example source files, assuming no sub-folders.
+!scan-path "libs/mylibrary/example" ".*\.cpp"
+</pre>
+<p>
Often the <span class="emphasis"><em>scan</em></span> or <span class="emphasis"><em>scan-path</em></span> rules
will bring in too many terms to search for, so we need to be able to exclude
terms as well:
@@ -648,29 +661,16 @@
<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>
<p>
- Adding manual terms is most useful if you are using Quickbook to prepare your
- documentation.
- </p>
-<p>
- 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.
- </p>
-<p>
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 <span class="bold"><strong>only</strong></span> index
- the text part?
+ etc).
</p>
-<pre class="programlisting">!scan-path "boost/mylibrary" ".*.qbk" true </pre>
<p>
- 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.
+ 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.
</p>
<a name="autoindex.tut.step_5__add_manual_index_entries_to_docbook_xml___optional"></a><h5>
-<a name="id868851"></a>
+<a name="id873289"></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>
@@ -689,7 +689,7 @@
"type" attribute.
</p>
<a name="autoindex.tut.step_6__build_the_docs"></a><h5>
-<a name="id868972"></a>
+<a name="id873411"></a>
<a class="link" href="tut.html#autoindex.tut.step_6__build_the_docs">Step 6: Build the Docs</a>
</h5>
<p>
@@ -732,7 +732,7 @@
directive</code> is at the head of the script file.
</p>
<a name="autoindex.tut.step_7__iterate___to_refine_your_index"></a><h5>
-<a name="id869166"></a>
+<a name="id873605"></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>
@@ -756,6 +756,28 @@
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="id873653"></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>
+<p>
+ Kelvin "" ".<span class="bold"><strong>introduction.</strong></span>"
+ </p>
+<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>
@@ -778,7 +800,7 @@
</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="workflow.html"><img src="../images/next.png" alt="Next"></a>
</div>
</body>
</html>
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-02-01 12:56:53 EST (Tue, 01 Feb 2011)
@@ -21,7 +21,7 @@
</h3></div></div></div>
<div><p class="copyright">Copyright © 2008 , 2011 John Maddock</p></div>
<div><div class="legalnotice">
-<a name="id857440"></a><p>
+<a name="id861809"></a><p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</p>
@@ -34,6 +34,7 @@
<dl>
<dt><span class="section">Overview</span></dt>
<dt><span class="section">Getting Started and Tutorial</span></dt>
+<dt><span class="section">AutoIndex Workflow</span></dt>
<dt><span class="section">Script File Reference</span></dt>
<dt><span class="section">XML Handling</span></dt>
<dt><span class="section">Command Line Reference</span></dt>
@@ -41,7 +42,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: January 28, 2011 at 15:01:40 GMT</small></p></td>
+<td align="left"><p><small>Last revised: February 01, 2011 at 17:38:04 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>
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