From 8336f4d09943fadeff733a3da99c1d0a5ae237e6 Mon Sep 17 00:00:00 2001 From: John Maddock Date: Fri, 21 Nov 2008 18:21:43 +0000 Subject: [PATCH] Update docs, add build Jamfile. [SVN r49860] --- build/Jamfile.v2 | 11 ++ doc/auto_index.qbk | 129 +++++++++++++++++++++- doc/html/autoindex/comm_ref.html | 42 +++++++- doc/html/autoindex/script_ref.html | 165 ++++++++++++++++++++++++++++- doc/html/autoindex/tut.html | 27 +++-- doc/html/index.html | 4 +- project-root.jam | 47 ++++++++ 7 files changed, 410 insertions(+), 15 deletions(-) create mode 100644 build/Jamfile.v2 create mode 100644 project-root.jam diff --git a/build/Jamfile.v2 b/build/Jamfile.v2 new file mode 100644 index 0000000..f642122 --- /dev/null +++ b/build/Jamfile.v2 @@ -0,0 +1,11 @@ +import quickbook ; + +exe auto_index : ../src/auto_index.cpp ../src/tiny_xml.cpp /boost/regex /boost/filesystem +: BOOST_ALL_NO_LIB=1 static +; + +install dist : auto_index ; + + + + diff --git a/doc/auto_index.qbk b/doc/auto_index.qbk index fb92b67..af7600e 100644 --- a/doc/auto_index.qbk +++ b/doc/auto_index.qbk @@ -161,9 +161,20 @@ We can also add terms manually: will index occurances of "foobar" and: - foo bar + foobar \<\w*(foo|bar)\w*\> -will index occurances of "foo" under the name "bar". +will index any whole word containing either "foo" or "bar" within it, +this is useful when you want to index a lot of similar or related +words under one entry, for example: + + reflex + +Will only index occurances of "reflex" as a whole word, but: + + reflex \ + +will index occurances of "reflex", reflexing" and +"reflexed" all under the same entry ['reflex]. This inclusion rule can also restict the term to certain sections, and add an index category that @@ -194,10 +205,124 @@ and the next iteration examined, and so on. [section:script_ref Script File Reference] +The following elements can occur in a script: + +[h4 Simple Inclusions] + + term [regular-expression1 [regular-expression2 [category]]] + +[variablelist +[[term][The term to index: this will form a primary entry in the Index +with the section title(s) containing the term as secondary entries, and +also will be used as a secondary entry beneath each of the section +titles that the term occurs in.]] + +[[regular-expression1][An optional regular expression: each occurance +of the regular expression in the text of the document will result +in one index term being emitted. + +If the regular expression is omitted or is "", then the ['term] itself +will be used as the search text - and only occurance of whole words matching +['term] will be indexed.]] + +[[regular-expression2][A constraint that specifies which sections are +indexed for ['term]: only if the ID of the section matches +['regular-expression2] exactly will that section be indexed for occurances +of ['term]. + +For example: + + `myclass "" "mylib.examples.*"` + +Will index occurances of "myclass" as a whole word only in sections +whose ID begins "mylib.examples", while: + + `myclass "" "(?!mylib.introduction.*).*"` + +will index occurances of "myclass" in any section, except those whose +ID's begin "mylib.introduction".]] + +[[category][Optionally an index category to place occurances of +['term] in. If you have multiple indexes then this is the name +assigned to the indexes "type" attribute. +]] + +] + +[h4 Source File Scanning] + + !scan source-file-name + +Scans the C\/C++ source file ['source-file-name] for definitions of +['function]'s, ['class]'s, ['macro]'s or ['typedef]'s and makes each of +these a term to be indexed. Terms found are assigned to the index category +"function_name", "class_name", "macro_name" or "typedef_name" depending +on how they were seen in the source file. These may then be included +in a specialised index whose "type" attribute has the same category name. + +[h4 Directory and Source File Scanning] + + !scan-path directory-name file-name-regex [recurse] + +[variablelist +[[directory-name][The directory to scan: this should be a path relative +to the script file and should use all forward slashes in it's file name.]] + +[[file-name-regex][A regular expression: any file in the directory whose name +matches the regular expression will be scanned for terms to index.]] + +[[recurse][An optional boolian value - either "true" or "false" - that +indicates whether to recurse into subdirectories.]] +] + +[h4 Excluding Terms] + + !exclude term-list + +Excludes all the terms in whitespace separated ['term-list] from being indexed. +This should be placed /after/ any ['!scan] or ['!scan-path] rules which may +result in the terms becoming included. + +[h4 Rewriting Section Names] + + !rewrite-id regular-expression new-name + +[variablelist +[[regular-expression][A regular expression: all section ID's that match +the expression exactly will have index entries ['new-name] instead of +their title(s).]] + +[[new-name][The name that the section will appear under in the index.]] +] + + !rewrite-name regular-expression format-text + +[variablelist +[[regular-expression][A regular expression: all sections whose titles +match the regular expression exactly, will have index entries composed +of the regular expression match combined with the regex format string +['format-text].]] +[[format-text][The Perl-style format string used to reformat the title.]] +] [endsect] [section:comm_ref Command Line Reference] +The following command line options are supported by auto_index: + +[variablelist +[[in=infilename][Specifies the name of the XML input file to be indexed.]] +[[out=outfilename][Specifies the name of the new XML file to create.]] +[[scan=source-filename][Specifies that ['source-filename] should be scanned +for terms to index.]] +[[script=script-filename][Specifies the name of the script file to process.]] +[[--no-duplicates][If a term occurs more than once in the same section, then +include only one index entry.]] +[[--internal-index][Specifies that auto_index should generate the actual +indexes rather than inserting ``'s and leaving index generation +to the XSL stylesheets.]] +] + [endsect] diff --git a/doc/html/autoindex/comm_ref.html b/doc/html/autoindex/comm_ref.html index 93e042f..f492d77 100644 --- a/doc/html/autoindex/comm_ref.html +++ b/doc/html/autoindex/comm_ref.html @@ -21,9 +21,47 @@
PrevUpHome
-
+

+ The following command line options are supported by auto_index: +

+
+

+
+
in=infilename
+

+ Specifies the name of the XML input file to be indexed. +

+
out=outfilename
+

+ Specifies the name of the new XML file to create. +

+
scan=source-filename
+

+ Specifies that source-filename should be scanned for + terms to index. +

+
script=script-filename
+

+ Specifies the name of the script file to process. +

+
--no-duplicates
+

+ If a term occurs more than once in the same section, then include only + one index entry. +

+
--internal-index
+

+ Specifies that auto_index should generate the actual indexes rather than + inserting <indexterm>'s and leaving index generation to the + XSL stylesheets. +

+
+
+
Copyright © 2008 John Maddock

diff --git a/doc/html/autoindex/script_ref.html b/doc/html/autoindex/script_ref.html index 37e5a71..d228f88 100644 --- a/doc/html/autoindex/script_ref.html +++ b/doc/html/autoindex/script_ref.html @@ -22,9 +22,170 @@

PrevUpHomeNext
-
+

+ The following elements can occur in a script: +

+
+ + Simple Inclusions +
+
term [regular-expression1 [regular-expression2 [category]]]
+
+
+

+
+
term
+

+ The term to index: this will form a primary entry in the Index with the + section title(s) containing the term as secondary entries, and also will + be used as a secondary entry beneath each of the section titles that the + term occurs in. +

+
regular-expression1
+
+

+ An optional regular expression: each occurance of the regular expression + in the text of the document will result in one index term being emitted. +

+

+ If the regular expression is omitted or is "", then the term + itself will be used as the search text - and only occurance of whole words + matching term will be indexed. +

+
+
regular-expression2
+
+

+ A constraint that specifies which sections are indexed for term: + only if the ID of the section matches regular-expression2 + exactly will that section be indexed for occurances of term. +

+

+ For example: +

+

+ myclass "" + "mylib.examples.*" +

+

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

+

+ myclass "" + "(?!mylib.introduction.*).*" +

+

+ will index occurances of "myclass" in any section, except those + whose ID's begin "mylib.introduction". +

+
+
category
+

+ Optionally an index category to place occurances of term + in. If you have multiple indexes then this is the name assigned to the + indexes "type" attribute. +

+
+
+
+ + Source File Scanning +
+
!scan source-file-name
+
+

+ Scans the C/C++ source file source-file-name for definitions + of function's, class's, macro's + or typedef's and makes each of these a term to be indexed. + Terms found are assigned to the index category "function_name", "class_name", + "macro_name" or "typedef_name" depending on how they were + seen in the source file. These may then be included in a specialised index + whose "type" attribute has the same category name. +

+
+ + Directory + and Source File Scanning +
+
!scan-path directory-name file-name-regex [recurse]
+
+
+

+
+
directory-name
+

+ The directory to scan: this should be a path relative to the script file + and should use all forward slashes in it's file name. +

+
file-name-regex
+

+ A regular expression: any file in the directory whose name matches the + regular expression will be scanned for terms to index. +

+
recurse
+

+ An optional boolian value - either "true" or "false" + - that indicates whether to recurse into subdirectories. +

+
+
+
+ + Excluding Terms +
+
!exclude term-list
+
+

+ Excludes all the terms in whitespace separated term-list + from being indexed. This should be placed after any !scan + or !scan-path rules which may result in the terms becoming + included. +

+
+ + Rewriting Section + Names +
+
!rewrite-id regular-expression new-name
+
+
+

+
+
regular-expression
+

+ A regular expression: all section ID's that match the expression exactly + will have index entries new-name instead of their + title(s). +

+
new-name
+

+ The name that the section will appear under in the index. +

+
+
+
!rewrite-name regular-expression format-text
+
+
+

+
+
regular-expression
+

+ A regular expression: all sections whose titles match the regular expression + exactly, will have index entries composed of the regular expression match + combined with the regex format string format-text. +

+
format-text
+

+ The Perl-style format string used to reformat the title. +

+
+
+
Copyright © 2008 John Maddock

diff --git a/doc/html/autoindex/tut.html b/doc/html/autoindex/tut.html index e940632..58e3d5a 100644 --- a/doc/html/autoindex/tut.html +++ b/doc/html/autoindex/tut.html @@ -27,7 +27,7 @@ Getting Started and Tutorial

- + Step 1: Build the tool

@@ -42,7 +42,7 @@ 

bjam release gcc
- + Step 2: Configure Boost.Build
@@ -53,7 +53,7 @@ Currently the tool can only be run manually.

- + Step 3: Add indexes to your documentation
@@ -93,7 +93,7 @@ 
'''<index/>'''
- + Step 4: Create the script file
@@ -135,10 +135,23 @@

will index occurances of "foobar" and:

-
foo bar
+
foobar \<\w*(foo|bar)\w*\>
 

 

-      will index occurances of "foo" under the name "bar".
+      will index any whole word containing either "foo" or "bar"
+      within it, this is useful when you want to index a lot of similar or related
+      words under one entry, for example:
+    

+
reflex
+

+

+      Will only index occurances of "reflex" as a whole word, but:
+    

+
reflex \<reflex\w*\>
+

+

+      will index occurances of "reflex", reflexing" and "reflexed"
+      all under the same entry reflex.
     

 

       This inclusion rule can also restict the term to certain sections, and add
@@ -154,7 +167,7 @@
 
!rewrite-name "(?i)(?:A|The)\s+(.*)" "\1"
 

 

-
+
       Step 5: Iterate
     

 

diff --git a/doc/html/index.html b/doc/html/index.html
index 512611c..7c5eb28 100644
--- a/doc/html/index.html
+++ b/doc/html/index.html
@@ -28,7 +28,7 @@
 
 
Copyright © 2008 John Maddock

 

-

+

         Distributed under the Boost Software License, Version 1.0. (See accompanying
         file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
       

@@ -47,7 +47,7 @@
 

 

 
-
+
Last revised: November 21, 2008 at 13:57:27 GMT
Last revised: November 21, 2008 at 17:25:20 GMT

 

 

 

diff --git a/project-root.jam b/project-root.jam
new file mode 100644
index 0000000..a4e1a15
--- /dev/null
+++ b/project-root.jam
@@ -0,0 +1,47 @@
+#
+#   Copyright (c) 2006 JoĆ£o Abecasis
+#
+#   Distributed under the Boost Software License, Version 1.0. (See
+#   accompanying file LICENSE_1_0.txt or copy at
+#   http://www.boost.org/LICENSE_1_0.txt)
+#
+
+##
+##  IMPORTANT NOTE: This file MUST NOT be copied over a boost installation
+##
+
+path-constant top : . ;
+
+import modules ;
+import path ;
+
+local boost-root = [ modules.peek : BOOST_ROOT ] ;
+local math-header-include = $(top)/../.. ;
+
+if ! $(boost-root)
+{
+    local boost-search-dirs = [ modules.peek : BOOST_BUILD_PATH ] ;
+
+    for local dir in $(boost-search-dirs)
+    {
+        if [ path.glob $(dir)/../../../ : boost/version.hpp ]
+        {
+            boost-root += $(dir)/../../../ ;
+        }
+    }
+
+    if $(boost-root)
+    {
+        boost-root = [ path.make $(boost-root[1]) ] ;
+    }
+    else
+    {
+        ECHO "Warning: couldn't find BOOST_ROOT in" $(boost-root) ;
+    }
+}
+
+use-project /boost/regex : $(boost-root)/libs/regex/build ;
+use-project /boost/unit_test : $(boost-root)/libs/test/build ;
+use-project /boost/filesystem : $(boost-root)/libs/filesystem/build ;
+
+