1 # Copyright 2002, 2005 Dave Abrahams
2 # Copyright 2002, 2003, 2006 Rene Rivera
3 # Copyright 2003 Vladimir Prus
4 # Distributed under the Boost Software License, Version 1.0.
5 # (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)
7 # Documentation system, handles --help requests.
8 # It defines rules that attach documentation to modules, rules, and variables.
9 # Collects and generates documentation for the various parts of the build
10 # system. The documentation is collected from comments integrated into the code.
21 # The type of output to generate.
22 # "console" is formated text echoed to the console (the default);
23 # "text" is formated text appended to the output file;
24 # "html" is HTML output to the file.
26 help-output = console ;
29 # The file to output documentation to when generating "text" or "html" help.
30 # This is without extension as the extension is determined by the type of
33 help-output-file = help ;
35 # Whether to include local rules in help output.
37 .option.show-locals ?= ;
39 # When showing documentation for a module, whether to also generate
40 # automatically the detailed docs for each item in the module.
44 # Generate debug output as the help is generated and modules are parsed.
48 # These are all the options available for enabling or disabling to control the
49 # help system in various ways. Options can be enabled or disabled with
50 # '--help-enable-<option>', and '--help-disable-<option>' respectively.
52 .option-description = Help Options ;
54 # Enable or disable a documentation option.
56 local rule set-option (
57 option # The option name.
58 : value ? # Enabled (non-empty), or disabled (empty)
61 .option.$(option) = $(value) ;
65 # Set the type of output.
67 local rule set-output ( type )
69 help-output = $(type) ;
73 # Set the output to a file.
75 local rule set-output-file ( file )
77 help-output-file = $(file) ;
81 # Extracts the brief comment from a complete comment. The brief comment is the
84 local rule brief-comment (
85 docs * # The comment documentation.
88 local d = $(docs:J=" ") ;
89 local p = [ MATCH ".*([.])$" : $(d) ] ;
90 if ! $(p) { d = $(d)"." ; }
92 local m = [ MATCH "^([^.]+[.])(.*)" : $(d) ] ;
93 local brief = $(m[1]) ;
94 while $(m[2]) && [ MATCH "^([^ ])" : $(m[2]) ]
96 m = [ MATCH "^([^.]+[.])(.*)" : $(m[2]) ] ;
99 return $(brief:J="") ;
103 # Specifies the documentation for the current module.
105 local rule set-module-doc (
106 module-name ? # The name of the module to document.
107 : docs * # The documentation for the module.
112 $(module-name).brief = [ brief-comment $(docs) ] ;
113 $(module-name).docs = $(docs) ;
115 if ! $(module-name) in $(documented-modules)
117 documented-modules += $(module-name) ;
122 # Specifies the documentation for the current module.
124 local rule set-module-copyright (
125 module-name ? # The name of the module to document.
126 : copyright * # The copyright for the module.
131 $(module-name).copy-brief = [ brief-comment $(copyright) ] ;
132 $(module-name).copy-docs = $(docs) ;
134 if ! $(module-name) in $(documented-modules)
136 documented-modules += $(module-name) ;
141 # Specifies the documentation for a rule in the current module. If called in the
142 # global module, this documents a global rule.
144 local rule set-rule-doc (
145 name # The name of the rule.
146 module-name ? # The name of the module to document.
147 is-local ? # Whether the rule is local to the module.
148 : docs * # The documentation for the rule.
153 $(module-name).$(name).brief = [ brief-comment $(docs) ] ;
154 $(module-name).$(name).docs = $(docs) ;
155 $(module-name).$(name).is-local = $(is-local) ;
157 if ! $(name) in $($(module-name).rules)
159 $(module-name).rules += $(name) ;
164 # Specify a class, will turn a rule into a class.
166 local rule set-class-doc (
167 name # The name of the class.
168 module-name ? # The name of the module to document.
169 : super-name ? # The super class name.
174 $(module-name).$(name).is-class = true ;
175 $(module-name).$(name).super-name = $(super-name) ;
176 $(module-name).$(name).class-rules =
177 [ MATCH "^($(name)[.].*)" : $($(module-name).rules) ] ;
178 $(module-name).$($(module-name).$(name).class-rules).is-class-rule = true ;
180 $(module-name).classes += $(name) ;
181 $(module-name).class-rules += $($(module-name).$(name).class-rules) ;
182 $(module-name).rules =
183 [ set.difference $($(module-name).rules) :
184 $(name) $($(module-name).$(name).class-rules) ] ;
188 # Set the argument call signature of a rule.
190 local rule set-rule-arguments-signature (
191 name # The name of the rule.
192 module-name ? # The name of the module to document.
193 : signature * # The arguments signature.
198 $(module-name).$(name).signature = $(signature) ;
202 # Specifies the documentation for an argument of a rule.
204 local rule set-argument-doc (
205 name # The name of the argument.
206 qualifier # Argument syntax qualifier, "*", "+", etc.
207 rule-name # The name of the rule.
208 module-name ? # THe optional name of the module.
209 : docs * # The documentation.
214 $(module-name).$(rule-name).args.$(name).qualifier = $(qualifier) ;
215 $(module-name).$(rule-name).args.$(name).docs = $(docs) ;
217 if ! $(name) in $($(module-name).$(rule-name).args)
219 $(module-name).$(rule-name).args += $(name) ;
224 # Specifies the documentation for a variable in the current module. If called in
225 # the global module, the global variable is documented.
227 local rule set-variable-doc (
228 name # The name of the variable.
229 default # The default value.
230 initial # The initial value.
231 module-name ? # The name of the module to document.
232 : docs * # The documentation for the variable.
237 $(module-name).$(name).brief = [ brief-comment $(docs) ] ;
238 $(module-name).$(name).default = $(default) ;
239 $(module-name).$(name).initial = $(initial) ;
240 $(module-name).$(name).docs = $(docs) ;
242 if ! $(name) in $($(module-name).variables)
244 $(module-name).variables += $(name) ;
249 # Generates a general description of the documentation and help system.
251 local rule print-help-top ( )
253 print.section "General command line usage" ;
255 print.text " b2 [options] [properties] [targets]
257 Options, properties and targets can be specified in any order.
260 print.section "Important Options" ;
263 print.list-item "--clean Remove targets instead of building" ;
264 print.list-item "-a Rebuild everything" ;
265 print.list-item "-n Don't execute the commands, only print them" ;
266 print.list-item "-d+2 Show commands as they are executed" ;
267 print.list-item "-d0 Suppress all informational messages" ;
268 print.list-item "-q Stop at first error" ;
269 print.list-item "--reconfigure Rerun all configuration checks" ;
270 print.list-item "--debug-configuration Diagnose configuration" ;
271 print.list-item "--debug-building Report which targets are built with what properties" ;
272 print.list-item "--debug-generator Diagnose generator search/execution" ;
275 print.section "Further Help"
276 The following options can be used to obtain additional documentation.
280 print.list-item "--help-options Print more obscure command line options." ;
281 print.list-item "--help-internal Boost.Build implementation details." ;
282 print.list-item "--help-doc-options Implementation details doc formatting." ;
287 # Generate Jam/Boost.Jam command usage information.
289 local rule print-help-usage ( )
291 print.section "Boost.Build Usage"
292 "b2 [ options... ] targets..."
296 Build all targets, even if they are current. ;
298 Read '"x"' as the Jamfile for building instead of searching for the
299 Boost.Build system. ;
301 Run up to '"x"' commands concurrently. ;
303 Do not execute build commands. Instead print out the commands as they
304 would be executed if building. ;
306 Output the used build commands to file '"x"'. ;
308 Quit as soon as a build failure is encountered. Without this option
309 Boost.Jam will continue building as many targets as it can. ;
310 print.list-item -sx=y;
311 Sets a Jam variable '"x"' to the value '"y"', overriding any value that
312 variable would have from the environment. ;
314 Rebuild the target '"x"', even if it is up-to-date. ;
316 Display the version of b2. ;
318 Any option not explicitly handled by Boost.Build remains available to
319 build scripts using the '"ARGV"' variable. ;
320 print.list-item --abbreviate-paths;
321 Use abbreviated paths for targets. ;
322 print.list-item --hash;
323 Shorten target paths by using an MD5 hash. ;
324 print.list-item -dconsole;
325 Run the interactive debugger. Cannot be used with any other option. ;
327 Enables output of diagnostic messages. The debug level '"n"' and all
328 below it are enabled by this option. ;
329 print.list-item -d+n;
330 Enables output of diagnostic messages. Only the output for debug level
333 print.section "Debug Levels"
334 Each debug level shows a different set of information. Usually with
335 higher levels producing more verbose information. The following levels
339 Turn off all diagnostic output. Only errors are reported. ;
341 Show the actions taken for building targets, as they are executed. ;
343 Show "quiet" actions and display all action text, as they are executed. ;
345 Show dependency analysis, and target/source timestamps/paths. ;
347 Show arguments of shell invocations. ;
349 Show rule invocations and variable expansions. ;
351 Show directory/header file/archive scans, and attempts at binding to targets. ;
353 Show variable settings. ;
355 Show variable fetches, variable expansions, and evaluation of '"if"' expressions. ;
357 Show variable manipulation, scanner tokens, and memory usage. ;
359 Show execution times for rules. ;
361 Show parsing progress of Jamfiles. ;
363 Show graph for target dependencies. ;
365 Show changes in target status (fate). ;
369 # Generates description of options controlling the help system. This
370 # automatically reads the options as all variables in the module given
371 # with the name `module-name` of the form ".option.*".
373 local rule print-help-options (
377 local options-to-list = [ MATCH ^[.]option[.](.*) : $($(module-name).variables) ] ;
378 if $(options-to-list)
380 local option-title = $($(module-name)..option-description.initial) ;
381 if ! $(option-title) || $(option-title) = "(empty)"
383 option-title = "$(module-name) Options" ;
385 local option-description = $(option-title)
386 $($(module-name)..option-description.docs) ;
387 print.section $(option-description) ;
389 for local option in [ sequence.insertion-sort $(options-to-list) ]
391 local def = disabled ;
392 if $($(module-name)..option.$(option).default) != "(empty)"
394 def = $($(module-name)..option.$(option).default) ;
396 print.list-item $(option): $($(module-name)..option.$(option).docs)
404 # Generate brief documentation for all the known items in the section for a
405 # module. Possible sections are: "rules", and "variables".
407 local rule print-help-module-section (
408 module # The module name.
409 section # rules or variables.
410 : section-head # The title of the section.
411 section-description * # The detailed description of the section.
414 if $($(module).$(section))
416 print.section $(section-head) $(section-description) ;
418 for local item in [ sequence.insertion-sort $($(module).$(section)) ]
421 if ! $($(module).$(item).is-local)
425 if $(.option.show-locals)
431 print.list-item $(item): $($(module).$(item).brief) ;
439 # Generate documentation for all possible modules. We attempt to list all known
440 # modules together with a brief description of each.
442 local rule print-help-all (
443 ignored # Usually the module name, but is ignored here.
446 print.section "Modules"
447 "These are all the known modules. Use --help <module> to get more"
448 "detailed information."
450 if $(documented-modules)
453 for local module-name in [ sequence.insertion-sort $(documented-modules) ]
455 # The brief docs for each module.
456 print.list-item $(module-name): $($(module-name).brief) ;
460 # The documentation for each module when details are requested.
461 if $(documented-modules) && $(.option.detailed)
463 for local module-name in [ sequence.insertion-sort $(documented-modules) ]
465 # The brief docs for each module.
466 print-help-module $(module-name) ;
472 # Generate documentation for a module. Basic information about the module is
475 local rule print-help-module (
476 module-name # The module to generate docs for.
480 print.section "Module '$(module-name)'" $($(module-name).docs) ;
482 # Print out the documented classes.
483 print-help-module-section $(module-name) classes : "Module '$(module-name)' classes"
484 Use --help $(module-name).<class-name> to get more information. ;
486 # Print out the documented rules.
487 print-help-module-section $(module-name) rules : "Module '$(module-name)' rules"
488 Use --help $(module-name).<rule-name> to get more information. ;
490 # Print out the documented variables.
491 print-help-module-section $(module-name) variables : "Module '$(module-name)' variables"
492 Use --help $(module-name).<variable-name> to get more information. ;
494 # Print out all the same information but indetailed form.
495 if $(.option.detailed)
497 print-help-classes $(module-name) ;
498 print-help-rules $(module-name) ;
499 print-help-variables $(module-name) ;
504 # Generate documentation for a set of rules in a module.
506 local rule print-help-rules (
507 module-name # Module of the rules.
508 : name * # Optional list of rules to describe.
511 name ?= $($(module-name).rules) ;
512 if [ set.intersection $(name) : $($(module-name).rules) $($(module-name).class-rules) ]
514 # Print out the given rules.
515 for local rule-name in [ sequence.insertion-sort $(name) ]
517 if $(.option.show-locals) || ! $($(module-name).$(rule-name).is-local)
519 local signature = $($(module-name).$(rule-name).signature:J=" ") ;
521 print.section "Rule '$(module-name).$(rule-name) ( $(signature) )'"
522 $($(module-name).$(rule-name).docs) ;
523 if $($(module-name).$(rule-name).args)
526 for local arg-name in $($(module-name).$(rule-name).args)
528 print.list-item $(arg-name): $($(module-name).$(rule-name).args.$(arg-name).docs) ;
538 # Generate documentation for a set of classes in a module.
540 local rule print-help-classes (
541 module-name # Module of the classes.
542 : name * # Optional list of classes to describe.
545 name ?= $($(module-name).classes) ;
546 if [ set.intersection $(name) : $($(module-name).classes) ]
548 # Print out the given classes.
549 for local class-name in [ sequence.insertion-sort $(name) ]
551 if $(.option.show-locals) || ! $($(module-name).$(class-name).is-local)
553 local signature = $($(module-name).$(class-name).signature:J=" ") ;
555 print.section "Class '$(module-name).$(class-name) ( $(signature) )'"
556 $($(module-name).$(class-name).docs)
557 "Inherits from '"$($(module-name).$(class-name).super-name)"'." ;
558 if $($(module-name).$(class-name).args)
561 for local arg-name in $($(module-name).$(class-name).args)
563 print.list-item $(arg-name): $($(module-name).$(class-name).args.$(arg-name).docs) ;
569 # Print out the documented rules of the class.
570 print-help-module-section $(module-name) $(class-name).class-rules : "Class '$(module-name).$(class-name)' rules"
571 Use --help $(module-name).<rule-name> to get more information. ;
573 # Print out all the rules if details are requested.
574 if $(.option.detailed)
576 print-help-rules $(module-name) : $($(module-name).$(class-name).class-rules) ;
583 # Generate documentation for a set of variables in a module.
585 local rule print-help-variables (
586 module-name ? # Module of the variables.
587 : name * # Optional list of variables to describe.
590 name ?= $($(module-name).variables) ;
591 if [ set.intersection $(name) : $($(module-name).variables) ]
593 # Print out the given variables.
594 for local variable-name in [ sequence.insertion-sort $(name) ]
596 print.section "Variable '$(module-name).$(variable-name)'" $($(module-name).$(variable-name).docs) ;
597 if $($(module-name).$(variable-name).default) ||
598 $($(module-name).$(variable-name).initial)
601 if $($(module-name).$(variable-name).default)
603 print.list-item "default value:" '$($(module-name).$(variable-name).default:J=" ")' ;
605 if $($(module-name).$(variable-name).initial)
607 print.list-item "initial value:" '$($(module-name).$(variable-name).initial:J=" ")' ;
616 # Generate documentation for a project.
618 local rule print-help-project (
620 : jamfile * # The project Jamfile.
623 if $(jamfile<$(jamfile)>.docs)
626 print.section "Project-specific help"
627 Project has jamfile at $(jamfile) ;
629 print.lines $(jamfile<$(jamfile)>.docs) "" ;
634 # Generate documentation for a config file.
636 local rule print-help-config (
638 : type # The type of configuration file user or site.
639 config-file # The configuration Jamfile.
642 if $(jamfile<$(config-file)>.docs)
645 print.section "Configuration help"
646 Configuration file at $(config-file) ;
648 print.lines $(jamfile<$(config-file)>.docs) "" ;
655 # Extract the text from a block of comments.
657 local rule extract-comment (
658 var # The name of the variable to extract from.
662 local line = $($(var)[1]) ;
663 local l = [ MATCH "^[$(ws)]*(#)(.*)$" : $(line) ] ;
664 while $(l[1]) && $($(var))
666 if $(l[2]) { comment += [ MATCH "^[$(ws)]?(.*)$" : $(l[2]) ] ; }
667 else { comment += "" ; }
668 $(var) = $($(var)[2-]) ;
669 line = $($(var)[1]) ;
670 l = [ MATCH "^[$(ws)]*(#)(.*)$" : $(line) ] ;
676 # Extract s single line of Jam syntax, ignoring any comments.
678 local rule extract-syntax (
679 var # The name of the variable to extract from.
683 local line = $($(var)[1]) ;
684 while ! $(syntax) && ! [ MATCH "^[$(ws)]*(#)" : $(line) ] && $($(var))
686 local m = [ MATCH "^[$(ws)]*(.*)$" : $(line) ] ;
691 $(var) = $($(var)[2-]) ;
692 line = $($(var)[1]) ;
698 # Extract the next token, this is either a single Jam construct or a comment as
701 local rule extract-token (
702 var # The name of the variable to extract from.
708 parts = [ MATCH "^[$(ws)]*([^$(ws)]+)[$(ws)]*(.*)" : $($(var)[1]) ] ;
711 $(var) = $($(var)[2-]) ;
715 if [ MATCH "^(#)" : $(parts[1]) ]
717 token = $(parts:J=" ") ;
718 $(var) = $($(var)[2-]) ;
722 token = $(parts[1]) ;
723 $(var) = $(parts[2-]:J=" ") $($(var)[2-]) ;
729 # Scan for a rule declaration as the next item in the variable.
731 local rule scan-rule (
732 syntax ? # The first part of the text which contains the rule declaration.
733 : var # The name of the variable to extract from.
737 [ MATCH "^[$(ws)]*(rule|local[$(ws)]*rule)[$(ws)]+([^$(ws)]+)[$(ws)]*(.*)" : $(syntax:J=" ") ] ;
740 # Mark as doc for rule.
741 local rule-name = $(rule-parts[2]) ;
744 rule-name = $(scope-name).$(rule-name) ;
746 local is-local = [ MATCH "^(local).*" : $(rule-parts[1]) ] ;
749 set-rule-doc $(rule-name) $(module-name) $(is-local) : $(comment-block) ;
751 # Parse args of rule.
752 $(var) = $(rule-parts[3-]) $($(var)) ;
753 set-rule-arguments-signature $(rule-name) $(module-name) : [ scan-rule-arguments $(var) ] ;
754 # Scan within this rules scope.
755 local scope-level = [ extract-token $(var) ] ;
756 local scope-name = $(rule-name) ;
757 while $(scope-level) && $($(var))
759 local comment-block = [ extract-comment $(var) ] ;
760 local syntax-block = [ extract-syntax $(var) ] ;
761 if [ scan-rule $(syntax-block) : $(var) ]
764 else if [ MATCH "^(\\{)" : $(syntax-block) ]
768 else if [ MATCH "^[^\\}]*([\\}])[$(ws)]*$" : $(syntax-block) ]
770 scope-level = $(scope-level[2-]) ;
779 # Scan the arguments of a rule.
781 local rule scan-rule-arguments (
782 var # The name of the variable to extract from.
786 local token = [ extract-token $(var) ] ;
787 while $(token) != "(" && $(token) != "{"
789 token = [ extract-token $(var) ] ;
793 token = [ extract-token $(var) ] ;
795 local arg-signature = ;
796 while $(token) != ")" && $(token) != "{"
799 local arg-qualifier = " " ;
803 arg-signature += $(token) ;
804 token = [ extract-token $(var) ] ;
806 arg-name = $(token) ;
807 arg-signature += $(token) ;
808 token = [ extract-token $(var) ] ;
809 if [ MATCH "^([\\*\\+\\?])" : $(token) ]
811 arg-qualifier = $(token) ;
812 arg-signature += $(token) ;
813 token = [ extract-token $(var) ] ;
817 arg-signature += $(token) ;
818 token = [ extract-token $(var) ] ;
820 if [ MATCH "^(#)" : $(token) ]
822 $(var) = $(token) $($(var)) ;
823 arg-doc = [ extract-comment $(var) ] ;
824 token = [ extract-token $(var) ] ;
826 set-argument-doc $(arg-name) $(arg-qualifier) $(rule-name) $(module-name) : $(arg-doc) ;
828 while $(token) != "{"
830 token = [ extract-token $(var) ] ;
832 $(var) = "{" $($(var)) ;
833 arg-signature ?= "" ;
834 return $(arg-signature) ;
838 # Scan for a variable declaration.
840 local rule scan-variable (
841 syntax ? # The first part of the text which contains the variable declaration.
842 : var # The name of the variable to extract from.
845 # [1] = name, [2] = value(s)
847 [ MATCH "^[$(ws)]*([^$(ws)]+)[$(ws)]+([\\?\\=]*)[$(ws)]+([^\\;]*)\\;" : $(syntax) ] ;
850 local value = [ MATCH "^(.*)[ ]$" : $(var-parts[3-]:J=" ") ] ;
851 local default-value = "" ;
852 local initial-valie = "" ;
853 if $(var-parts[2]) = "?="
855 default-value = $(value) ;
856 default-value ?= "(empty)" ;
860 initial-value = $(value) ;
861 initial-value ?= "(empty)" ;
865 set-variable-doc $(var-parts[1]) $(default-value) $(initial-value) $(module-name) : $(comment-block) ;
872 # Scan a class declaration.
874 local rule scan-class (
875 syntax ? # The syntax text for the class declaration.
878 # [1] = class?, [2] = name, [3] = superclass
880 [ MATCH "^[$(ws)]*([^$(ws)]+)[$(ws)]+([^$(ws)]+)[$(ws)]+:*[$(ws)]*([^$(ws);]*)" : $(syntax) ] ;
881 if $(class-parts[1]) = "class" || $(class-parts[1]) = "class.class"
883 set-class-doc $(class-parts[2]) $(module-name) : $(class-parts[3]) ;
888 # Scan a module file for documentation comments. This also invokes any actions
889 # assigned to the module. The actions are the rules that do the actual output of
890 # the documentation. This rule is invoked as the header scan rule for the module
894 target # The module file.
895 : text * # The text in the file, one item per line.
896 : action * # Rule to call to output docs for the module.
899 if $(.option.debug) { ECHO "HELP:" scanning module target '$(target)' ; }
900 local module-name = $(target:B) ;
901 local module-documented = ;
902 local comment-block = ;
903 local syntax-block = ;
904 # This is a hack because we can not get the line of a file if it happens to
905 # not have a new-line termination.
909 comment-block = [ extract-comment text ] ;
910 syntax-block = [ extract-syntax text ] ;
913 ECHO "HELP:" comment block; '$(comment-block)' ;
914 ECHO "HELP:" syntax block; '$(syntax-block)' ;
916 if [ scan-rule $(syntax-block) : text ] { }
917 else if [ scan-variable $(syntax-block) : text ] { }
918 else if [ scan-class $(syntax-block) ] { }
919 else if [ MATCH .*([cC]opyright).* : $(comment-block:J=" ") ]
921 # mark as the copy for the module.
922 set-module-copyright $(module-name) : $(comment-block) ;
924 else if $(action[1]) in "print-help-project" "print-help-config"
925 && ! $(jamfile<$(target)>.docs)
927 # special module docs for the project jamfile.
928 jamfile<$(target)>.docs = $(comment-block) ;
930 else if ! $(module-documented)
932 # document the module.
933 set-module-doc $(module-name) : $(comment-block) ;
934 module-documented = true ;
939 $(action[1]) $(module-name) : $(action[2-]) ;
944 # Import scan-module to global scope, so that it is available during header
947 IMPORT $(__name__) : scan-module : : doc.scan-module ;
950 # Read in a file using the SHELL builtin and return the individual lines as
951 # would be done for header scanning.
953 local rule read-file (
954 file # The file to read in.
957 file = [ path.native [ path.root [ path.make $(file) ] [ path.pwd ] ] ] ;
958 if ! $(.file<$(file)>.lines)
961 switch [ modules.peek : OS ]
964 content = [ SHELL "TYPE \"$(file)\"" ] ;
967 content = [ SHELL "cat \"$(file)\"" ] ;
972 local << = "([^$(nl)]*)[$(nl)](.*)" ;
973 local line+ = [ MATCH "$(<<)" : "$(content)" ] ;
976 lines += $(line+[1]) ;
977 line+ = [ MATCH "$(<<)" : "$(line+[2])" ] ;
979 .file<$(file)>.lines = $(lines) ;
981 return $(.file<$(file)>.lines) ;
985 # Add a scan action to perform to generate the help documentation. The action
986 # rule is passed the name of the module as the first argument. The second
987 # argument(s) are optional and passed directly as specified here.
990 modules + # The modules to scan and perform the action on.
991 : action * # The action rule, plus the secondary arguments to pass to the action rule.
994 if $(help-output) = text
996 print.output $(help-output-file).txt plain ;
997 ALWAYS $(help-output-file).txt ;
998 DEPENDS all : $(help-output-file).txt ;
1000 if $(help-output) = html
1002 print.output $(help-output-file).html html ;
1003 ALWAYS $(help-output-file).html ;
1004 DEPENDS all : $(help-output-file).html ;
1006 for local module-file in $(modules[1--2])
1008 scan-module $(module-file) : [ read-file $(module-file) ] ;
1010 scan-module $(modules[-1]) : [ read-file $(modules[-1]) ] : $(action) ;