Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r68624 - in sandbox/tools/auto_index/doc: . html html/autoindex
From: pbristow_at_[hidden]
Date: 2011-02-03 10:58:43

Author: pbristow
Date: 2011-02-03 10:58:41 EST (Thu, 03 Feb 2011)
New Revision: 68624
URL: http://svn.boost.org/trac/boost/changeset/68624

Log:
Examples and cosmetic improvements
Binary files modified:
   sandbox/tools/auto_index/doc/auto_index.pdf
Text files modified:
   sandbox/tools/auto_index/doc/auto_index.qbk | 131 ++++++++++++++++++++++++---------
   sandbox/tools/auto_index/doc/html/autoindex/script_ref.html | 158 ++++++++++++++++++++++++++++++---------
   sandbox/tools/auto_index/doc/html/autoindex/tut.html | 48 +++++++----
   sandbox/tools/auto_index/doc/html/index.html | 4
   4 files changed, 249 insertions(+), 92 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-03 10:58:41 EST (Thu, 03 Feb 2011)
@@ -15,6 +15,8 @@
[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 __DOM [@http://en.wikipedia.org/wiki/Document_Object_Model Document Object Model]]
+
[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]]
@@ -437,16 +439,28 @@

[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.
+AutoIndex works by reading a script file that tells it what terms to index.
+
+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.
+
+But if you want C++ classes functions, typedefs and/or macros AutoIndexed,
+optionally, the script file also tells which other C++ files to scan.
+
At its simplest, it will scan one or more headers for terms that
should be indexed in the documentation. So for example to scan
"myheader.hpp" the script file would just contain:

 !scan myheader.hpp
+ !scan mydetailsheader.hpp

-Or, more likely in practice,
+Or, more likely in practice, so
we can recursively scan through directories looking for all
-the files to scan whose name matches a particular regular expression:
+the files to scan whose [*name matches a particular regular expression]:

[pre !scan-path "boost\/mylibrary" ".*\.hpp" true ]

@@ -594,7 +608,7 @@
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.*"
+ Kelvin "" ".*introduction.*"

to the script file,
assuming that the section ID of the intro is "some_library_or_chapter_name.introduction".
@@ -608,7 +622,6 @@

[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.
@@ -623,23 +636,23 @@
 (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.
+# 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 paragraph level
+ 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),
+# 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.
+# Also the tool's internal index gets updated. TODO Which tool? <<<<<<<<<<<<<<<<<<<

# 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.
+ 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
@@ -654,52 +667,98 @@

[h4 Comments and blank lines]

-Blank lines consisting of only whitespace are ignored, so are lines that [*start with] a '#'.
+Blank lines consisting of only whitespace are ignored, so are lines that [*start with a #].
(But, of course, you can't append \# comments onto the end of a line!).

-[h4 Simple Inclusions]
+[h4 Inclusion of Index terms]

 term [regular-expression1 [regular-expression2 [category]]]

[variablelist
-[[term][The term to index: this will form a primary entry in the Index
+[[term][['Term to index.][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 term occurs in.]]
+titles that the index term occurs in.]
+] [/term]

-[[regular-expression1][An optional regular expression: each occurrence
+[[regular-expression1][['Index term Searcher.][br]
+An optional regular expression: each occurrence
of the regular expression in the text of the document will result
-in one index term being emitted.
+in one index index term being emitted.

-If the regular expression is omitted or is "", then the ['term] itself
+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
-['term] will be indexed.]]
+['index term] will be indexed.
+
+For example:
+
+``foobar``
+
+will index occurrences of "foobar" in any section, but
+
+``foobar \<\w*(foo|bar)\w*\>``
+
+will index any whole word containing either "foo" or "bar" within it.
+This is useful when you want to index a lot of similar or related words under one entry.
+
+``reflex``
+
+will only index occurrences of "reflex" as a whole word, but:
+
+``reflex \<reflex\w*\>``

-[[regular-expression2][A constraint that specifies which sections are
+will index occurrences of "reflex", "reflexes", "reflexing" and "reflexed" ...
+all under the same entry reflex.
+
+You will very often need to use this to deal with plurals and other variants.]
+] [/regular-expression1]
+
+[[regular-expression2]
+[['Section(s) Selector.][br]
+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 ['term].
+['regular-expression2] exactly will that section be indexed
+for occurrences of ['index term].

-For example:
+For example, to limit indexing to just [*one specific section] (but not sub-sections below):

- `myclass "" "mylib.examples.*"`
-
-Will index occurrences of "myclass" as a whole word only in sections
-whose ID begins "mylib.examples", while:
+``myclass "" "mylib.examples"``

- `myclass "" "(?!mylib.introduction.*).*"`
+
+For example, to limit indexing to specific sections, [*and sub-sections below]:
+
+``myclass "" "mylib.examples.*"``

-will index occurrences of "myclass" in any section, except those whose
-ID's begin "mylib.introduction".
+will index occurrences of "myclass" as a whole word,
+but only in sections whose section ID [*begins] "mylib.examples",

-If this field is omitted or is "", then all sections are indexed for this term.]]
+``myclass "\<myclass\w*\>" "mylib.examples.*"``

-[[category][Optionally an index category to place occurrences of
-['term] in. If you have multiple indexes then this is the name
-assigned to the indexes "type" attribute.
-]]
+and will also index plurals myclass, myclasses, myclasss ...

+while:
+
+``myclass "" "(?!mylib.introduction.*).*"``
+
+will index occurrences of "myclass" in any section,
+except those whose section IDs begin "mylib.introduction".
+
+``reflex "\<reflex\w*\>" "mylib.introduction.*"``
+
+If this third section selection field is omitted (the default)
+or is "", then [*all sections] are indexed for this term.
]
+] [/regular-expression2]
+
+[[category][['Index Category.][br]
+Optionally an 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]
+
+] [/variablelist]

[h4 Source File Scanning]

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-03 10:58:41 EST (Thu, 03 Feb 2011)
@@ -23,17 +23,18 @@
 The following elements can occur in a script:
 
<a name="autoindex.script_ref.comments_and_blank_lines"></a><h5>
-<a name="id874964"></a>
+<a name="id864035"></a>
 <a class="link" href="script_ref.html#autoindex.script_ref.comments_and_blank_lines">Comments and
 blank lines</a>
 </h5>

- Blank lines consisting of only whitespace are ignored, so are lines that start with a '#'. (But, of course, you can't append
- # comments onto the end of a line!).
+ Blank lines consisting of only whitespace are ignored, so are lines that start with a #. (But, of course, you can't append #
+ comments onto the end of a line!).
 
-<a name="autoindex.script_ref.simple_inclusions"></a><h5>
-<a name="id874986"></a>
- <a class="link" href="script_ref.html#autoindex.script_ref.simple_inclusions">Simple Inclusions</a>
+<a name="autoindex.script_ref.inclusion_of_index_terms"></a><h5>
+<a name="id864056"></a>
+ <a class="link" href="script_ref.html#autoindex.script_ref.inclusion_of_index_terms">Inclusion of
+ Index terms</a>
 </h5>
<pre class="programlisting">term [regular-expression1 [regular-expression2 [category]]]
</pre>
@@ -42,64 +43,147 @@
<dl>
<dt>term</dt>
<dd>
- The term to index: this will form a primary entry in the Index with the
- section title(s) containing the term as secondary entries, and also will
- be used as a secondary entry beneath each of the section titles that
- the term occurs in.
+ 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.
 </dd>
<dt>regular-expression1</dt>
<dd>

- An optional regular expression: each occurrence of the regular expression
- in the text of the document will result in one index term being emitted.
+ 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.
 

- If the regular expression is omitted or is "", then the term
- itself will be used as the search text - and only occurrence of whole
- words matching term will be indexed.
+ 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 index term
+ will be indexed.
+ 
+
+ For example:
+ 
+
+
+
+<pre class="programlisting">foobar</pre>
+
+ 
+
+ will index occurrences of "foobar" in any section, but
+ 
+
+
+
+<pre class="programlisting">foobar \<\w*(foo|bar)\w*\></pre>
+
+ 
+
+ will index any whole word containing either "foo" or "bar"
+ within it. This is useful when you want to index a lot of similar or
+ related words under one entry.
+ 
+
+
+
+<pre class="programlisting">reflex</pre>
+
+ 
+
+ will only index occurrences of "reflex" as a whole word, but:
+ 
+
+
+
+<pre class="programlisting">reflex \<reflex\w*\></pre>
+
+ 
+
+ will index occurrences of "reflex", "reflexes", "reflexing"
+ and "reflexed" ... all under the same entry reflex.
+ 
+
+ You will very often need to use this to deal with plurals and other variants.
 
</dd>
<dt>regular-expression2</dt>
<dd>

- 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 term.
+ 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 example:
+ For example, to limit indexing to just one specific
+ section (but not sub-sections below):
 

- <code class="computeroutput">myclass ""
- "mylib.examples.*"</code>
+
+
+<pre class="programlisting">myclass "" "mylib.examples"</pre>
+
 

- Will index occurrences of "myclass" as a whole word only in
- sections whose ID begins "mylib.examples", while:
+ For example, to limit indexing to specific sections, and
+ sub-sections below:
 

- <code class="computeroutput">myclass ""
- "(?!mylib.introduction.*).*"</code>
+
+
+<pre class="programlisting">myclass "" "mylib.examples.*"</pre>
+
+ 
+
+ will index occurrences of "myclass" as a whole word, but only
+ in sections whose section ID begins
+ "mylib.examples",
+ 
+
+
+
+<pre class="programlisting">myclass "\<myclass\w*\>" "mylib.examples.*"</pre>
+
+ 
+
+ and will also index plurals myclass, myclasses, myclasss ...
+ 
+
+ while:
+ 
+
+
+
+<pre class="programlisting">myclass "" "(?!mylib.introduction.*).*"</pre>
+
 

 will index occurrences of "myclass" in any section, except
- those whose ID's begin "mylib.introduction".
+ those whose section IDs begin "mylib.introduction".
+ 
+
+
+
+<pre class="programlisting">reflex "\<reflex\w*\>" "mylib.introduction.*"</pre>
+
 

- If this field is omitted or is "", then all sections are indexed
- for this term.
+ If this third section selection field is omitted (the default) or is
+ "", then all sections are
+ indexed for this term.
 
</dd>
<dt>category</dt>
<dd>
- Optionally an index category to place occurrences of term
- in. If you have multiple indexes then this is the name assigned to the
- indexes "type" attribute.
+ Index Category. Optionally an to place occurrences
+ of index term in. If you have multiple indexes then
+ this is the name assigned to the indexes "type" attribute.
 </dd>
</dl>
</div>
<a name="autoindex.script_ref.source_file_scanning"></a><h5>
-<a name="id875195"></a>
+<a name="id864493"></a>
 <a class="link" href="script_ref.html#autoindex.script_ref.source_file_scanning">Source File Scanning</a>
 </h5>
<pre class="programlisting">!scan source-file-name
@@ -128,7 +212,7 @@
 </td></tr>
</table></div>
<a name="autoindex.script_ref.directory_and_source_file_scanning"></a><h5>
-<a name="id875273"></a>
+<a name="id864571"></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 +241,7 @@
</dl>
</div>
<a name="autoindex.script_ref.excluding_terms"></a><h5>
-<a name="id875398"></a>
+<a name="id864696"></a>
 <a class="link" href="script_ref.html#autoindex.script_ref.excluding_terms">Excluding Terms</a>
 </h5>
<pre class="programlisting">!exclude term-list
@@ -170,7 +254,7 @@
 of things to index.
 
<a name="autoindex.script_ref.rewriting_section_names"></a><h5>
-<a name="id875453"></a>
+<a name="id864751"></a>
 <a class="link" href="script_ref.html#autoindex.script_ref.rewriting_section_names">Rewriting Section
 Names</a>
 </h5>
@@ -217,7 +301,7 @@
 all index entries - thus preventing lots of entries under "The" etc!
 
<a name="autoindex.script_ref.defining_or_changing_the_file_scanners"></a><h5>
-<a name="id875605"></a>
+<a name="id864904"></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 +404,7 @@
 scanner may find in the documentation.
 
<a name="autoindex.script_ref.debugging_scanning"></a><h5>
-<a name="id876108"></a>
+<a name="id865406"></a>
 <a class="link" href="script_ref.html#autoindex.script_ref.debugging_scanning">Debugging scanning</a>
 </h5>

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-03 10:58:41 EST (Thu, 03 Feb 2011)
@@ -20,7 +20,7 @@
<a name="autoindex.tut"></a><a class="link" href="tut.html" title="Getting Started and Tutorial">Getting Started and Tutorial</a>
</h2></div></div></div>
<a name="autoindex.tut.step_1__build_the_autoindex_tool"></a><h5>
-<a name="id871627"></a>
+<a name="id860648"></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 @@
 </td></tr>
</table></div>
<a name="autoindex.tut.step_2__configure_boost_build_to_use_autoindex"></a><h5>
-<a name="id871889"></a>
+<a name="id860909"></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>
@@ -438,7 +438,7 @@
 </td></tr>
</table></div>
<a name="autoindex.tut.step_3__add_indexes_to_your_documentation"></a><h5>
-<a name="id872532"></a>
+<a name="id861552"></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>
@@ -556,21 +556,36 @@
 <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="id872883"></a>
+<a name="id861903"></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>

- AutoIndex works by reading a script file that tells it what to index. At its
- simplest, it will scan one or more headers for terms that should be indexed
- in the documentation. So for example to scan "myheader.hpp" the script
- file would just contain:
+ AutoIndex works by reading a script file that tells it what terms to index.
+ 
+
+ 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.
+ 
+
+ But if you want C++ classes functions, typedefs and/or macros AutoIndexed,
+ optionally, the script file also tells which other C++ files to scan.
+ 
+
+ At its simplest, it will scan one or more headers for terms that should be
+ indexed in the documentation. So for example to scan "myheader.hpp"
+ the script file would just contain:
 
<pre class="programlisting">!scan myheader.hpp
+!scan mydetailsheader.hpp
</pre>

- 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:
+ Or, more likely in practice, so we can recursively scan through directories
+ looking for all the files to scan whose name matches
+ a particular regular expression:
 
<pre class="programlisting">!scan-path "boost/mylibrary" ".*.hpp" true </pre>

@@ -670,7 +685,7 @@
 output is appended as a comment, then this text will also be scanned.
 
<a name="autoindex.tut.step_5__add_manual_index_entries_to_docbook_xml___optional"></a><h5>
-<a name="id873289"></a>
+<a name="id862346"></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 +704,7 @@
 "type" attribute.
 
<a name="autoindex.tut.step_6__build_the_docs"></a><h5>
-<a name="id873411"></a>
+<a name="id862467"></a>
 <a class="link" href="tut.html#autoindex.tut.step_6__build_the_docs">Step 6: Build the Docs</a>
 </h5>

@@ -732,7 +747,7 @@
 directive</code> is at the head of the script file.
 
<a name="autoindex.tut.step_7__iterate___to_refine_your_index"></a><h5>
-<a name="id873605"></a>
+<a name="id862661"></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>
@@ -757,7 +772,7 @@
 next iteration examined, and so on.
 
<a name="autoindex.tut.restricting_which_sections_are_indexed_for_a_particular_term"></a><h5>
-<a name="id873653"></a>
+<a name="id863849"></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>
@@ -772,9 +787,8 @@
 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."
- 
+<pre class="programlisting">Kelvin "" ".*introduction.*"
+</pre>

 to the script file, assuming that the section ID of the intro is "some_library_or_chapter_name.introduction".

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-03 10:58:41 EST (Thu, 03 Feb 2011)
@@ -21,7 +21,7 @@
</h3></div></div></div>
<div>Copyright © 2008 , 2011 John Maddock</div>
<div><div class="legalnotice">
-<a name="id861809"></a>
+<a name="id850903"></a>
 Distributed under the Boost Software License, Version 1.0. (See accompanying
 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
@@ -42,7 +42,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left">Last revised: February 01, 2011 at 17:38:04 GMT</td>
+<td align="left">Last revised: February 03, 2011 at 15:56:16 GMT</td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk