|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r68638 - in sandbox/tools/auto_index/doc: . html html/autoindex
From: john_at_[hidden]
Date: 2011-02-04 13:51:18
Author: johnmaddock
Date: 2011-02-04 13:51:10 EST (Fri, 04 Feb 2011)
New Revision: 68638
URL: http://svn.boost.org/trac/boost/changeset/68638
Log:
Fix some typos, move a few things around.
Regenerate docs.
Text files modified:
sandbox/tools/auto_index/doc/auto_index.qbk | 199 ++++++++++++++++++++-------------------
sandbox/tools/auto_index/doc/html/autoindex/overview.html | 23 ++--
sandbox/tools/auto_index/doc/html/autoindex/script_ref.html | 84 ++++++++++------
sandbox/tools/auto_index/doc/html/autoindex/tut.html | 135 ++++++++++++++-------------
sandbox/tools/auto_index/doc/html/autoindex/xml.html | 6
sandbox/tools/auto_index/doc/html/index.html | 15 ++
6 files changed, 251 insertions(+), 211 deletions(-)
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-04 13:51:10 EST (Fri, 04 Feb 2011)
@@ -39,13 +39,12 @@
names that are defined by those headers, and then insert the
`<indexterm>`s into the Docbook XML document for you.
-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 search terms in the text to index is a tedious task
+AutoIndex can also scan using a list of index terms
+specified in a script file, for example index.idx.
+These manually provided terms can optionally be regular expressions,
+and may allow the user to find references to terms
+that may not occur in the C++ header files. Of course providing a manual
+list of search terms in to index is a tedious task
(especially handling plurals and variants),
and requires enough knowledge of the library
to guess what users may be seeking to know,
@@ -61,7 +60,7 @@
# 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
+Thus the user has two chances to find what they're
looking for, based upon either the section name
or the ['function], ['class], ['macro] or ['typedef] name.
@@ -152,7 +151,7 @@
Also note that Windows users must use forward slashes in the paths in `user-config.jam`]
-Finally note that `tools/auto_index/auto-index.jam` gets copied into the same directory as the rest of the Boost.Build tools
+Finally note that [=tools/auto_index/auto-index.jam] gets copied into the same directory as the rest of the Boost.Build tools
(under `tools/build/v2/tools` in your main Boost tree): this is a temporary fix that will go away
if the tool is accepted into Boost.
@@ -191,7 +190,6 @@
# 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.
@@ -203,12 +201,14 @@
# 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 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 (doc, example...).
- # Without a prefix you would need !scan-path "..\/..\/..\/boost\/mylibrary"
+ # Commands in the script file should all use RELATIVE PATHS
+ # otherwise the script will not be portable to other machines.
+ # Relative paths are normally taken as relative to the location
+ # of the script file, but we can add a prefix to all
+ # those relative paths using the <auto-index-prefix> feature.
+ # The path specified by <auto-index-prefix> may be either relative or
+ # absolute, for example the following will get us up to the boost root
+ # directory for most Boost libraries:
<auto-index-prefix>..\/..\/..
# Tell Quickbook that it should enable indexing.
@@ -236,15 +236,17 @@
[[<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][Optionally specifies a directory to apply
-as a prefix to all relative file paths in the script file.[br]
+as a prefix to all relative file paths in the script file.
+
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]
+but the script file is in Boost sandbox.
+
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-prefix>..\/..\/..] will get you back up to the 'root' of the Boost tree,
+so !scan-path [~boost\/mylibrary/] is where your headers will be, and [~libs\/mylibrary] for other files.
+Without a prefix all relative paths are relative to the location of the script file.
]]
[[<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.
@@ -269,9 +271,6 @@
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,
@@ -322,7 +321,7 @@
] [/tip]
[tip If you upgrade compiler version, for example MSVC from 9 to 10,
-then you will need to rebuild Autoindex
+then you may need to rebuild Autoindex
to avoid what Microsoft call a 'side-by-side' error.
And make sure that the autoindex.exe version you are using is the new one.
] [/tip]
@@ -387,6 +386,13 @@
[pre
<xsl:param>"boost.doxygen.reftitle=Boost.mylibrary C++ Reference"
]
+
+[note AutoIndex knows nothing of the XML `xinclude` element, so if
+you're writing raw Docbook XML then you may want to run this through an
+XSL processor to flatten everything to one XML file before passing to
+AutoIndex. If you're using Boostbook or quickbook though, this all
+happens for you anyway, and AutoIndex will index the whole document
+including any sections included with `xinclude`.]
If you are using auto-index's internal index generation on
@@ -444,7 +450,7 @@
If your document contains largely text, and only a small amount of simple C++,
and/or if you are using Doxygen to provide a C++ Reference section
(that lists the C++ elements),
-and/or if you are relying the indexinf provided from a Standalone Doxygen Index,
+and/or if you are relying on the indexing provided from a Standalone Doxygen Index,
you may decide that a index is not needed
and that you may only want the text part indexed.
@@ -471,13 +477,13 @@
that subdirectories in `/boost/math/mylibrary` should be searched
recursively in addition to that directory.
-[caution The second ['file-name-regex] argument is a regular expression!]
+[caution The second ['file-name-regex] argument is a regular expression and not a filename GLOB!]
[caution The scan-path is modified by any setting of <auto-index-prefix>.
-The examples here assume that this is `<auto-index-prefix>../../..`
+The examples here assume that this is [=<auto-index-prefix>../../..]
so that `boost/mylibrary` will be your header files,
-`libs/mylibrary/doc` will be your docs, like .qbk
-`libs/mylibrary/example` will be your examples, usually .cpp.
+`libs/mylibrary/doc` will contain your documentation files and
+`libs/mylibrary/example` will contain your examples.
]
You could also scan any examples (.cpp) files,
@@ -529,15 +535,6 @@
!rewrite-name "(?i)(?:A|The)\s+(.*)" "\1"
-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).
-
-
-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.
-
[h4 Step 5: Add Manual Index Entries to Docbook XML - Optional]
If you add manual `<indexentry>` markup to your Docbook XML then these will be
@@ -553,12 +550,7 @@
[h4 Step 6: Build the Docs]
-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 `auto-index.jam` file into
-`boost-root/tools/build/v2/tools`.
-
-Then you build the docs with either:
+Using Boost.Build you build the docs with either:
bjam release > mylibrary_html.log
@@ -583,7 +575,8 @@
Examine the log file, and if the cause is not obvious,
make sure that you have [^<auto-index-verbose>on] and that
-[^!debug regular-expression directive] is at the head of the script file.
+any needed
+[^!debug regular-expression] directives are in your script file.
[h4 Step 7: Iterate - to refine your index]
@@ -620,46 +613,6 @@
[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).
-
-# AutoIndex 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 XML paragraph level
- (or equivalent sibling such as a table or code block)
- - so all the XML encoding within a paragraph gets flattened to plain text.[br]
- This flattening means the regular expressions used to search for ['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 tool's internal index gets updated. TODO Which tool? <<<<<<<<<<<<<<<<<<<
-
-# Once the whole XML document has been indexed,
- then, if autoindex 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]
@@ -675,17 +628,21 @@
term [regular-expression1 [regular-expression2 [category]]]
[variablelist
-[[term][['Term to index.][br]
+[[term][
+['Term to index.]
+
The index term will form a primary entry in the Index
with the section title(s) containing the term as secondary entries, and
also will be used as a secondary entry beneath each of the section
titles that the index term occurs in.]
] [/term]
-[[regular-expression1][['Index term Searcher.][br]
+[[regular-expression1][
+['Index term Searcher.]
+
An optional regular expression: each occurrence
of the regular expression in the text of the document will result
-in one index index term being emitted.
+in one index term being emitted.
If the regular expression is omitted (default) or is "", then the ['index term] itself
will be used as the search text - and only occurrence of whole words matching
@@ -715,11 +672,12 @@
] [/regular-expression1]
[[regular-expression2]
-[['Section(s) Selector.][br]
+[['Section(s) Selector.]
+
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 occurrences of ['index term].
+for occurrences of ['term].
For example, to limit indexing to just [*one specific section] (but not sub-sections below):
@@ -751,12 +709,20 @@
]
] [/regular-expression2]
-[[category][['Index Category.][br]
-Optionally an to place occurrences of ['index term] in.
+[[category][
+['Index Category Constraint.]
+
+Optionally a category to place occurrences of ['index term] in.
If you have multiple indexes then this is the name
-assigned to the indexes "type" attribute.]
-[/ TODO Need an example of category? function, class, macro, typdef???]
-] [/category]
+assigned to the indexes "type" attribute.
+
+For example:
+
+ myclass "" "" class_name
+
+Will index occurances of ['myclass] and place them in the class-index if there is one.
+
+]] [/category]
] [/variablelist]
@@ -921,6 +887,46 @@
[endsect] [/section:script_ref Script File Reference]
+[section:workflow Understanding The AutoIndex Workflow]
+
+# Load the script file (usually index.idx)
+ and process it one line at a time,
+ producing one or more index term per (non-comment) line.
+
+# 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 scanning C++ header and source files
+ that were specified by the ['!scan-path] directive.
+
+# 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).
+
+# AutoIndex 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 XML paragraph level
+ (or equivalent sibling such as a table or code block)
+ - so all the XML encoding within a paragraph gets flattened to plain text.[br]
+ This flattening means the regular expressions used to search for ['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 (provided internal index generation is off),
+
+# Also the AutoIndex's internal index representation gets updated.
+
+# Once the whole XML document has been indexed,
+ then, if autoindex 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 (with xsltproc)
+ to actually build the final human-readable docs.
+
+[endsect] [/section:workflow Auto-index Workflow]
+
[section:xml XML Handling]
@@ -963,4 +969,3 @@
-
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-04 13:51:10 EST (Fri, 04 Feb 2011)
@@ -37,17 +37,14 @@
into the Docbook XML document for you.
</p>
<p>
- 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 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.
+ AutoIndex can also scan using a list of index terms specified in a script file,
+ for example index.idx. These manually provided terms can optionally be regular
+ expressions, and may allow the user to find references to terms that may not
+ occur in the C++ header files. Of course providing a manual list of search
+ terms in to index is a tedious task (especially handling plurals and variants),
+ and requires enough knowledge of the library to guess what users may be seeking
+ to know, but at least the real 'grunt work' of finding the term and listing
+ the page number is automated.
</p>
<p>
AutoIndex creates index entries as follows:
@@ -65,8 +62,8 @@
</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>,
+ Thus the user has two chances to find what they're looking for, based upon
+ either the section name or the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>,
<span class="emphasis"><em>macro</em></span> or <span class="emphasis"><em>typedef</em></span> name.
</p>
<div class="note"><table border="0" summary="Note">
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-04 13:51:10 EST (Fri, 04 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="workflow.html" title="AutoIndex Workflow">
-<link rel="next" href="xml.html" title="XML Handling">
+<link rel="prev" href="tut.html" title="Getting Started and Tutorial">
+<link rel="next" href="workflow.html" title="Understanding The AutoIndex Workflow">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="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>
+<a accesskey="p" href="tut.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="workflow.html"><img src="../images/next.png" alt="Next"></a>
</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="id864035"></a>
+<a name="id1002121"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.comments_and_blank_lines">Comments and
blank lines</a>
</h5>
@@ -32,7 +32,7 @@
comments onto the end of a line!).
</p>
<a name="autoindex.script_ref.inclusion_of_index_terms"></a><h5>
-<a name="id864056"></a>
+<a name="id1002142"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.inclusion_of_index_terms">Inclusion of
Index terms</a>
</h5>
@@ -42,18 +42,25 @@
<p class="title"><b></b></p>
<dl>
<dt><span class="term">term</span></dt>
-<dd><p>
- <span class="emphasis"><em>Term to index.</em></span><br> The index term will form a
- primary entry in the Index with the section title(s) containing the term
- as secondary entries, and also will be used as a secondary entry beneath
- each of the section titles that the index term occurs in.
- </p></dd>
+<dd>
+<p>
+ <span class="emphasis"><em>Term to index.</em></span>
+ </p>
+<p>
+ The index term will form a primary entry in the Index with the section
+ title(s) containing the term as secondary entries, and also will be used
+ as a secondary entry beneath each of the section titles that the index
+ term occurs in.
+ </p>
+</dd>
<dt><span class="term">regular-expression1</span></dt>
<dd>
<p>
- <span class="emphasis"><em>Index term Searcher.</em></span><br> An optional regular expression:
- each occurrence of the regular expression in the text of the document
- will result in one index index term being emitted.
+ <span class="emphasis"><em>Index term Searcher.</em></span>
+ </p>
+<p>
+ An optional regular expression: each occurrence of the regular expression
+ in the text of the document will result in one index term being emitted.
</p>
<p>
If the regular expression is omitted (default) or is "", then
@@ -110,10 +117,12 @@
<dt><span class="term">regular-expression2</span></dt>
<dd>
<p>
- <span class="emphasis"><em>Section(s) Selector.</em></span><br> A constraint that specifies
- which sections are indexed for <span class="emphasis"><em>term</em></span>: only if the
- ID of the section matches <span class="emphasis"><em>regular-expression2</em></span> exactly
- will that section be indexed for occurrences of <span class="emphasis"><em>index term</em></span>.
+ <span class="emphasis"><em>Section(s) Selector.</em></span>
+ </p>
+<p>
+ A constraint that specifies which sections are indexed for <span class="emphasis"><em>term</em></span>:
+ only if the ID of the section matches <span class="emphasis"><em>regular-expression2</em></span>
+ exactly will that section be indexed for occurrences of <span class="emphasis"><em>term</em></span>.
</p>
<p>
For example, to limit indexing to just <span class="bold"><strong>one specific
@@ -175,15 +184,30 @@
</p>
</dd>
<dt><span class="term">category</span></dt>
-<dd><p>
- <span class="emphasis"><em>Index Category.</em></span><br> Optionally an to place occurrences
- of <span class="emphasis"><em>index term</em></span> in. If you have multiple indexes then
- this is the name assigned to the indexes "type" attribute.
- </p></dd>
+<dd>
+<p>
+ <span class="emphasis"><em>Index Category Constraint.</em></span>
+ </p>
+<p>
+ Optionally a category to place occurrences of <span class="emphasis"><em>index term</em></span>
+ in. If you have multiple indexes then this is the name assigned to the
+ indexes "type" attribute.
+ </p>
+<p>
+ For example:
+ </p>
+<p>
+ myclass "" "" class_name
+ </p>
+<p>
+ Will index occurances of <span class="emphasis"><em>myclass</em></span> and place them
+ in the class-index if there is one.
+ </p>
+</dd>
</dl>
</div>
<a name="autoindex.script_ref.source_file_scanning"></a><h5>
-<a name="id864493"></a>
+<a name="id1003183"></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>
@@ -212,7 +236,7 @@
</p></td></tr>
</table></div>
<a name="autoindex.script_ref.directory_and_source_file_scanning"></a><h5>
-<a name="id864571"></a>
+<a name="id1003261"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.directory_and_source_file_scanning">Directory
and Source File Scanning</a>
</h5>
@@ -241,7 +265,7 @@
</dl>
</div>
<a name="autoindex.script_ref.excluding_terms"></a><h5>
-<a name="id864696"></a>
+<a name="id1003386"></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>
@@ -254,7 +278,7 @@
of things to index.
</p>
<a name="autoindex.script_ref.rewriting_section_names"></a><h5>
-<a name="id864751"></a>
+<a name="id1003441"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.rewriting_section_names">Rewriting Section
Names</a>
</h5>
@@ -301,7 +325,7 @@
all index entries - thus preventing lots of entries under "The" etc!
</p>
<a name="autoindex.script_ref.defining_or_changing_the_file_scanners"></a><h5>
-<a name="id864904"></a>
+<a name="id1003593"></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>
@@ -404,7 +428,7 @@
scanner may find in the documentation.
</p>
<a name="autoindex.script_ref.debugging_scanning"></a><h5>
-<a name="id865406"></a>
+<a name="id1004096"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.debugging_scanning">Debugging scanning</a>
</h5>
<p>
@@ -442,7 +466,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="workflow.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="xml.html"><img src="../images/next.png" alt="Next"></a>
+<a accesskey="p" href="tut.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="workflow.html"><img src="../images/next.png" alt="Next"></a>
</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-04 13:51:10 EST (Fri, 04 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="workflow.html" title="AutoIndex Workflow">
+<link rel="next" href="script_ref.html" title="Script File Reference">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="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>
+<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>
</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="id860648"></a>
+<a name="id992417"></a>
<a class="link" href="tut.html#autoindex.tut.step_1__build_the_autoindex_tool">Step 1: Build
the AutoIndex tool</a>
</h5>
@@ -57,11 +57,10 @@
</td></tr>
</table></div>
<p>
- Finally note that <code class="computeroutput"><span class="identifier">tools</span><span class="special">/</span><span class="identifier">auto_index</span><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">jam</span></code> gets
- copied into the same directory as the rest of the Boost.Build tools (under
- <code class="computeroutput"><span class="identifier">tools</span><span class="special">/</span><span class="identifier">build</span><span class="special">/</span><span class="identifier">v2</span><span class="special">/</span><span class="identifier">tools</span></code> in
- your main Boost tree): this is a temporary fix that will go away if the tool
- is accepted into Boost.
+ Finally note that [=tools/auto_index/auto-index.jam] gets copied into the same
+ directory as the rest of the Boost.Build tools (under <code class="computeroutput"><span class="identifier">tools</span><span class="special">/</span><span class="identifier">build</span><span class="special">/</span><span class="identifier">v2</span><span class="special">/</span><span class="identifier">tools</span></code>
+ in your main Boost tree): this is a temporary fix that will go away if the
+ tool is accepted into Boost.
</p>
<div class="caution"><table border="0" summary="Caution">
<tr>
@@ -74,7 +73,7 @@
</p></td></tr>
</table></div>
<a name="autoindex.tut.step_2__configure_boost_build_to_use_autoindex"></a><h5>
-<a name="id860909"></a>
+<a name="id992642"></a>
<a class="link" href="tut.html#autoindex.tut.step_2__configure_boost_build_to_use_autoindex">Step
2: Configure Boost.Build to use AutoIndex</a>
</h5>
@@ -108,7 +107,6 @@
# 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.
@@ -120,12 +118,14 @@
# 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 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 (doc, example...).
- # Without a prefix you would need !scan-path "../../../boost/mylibrary"
+ # Commands in the script file should all use RELATIVE PATHS
+ # otherwise the script will not be portable to other machines.
+ # Relative paths are normally taken as relative to the location
+ # of the script file, but we can add a prefix to all
+ # those relative paths using the <auto-index-prefix> feature.
+ # The path specified by <auto-index-prefix> may be either relative or
+ # absolute, for example the following will get us up to the boost root
+ # directory for most Boost libraries:
<auto-index-prefix>../../..
# Tell Quickbook that it should enable indexing.
@@ -173,19 +173,26 @@
information - useful for debugging purposes during setup.
</p></dd>
<dt><span class="term"><auto-index-prefix>filename</span></dt>
-<dd><p>
+<dd>
+<p>
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
+ file paths in the script file.
+ </p>
+<p>
+ You may wish to do this to reduce typing of pathnames, and/or where the
+ paths can't be located relative to the script file location, typically
+ if the headers are in the Boost trunk, but the script file is in Boost
+ sandbox.
+ </p>
+<p>
+ For Boost standard library layout, <code class="literal"><auto-index-prefix>../../..</code>
+ will get you back up to the 'root' of the Boost tree, so !scan-path
+ <em class="replaceable"><code>boost/mylibrary/</code></em> is where your headers will
+ be, and <em class="replaceable"><code>libs/mylibrary</code></em> for other files. Without
a prefix all relative paths are relative to the location of the script
- file.<br>
- </p></dd>
+ file.
+ </p>
+</dd>
<dt><span class="term"><auto-index-type>element-name</span></dt>
<dd><p>
Specifies the name of the XML element to enclose internally generated
@@ -358,10 +365,6 @@
be able to build your documentation.
</p>
<p>
- One method of setting up optional auto-index support is to place all auto-index
- configuration in a the body of a <span class="emphasis"><em>bjam if statement</em></span>.
- </p>
-<p>
This also very convenient while you are refining your documentation, to allow
you to decide to build indexes, or not: building indexes can take long time,
if you are just correcting typos, you won't want wait while you keep rebuilding
@@ -432,13 +435,13 @@
</tr>
<tr><td align="left" valign="top"><p>
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'
+ may need to rebuild Autoindex to avoid what Microsoft call a 'side-by-side'
error. And make sure that the autoindex.exe version you are using is the
new one.
</p></td></tr>
</table></div>
<a name="autoindex.tut.step_3__add_indexes_to_your_documentation"></a><h5>
-<a name="id861552"></a>
+<a name="id1000965"></a>
<a class="link" href="tut.html#autoindex.tut.step_3__add_indexes_to_your_documentation">Step
3: Add indexes to your documentation</a>
</h5>
@@ -506,6 +509,20 @@
</p>
<pre class="programlisting"><xsl:param>"boost.doxygen.reftitle=Boost.mylibrary C++ Reference"
</pre>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ AutoIndex knows nothing of the XML <code class="computeroutput"><span class="identifier">xinclude</span></code>
+ element, so if you're writing raw Docbook XML then you may want to run this
+ through an XSL processor to flatten everything to one XML file before passing
+ to AutoIndex. If you're using Boostbook or quickbook though, this all happens
+ for you anyway, and AutoIndex will index the whole document including any
+ sections included with <code class="computeroutput"><span class="identifier">xinclude</span></code>.
+ </p></td></tr>
+</table></div>
<p>
If you are using auto-index's internal index generation on
</p>
@@ -556,7 +573,7 @@
<xsl:param>index.on.type=1
</pre>
<a name="autoindex.tut.step_4__create_the_script_file____to_control_what_to_terms_to_index"></a><h5>
-<a name="id861903"></a>
+<a name="id1001337"></a>
<a class="link" href="tut.html#autoindex.tut.step_4__create_the_script_file____to_control_what_to_terms_to_index">Step
4: Create the script file - to control what to terms to index</a>
</h5>
@@ -566,9 +583,9 @@
<p>
If your document contains largely text, and only a small amount of simple C++,
and/or if you are using Doxygen to provide a C++ Reference section (that lists
- the C++ elements), and/or if you are relying the indexinf provided from a Standalone
- Doxygen Index, you may decide that a index is not needed and that you may only
- want the text part indexed.
+ the C++ elements), and/or if you are relying on the indexing provided from
+ a Standalone Doxygen Index, you may decide that a index is not needed and that
+ you may only want the text part indexed.
</p>
<p>
But if you want C++ classes functions, typedefs and/or macros AutoIndexed,
@@ -603,7 +620,8 @@
<th align="left">Caution</th>
</tr>
<tr><td align="left" valign="top"><p>
- The second <span class="emphasis"><em>file-name-regex</em></span> argument is a regular expression!
+ The second <span class="emphasis"><em>file-name-regex</em></span> argument is a regular expression
+ and not a filename GLOB!
</p></td></tr>
</table></div>
<div class="caution"><table border="0" summary="Caution">
@@ -613,13 +631,15 @@
</tr>
<tr><td align="left" valign="top"><p>
The scan-path is modified by any setting of <auto-index-prefix>. The
- examples here assume that this is <code class="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">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.
+ examples here assume that this is [=<auto-index-prefix>..<span class="emphasis"><em>..</em></span>..
</p></td></tr>
</table></div>
<p>
+ so that <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mylibrary</span></code> will be your header files, <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">mylibrary</span><span class="special">/</span><span class="identifier">doc</span></code> will
+ contain your documentation files and <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">mylibrary</span><span class="special">/</span><span class="identifier">example</span></code>
+ will contain your examples. ]
+ </p>
+<p>
You could also scan any examples (.cpp) files, typically in folder <code class="computeroutput"><span class="special">\/</span><span class="identifier">mylibrary</span><span class="special">\/</span><span class="identifier">lib</span><span class="special">\/</span><span class="identifier">example</span></code>.
</p>
<pre class="programlisting"># All example source files, assuming no sub-folders.
@@ -675,17 +695,8 @@
</p>
<pre class="programlisting"><span class="special">!</span><span class="identifier">rewrite</span><span class="special">-</span><span class="identifier">name</span> <span class="string">"(?i)(?:A|The)\s+(.*)"</span> <span class="string">"\1"</span>
</pre>
-<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).
- </p>
-<p>
- 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="id862346"></a>
+<a name="id1001751"></a>
<a class="link" href="tut.html#autoindex.tut.step_5__add_manual_index_entries_to_docbook_xml___optional">Step
5: Add Manual Index Entries to Docbook XML - Optional</a>
</h5>
@@ -704,17 +715,11 @@
"type" attribute.
</p>
<a name="autoindex.tut.step_6__build_the_docs"></a><h5>
-<a name="id862467"></a>
+<a name="id1001872"></a>
<a class="link" href="tut.html#autoindex.tut.step_6__build_the_docs">Step 6: Build the Docs</a>
</h5>
<p>
- 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 <code class="computeroutput"><span class="keyword">auto</span><span class="special">-</span><span class="identifier">index</span><span class="special">.</span><span class="identifier">jam</span></code>
- file into <code class="computeroutput"><span class="identifier">boost</span><span class="special">-</span><span class="identifier">root</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">build</span><span class="special">/</span><span class="identifier">v2</span><span class="special">/</span><span class="identifier">tools</span></code>.
- </p>
-<p>
- Then you build the docs with either:
+ Using Boost.Build you build the docs with either:
</p>
<pre class="programlisting"><span class="identifier">bjam</span> <span class="identifier">release</span> <span class="special">></span> <span class="identifier">mylibrary_html</span><span class="special">.</span><span class="identifier">log</span>
</pre>
@@ -743,11 +748,11 @@
</p>
<p>
Examine the log file, and if the cause is not obvious, make sure that you have
- <code class="literal"><auto-index-verbose>on</code> and that <code class="literal">!debug regular-expression
- directive</code> is at the head of the script file.
+ <code class="literal"><auto-index-verbose>on</code> and that any needed <code class="literal">!debug
+ regular-expression</code> directives are in your script file.
</p>
<a name="autoindex.tut.step_7__iterate___to_refine_your_index"></a><h5>
-<a name="id862661"></a>
+<a name="id1002000"></a>
<a class="link" href="tut.html#autoindex.tut.step_7__iterate___to_refine_your_index">Step 7:
Iterate - to refine your index</a>
</h5>
@@ -772,7 +777,7 @@
next iteration examined, and so on.
</p>
<a name="autoindex.tut.restricting_which_sections_are_indexed_for_a_particular_term"></a><h5>
-<a name="id863849"></a>
+<a name="id1002048"></a>
<a class="link" href="tut.html#autoindex.tut.restricting_which_sections_are_indexed_for_a_particular_term">Restricting
which Sections are indexed for a particular term</a>
</h5>
@@ -814,7 +819,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="workflow.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="script_ref.html"><img src="../images/next.png" alt="Next"></a>
</div>
</body>
</html>
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-02-04 13:51:10 EST (Fri, 04 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="script_ref.html" title="Script File Reference">
+<link rel="prev" href="workflow.html" title="Understanding The AutoIndex Workflow">
<link rel="next" href="comm_ref.html" title="Command Line Reference">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="script_ref.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="comm_ref.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="comm_ref.html"><img src="../images/next.png" alt="Next"></a>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -52,7 +52,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="script_ref.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="comm_ref.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="comm_ref.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-04 13:51:10 EST (Fri, 04 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="id850903"></a><p>
+<a name="id992083"></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,15 +34,24 @@
<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">Understanding The AutoIndex Workflow</span></dt>
<dt><span class="section">XML Handling</span></dt>
<dt><span class="section">Command Line Reference</span></dt>
</dl>
</div>
+<p>
+ </p>
+<div class="index">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="id1004467"></a>Index</h2></div></div></div>
+<div class="index"></div>
+</div>
+<p>
+ </p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><p><small>Last revised: February 03, 2011 at 15:56:16 GMT</small></p></td>
+<td align="left"><p><small>Last revised: February 04, 2011 at 18:44:11 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