Fix missing online help docs, and refactor to not use header scanning to speed up the parsing of Jamfiles for docs.

[SVN r33746]

src/build-system.jam

@@ -26,7 +26,6 @@ import "class" : new ;
 import builtin ;
 import make ;
 import os ;
-import option ;
 
 import version ;
 
@@ -141,8 +140,6 @@ if --version in [ modules.peek : ARGV ]
 }
 
 
-option.process ;
-
 
 # We always load project in "." so that 'use-project' directives has
 # any chance of been seen. Otherwise, we won't be able to refer to

src/build/project.jam

@@ -204,7 +204,7 @@ JAMFILE ?= [Bb]uild.jam [Jj]amfile.v2 [Jj]amfile [Jj]amfile.jam ;
 # causes this to search not the given directory but the ones above it up
 # to the directory given in it.
 #
-local rule find-jamfile (
+rule find-jamfile (
     dir # The directory(s) to look for a Jamfile.
     parent-root ? # Optional flag indicating to search for the parent Jamfile.
     : no-errors ?

src/kernel/bootstrap.jam

@@ -1,5 +1,5 @@
 # (C) Copyright David Abrahams, 2001.
-# (C) Copyright Rene Rivera, 2003.
+# (C) Copyright Rene Rivera, 2003 2006.
 #
 # See accompanying license for terms and conditions of use.
 #
@@ -112,11 +112,23 @@ IMPORT modules : import : : import ;
 #
 import modules ;
 
-# Allow users to override the build system file from the
-# command-line (mostly for testing)
-local build-system = [ MATCH --build-system=(.*) : $(ARGV) ] ;
-build-system ?= build-system ;
+# Process option plugins first to alow them to prevent loading
+# the rest of the build system.
+#
+import option ;
+local dont-build = [ option.process ] ;
 
-# Use last element in case of multiple command-line options
-import $(build-system[-1]) ;
+# Should we skip building, i.e. loding the build system, according
+# to the options processed?
+#
+if ! $(dont-build)
+{
+    # Allow users to override the build system file from the
+    # command-line (mostly for testing)
+    local build-system = [ MATCH --build-system=(.*) : $(ARGV) ] ;
+    build-system ?= build-system ;
+
+    # Use last element in case of multiple command-line options
+    import $(build-system[-1]) ;
+}
 

src/options/help.jam

@@ -13,6 +13,7 @@ import sequence ;
 import set ;
 import project ;
 import print ;
+import os ;
 
 
 # List of possible modules, but which really aren't.
@@ -57,37 +58,36 @@ rule process (
             local module-files = [ GLOB $(path-to-modules) : $(m)\\.jam ] ;
             modules-to-scan += $(module-files[1]) ;
         }
-        do-scan $(modules-to-scan[1--2]) ;
-        do-scan $(modules-to-scan[-1]) : print-help-all ;
+        do-scan $(modules-to-scan) : print-help-all ;
         did-help = true ;
-        
+
         case --help-enable-* :
         local option = [ MATCH --help-enable-(.*) : $(command) ] ; option = $(option:L) ;
         set-option $(option) : enabled ;
         did-help = true ;
-        
+
         case --help-disable-* :
         local option = [ MATCH --help-disable-(.*) : $(command) ] ; option = $(option:L) ;
         set-option $(option) ;
         did-help = true ;
-        
+
         case --help-output :
         set-output $(values[1]) ;
         did-help = true ;
-        
+
         case --help-output-file :
         set-output-file $(values[1]) ;
         did-help = true ;
-        
+
         case --help-options :
         local doc-module-spec = [ split-symbol doc ] ;
         do-scan $(doc-module-spec[1]) : print-help-options ;
         did-help = true ;
-               
+
         case --help-usage :
         print-help-usage ;
         did-help = true ;
-        
+
         case --help :
         local spec = $(values[1]) ;
         if $(spec)
@@ -114,25 +114,38 @@ rule process (
         else
         {
             # First print documentation from the current Jamfile, if any.
-            if [ project.find "." : "." ] 
+            local project-file =
+                [ project.find-jamfile . : no-error ]
+                [ project.find-jamfile . parent : no-error ] ;
+            for local p in $(project-file)
             {
-                local m = [ project.load "." ] ;
-                local help = [ modules.peek $(m) : project-help ] ;
-                if $(help)
-                {
-                    print.text "Project-specific help" ;
-                    print.text "" ;
-                    print.text $(help) ;                    
-                }                
+                do-scan $(p) : print-help-project $(p) ;
             }
             
-            print-help-top ;                                  
+            # Next any user-config help.
+            local user-path = [ os.home-directories ] [ os.environ BOOST_BUILD_PATH ] ;
+            local user-config = [ GLOB $(user-path) : user-config.jam ] ;
+            if $(user-config)
+            {
+                do-scan $(user-config[1]) : print-help-config user $(user-config[1]) ;
+            }
+            
+            # Next any site-config help.
+            local site-config = [ GLOB $(user-path) : site-config.jam ] ;
+            if $(site-config)
+            {
+                do-scan $(site-config[1]) : print-help-config site $(site-config[1]) ;
+            }
+
+            # Then the overall help.
+            print-help-top ;
         }
         did-help = true ;
     }
     if $(did-help)
     {
         UPDATE all ;
+        NOCARE all ;
     }
     return $(did-help) ;
 }
@@ -153,11 +166,11 @@ local rule split-symbol (
         local module-path = [ GLOB $(path-to-modules) : $(module-name)\\.jam ] ;
         if $(module-path)
         {
-            # The 'module-name' in fact refers to module. Return the full 
-            # module path and a symbol within it. If 'symbol' passed to this 
-            # rule is already module, 'symbol-name' will be empty. Otherwise, 
-            # it's initialized on the previous loop iteration. 
-            # In case there are several modules by this name, 
+            # The 'module-name' in fact refers to module. Return the full
+            # module path and a symbol within it. If 'symbol' passed to this
+            # rule is already module, 'symbol-name' will be empty. Otherwise,
+            # it's initialized on the previous loop iteration.
+            # In case there are several modules by this name,
             # use the first one.
             result = $(module-path[1]) $(symbol-name) ;
         }

src/util/doc.jam

@@ -570,6 +570,41 @@ local rule print-help-variables (
     }
 }
 
+# Generate documentation for a project.
+#
+local rule print-help-project (
+    unused ?
+    : jamfile * # The project Jamfile.
+    )
+{
+    if $(jamfile<$(jamfile)>.docs[1])
+    {
+        # Print the docs.
+        print.section "Project-specific help"
+            Project has jamfile at $(jamfile) ;
+        
+        print.lines $(jamfile<$(jamfile)>.docs) "" ;
+    }
+}
+
+# Generate documentation for a config file.
+#
+local rule print-help-config (
+    unused ?
+    : type # The type of configuration file user or site.
+    config-file # The configuration Jamfile.
+    )
+{
+    if $(jamfile<$(config-file)>.docs[1])
+    {
+        # Print the docs.
+        print.section "Configuration help"
+            Configuration file at $(config-file) ;
+        
+        print.lines $(jamfile<$(config-file)>.docs) "" ;
+    }
+}
+
 local rule __test__
 {
 }
@@ -808,11 +843,11 @@ local rule scan-class (
 rule scan-module (
     target # The module file.
     : text * # The text in the file, one item per line.
-    : binding
+    : action * # Rule to call to output docs for the module.
     )
-{    
+{
     if $(.option.debug) { ECHO "HELP:" scanning module target '$(target)' ; }
-    local module-name = $(.module<$(target)>.name) ;
+    local module-name = $(target:B) ;
     local module-documented = ;
     local comment-block = ;
     local syntax-block = ;
@@ -836,6 +871,12 @@ rule scan-module (
             # mark as the copy for the module.
             set-module-copyright $(module-name) : $(comment-block) ;
         }
+        else if $(action[1]) in "print-help-project" "print-help-config"
+            && ! $(jamfile<$(target)>.docs[1])
+        {
+            # special module docs for the project jamfile.
+            jamfile<$(target)>.docs = $(comment-block) ;
+        }
         else if ! $(module-documented)
         {
             # document the module.
@@ -843,11 +884,9 @@ rule scan-module (
             module-documented = true ;
         }
     }
-    for local action in $(.module<$(target)>.actions)
+    if $(action)
     {
-        local action-rule = [ $(action).front ] ; $(action).pop-front ;
-        local action-args = [ $(action).get ] ;
-        local ignored = [ $(action-rule) $(module-name) : $(action-args) ] ;
+        $(action[1]) $(module-name) : $(action[2-]) ;
     }
 }
 
@@ -855,6 +894,38 @@ rule scan-module (
 # header scanning phase.
 IMPORT $(__name__) : scan-module : : doc.scan-module ;
 
+# Read in a file using the SHELL builtin and return the
+# individual lines as would be done for header scanning.
+#
+local rule read-file (
+    file # The file to read in.
+    )
+{
+    if ! $(.file<$(file)>.lines)
+    {
+        local content ;
+        switch [ modules.peek : OS ]
+        {
+            case NT :
+            content = [ SHELL "TYPE \"$(file)\"" ] ;
+
+            case * :
+            content = [ SHELL "cat \"$(file)\"" ] ;
+        }
+        local lines ;
+        local nl = "
+" ;
+        local << = "([^$(nl)]*)[$(nl)](.*)" ;
+        local line+ = [ MATCH "$(<<)" : "$(content)" ] ;
+        while $(line+)
+        {
+            lines += $(line+[1]) ;
+            line+ = [ MATCH "$(<<)" : "$(line+[2])" ] ;
+        }
+        .file<$(file)>.lines = $(lines) ;
+    }
+    return $(.file<$(file)>.lines) ;
+}
 
 # Add a scan action to perform to generate the help documentation.
 # The action rule is passed the name of the module as the first argument.
@@ -866,38 +937,21 @@ local rule do-scan (
     : action * # The action rule, plus the secondary arguments to pass to the action rule.
     )
 {
-    local targets = ;
-    for local module-file in $(modules)
-    {
-        local module-name = $(module-file:B) ;
-        .module<$(module-file)>.name = $(module-name) ;
-        if $(action)
-        {
-            .module<$(module-file)>.actions += [ class.new vector $(action) ] ;
-        }
-        HDRSCAN on $(module-file) = "^(.*).$" ;
-        HDRRULE on $(module-file) = doc.scan-module ;
-        NOTFILE $(module-name).scan ;
-        ALWAYS $(module-name).scan ;
-        INCLUDES $(module-name).scan : $(module-file) ;
-        targets += $(module-name).scan ;
-    }
-    if $(help-output) = console
-    {
-        DEPENDS all : $(targets) ;
-    }
     if $(help-output) = text
     {
         print.output $(help-output-file).txt plain ;
         ALWAYS $(help-output-file).txt ;
-        DEPENDS $(help-output-file).txt : $(targets) ;
         DEPENDS all : $(help-output-file).txt ;
     }
     if $(help-output) = html
     {
         print.output $(help-output-file).html html ;
         ALWAYS $(help-output-file).html ;
-        DEPENDS $(help-output-file).html : $(targets) ;
         DEPENDS all : $(help-output-file).html ;
     }
+    for local module-file in $(modules[1--2])
+    {
+        scan-module $(module-file) : [ read-file $(module-file) ] ;
+    }
+    scan-module $(modules[-1]) : [ read-file $(modules[-1]) ] : $(action) ;
 }

src/util/option.jam

@@ -88,11 +88,6 @@ rule process ( )
         }
     }
 
-    if $(dont-build)
-    {
-        # Exit without printing "don't know how to build..." and "found 1 target"
-        # messages.
-        EXIT ;
-    }    
+    return $(dont-build) ;
 }