From 959e35788a8a6aa418c97cb55221c70b9cc15fe5 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 22 Feb 2023 09:43:58 -0700 Subject: User Guide fixups [skip appveyor] For add-method chapter, plus the following scanners chapter, normalize usage a little: the first mention in any given section uses the marked-up form &Builder; and &Scanner;, which contain index references, subsequent ones do not. Only references to Scanner as a concept are capitalized, things like "scanner function" were left alone. Signed-off-by: Mats Wichmann --- doc/user/add-method.xml | 4 ++-- doc/user/scanners.xml | 62 ++++++++++++++++++++++++------------------------- 2 files changed, 33 insertions(+), 33 deletions(-) diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml index d25ba9a..7c59bf2 100644 --- a/doc/user/add-method.xml +++ b/doc/user/add-method.xml @@ -32,9 +32,9 @@ Copyright The SCons Foundation The &f-link-AddMethod; function is used to add a method to an environment. It is typically used to add a "pseudo-builder," a function that looks like a &Builder; but - wraps up calls to multiple other &Builder;'s + wraps up calls to multiple other Builders or otherwise processes its arguments - before calling one or more &Builder;s. + before calling one or more Builders. In the following example, we want to install the program into the standard /usr/bin directory hierarchy, diff --git a/doc/user/scanners.xml b/doc/user/scanners.xml index b9a5084..1e22342 100644 --- a/doc/user/scanners.xml +++ b/doc/user/scanners.xml @@ -146,15 +146,16 @@ over the file scanning rather than being called for each input line: - &SCons; has built-in scanners that know how to look in + &SCons; has routines that know how to look in C/C++, Fortran, D, IDL, LaTeX, Python and SWIG source files for information about - other files that targets built from those files depend on--for example, - in the case of files that use the C preprocessor, + other files that targets built from those files depend on - + for example, in the case of files that use the C preprocessor, the .h files that are specified using #include lines in the source. + Such a routine is called a &Scanner;. You can use the same mechanisms that &SCons; uses to create - its built-in scanners to write scanners of your own for file types + its built-in Scanners to write Scanners of your own for file types that &SCons; does not know how to scan "out of the box." @@ -164,7 +165,7 @@ over the file scanning rather than being called for each input line: - Suppose, for example, that we want to create a simple scanner + Suppose, for example, that we want to create a simple &Scanner; for .foo files. A .foo file contains some text that will be processed, @@ -183,7 +184,7 @@ include filename.foo Scanning a file will be handled by a Python function that you must supply. Here is a function that will use the Python - re module + re module to scan for the include lines in our example: @@ -203,7 +204,7 @@ def kfile_scan(node, env, path, arg): It is important to note that you have to return a list of File nodes from the scanner function, simple strings for the file names won't do. As in the examples we are showing here, - you can use the &File; + you can use the &f-link-File; function of your current &consenv; in order to create nodes on the fly from a sequence of file names with relative paths. @@ -225,7 +226,7 @@ def kfile_scan(node, env, path, arg): - node + node @@ -233,8 +234,8 @@ def kfile_scan(node, env, path, arg): An &SCons; node object representing the file being scanned. The path name to the file can be used by converting the node to a string - using the str() function, - or an internal &SCons; get_text_contents() + using the str function, + or an internal &SCons; get_text_contents object method can be used to fetch the contents. @@ -242,7 +243,7 @@ def kfile_scan(node, env, path, arg): - env + env @@ -256,13 +257,13 @@ def kfile_scan(node, env, path, arg): - path + path A list of directories that form the search path for included files - for this scanner. + for this Scanner. This is how &SCons; handles the &cv-link-CPPPATH; and &cv-link-LIBPATH; variables. @@ -271,7 +272,7 @@ def kfile_scan(node, env, path, arg): - arg + arg @@ -288,10 +289,10 @@ def kfile_scan(node, env, path, arg): - A Scanner object is created using the &f-link-Scanner; function, + A scanner object is created using the &f-link-Scanner; function, which typically takes an skeys argument - to associate a file suffix with this scanner. - The Scanner object must then be associated with the + to associate a file suffix with this Scanner. + The scanner object must then be associated with the &cv-link-SCANNERS; &consvar; in the current &consenv;, typically by using the &f-link-Append; method: @@ -320,7 +321,6 @@ def kfile_scan(node, env, path): return env.File(includes) kscan = Scanner(function=kfile_scan, skeys=['.k']) - env = Environment(ENV={'PATH': '__ROOT__/usr/local/bin'}) env.Append(SCANNERS=kscan) @@ -364,21 +364,21 @@ cat
- Adding a search path to a scanner: &FindPathDirs; + Adding a search path to a Scanner: &FindPathDirs; If the build tool in question will use a path variable to search - for included files or other dependencies, then the Scanner will + for included files or other dependencies, then the &Scanner; will need to take that path variable into account as well - &cv-link-CPPPATH; and &cv-link-LIBPATH; are used this way, for example. The path to search is passed to your - scanner as the path argument. Path variables + Scanner as the path argument. Path variables may be lists of nodes, semicolon-separated strings, or even contain &consvars; which need to be expanded. &SCons; provides the &f-link-FindPathDirs; function which returns a callable to expand a given path (given as a SCons &consvar; - name) to a list of paths at the time the scanner is called. + name) to a list of paths at the time the Scanner is called. Deferring evaluation until that point allows, for instance, the path to contain &cv-link-TARGET; references which differ for each file scanned. @@ -390,7 +390,7 @@ cat Using &FindPathDirs; is quite easy. Continuing the above example, using KPATH as the &consvar; with the search path (analogous to &cv-link-CPPPATH;), we just modify the call to - the &Scanner; factory function to include a path keyword arg: + the &f-link-Scanner; factory function to include a path keyword arg: @@ -404,7 +404,7 @@ kscan = Scanner(function=kfile_scan, skeys=['.k'], path_function=FindPathDirs('K &FindPathDirs; returns a callable object that, when called, will essentially expand the elements in env['KPATH'] - and tell the scanner to search in those dirs. It will also properly + and tell the Scanner to search in those dirs. It will also properly add related repository and variant dirs to the search list. As a side note, the returned method stores the path in an efficient way so lookups are fast even when variable substitutions may be needed. @@ -418,9 +418,9 @@ kscan = Scanner(function=kfile_scan, skeys=['.k'], path_function=FindPathDirs('K - One approach for introducing scanners into the build is in - conjunction with a Builder. There are two relvant optional - parameters we can use when creating a builder: + One approach for introducing a &Scanner; into the build is in + conjunction with a &Builder;. There are two relvant optional + parameters we can use when creating a Builder: source_scanner and target_scanner. source_scanner is used for scanning @@ -459,16 +459,16 @@ env.Foo('file') An emitter function can modify the list of sources or targets - passed to the action function when the builder is triggered. + passed to the action function when the Builder is triggered. A scanner function will not affect the list of sources or targets - seen by the builder during the build action. The scanner function - will however affect if the builder should rebuild (if any of - the files sourced by the scanner have changed for example). + seen by the Builder during the build action. The scanner function + will however affect if the Builder should rebuild (if any of + the files sourced by the Scanner have changed for example).
-- cgit v0.12