diff --git a/CHANGES.txt b/CHANGES.txt index 7decd0e97..269452f6e 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -102,6 +102,8 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER * Drop old example section from manpage (not a visible change: has been commented out since v4.0, when the content moved to the new Cookbook) * Reword IMPLICIT_COMMAND_DEPENDENCIES construction variable. + * Tighten up the doc for Variables-Add() and add a note on file contents + not being preserved to Variables-Save() RELEASE 4.10.1 - Sun, 16 Nov 2025 10:51:57 -0700 diff --git a/RELEASE.txt b/RELEASE.txt index 5cd867192..f5b41e544 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -139,9 +139,11 @@ DOCUMENTATION - Fix typos in preface, Chapter 6, Chapter 9 and Chapter 10 of User Guide - - Fix broken links in Chapter 1 of User Guide +- Tighten up the doc for Variables-Add() and add a note on file contents + not being preserved to Variables-Save() + DEVELOPMENT ----------- diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 5ba098d2b..a689960ba 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -5009,48 +5009,48 @@ the first item in the sequence is taken as the variable name, and any remaining values are considered aliases for the variable. key is mandatory, the other fields are optional. + + + help -is the help text for the variable -(defaults to an empty string). +is the help text for the variable (default is an empty string). + + + default -is the default value of the variable -(defaults to None). -The variable will be set to the value of -default if it does -not appear in the input sources, -except if default -is None, -in which case it is not added to the &consenv; -unless it has been set in the input sources. +is the value assigned to the variable in the &consenv; +if no value is provided in the input sources. +If default is None (the default), +the variable is not added to the &consenv; +unless explicitly set in the input sources. +The default value can be of the intended type, +or a string that the converter +can transform into that type. If the validator argument is supplied, -it is a callback function to validate the value of the variable -when the variables are processed -(that is, when the &Update; -method runs). -A validator function must accept three arguments: +it is a callback function to validate the value of the variable. +The validator is called when the &Update; +method is called. +A validator must accept three arguments: key, -value -and env, -and should raise an exception (with a helpful error message) -if value is invalid. -No return value is expected from the validator. +value, +and env. +It should raise an exception (with a helpful error message) +if the value is invalid; no return value is expected. If the converter argument is supplied, -it is a callback function to convert the value into -one suitable for adding to the &consenv;. -A converter function must accept the -value argument, -and may declare env -as a second argument if it needs access to the -&consenv; while validating - the function will be called appropriately. -The converter is called before the validator; -it must return a value, which is then passed to the -validator (if any) for checking. +it is a callback function to transform the value into +the format desired for the &consenv;. +A converter is called before the validator. +It must return a value, which is then passed to the +validator (if any). +A converter must accept at least a value argument, +and may optionally accept env +as a second argument if it needs access to the &consenv;. In general, the converter should not fail, leaving validation checks to the validator, although if an operation is impossible to complete @@ -5059,10 +5059,11 @@ it can raise a ValueError. -Substitution will be performed on the variable value -before the converter and validator are called, -unless the optional subst parameter -is false (the default is True). +If the subst argument is supplied, +it is a boolean that indicates whether to perform +substitution on the value before passing it to the +converter and validator functions. +The default is True. Suppressing substitution may be useful if the variable value looks like a &consvar; reference (e.g. $VAR) and the validator and/or converter should see it unexpanded. @@ -5071,12 +5072,13 @@ and the validator and/or converter should see it unexpanded. As a special case, if key is a sequence and is the only -argument to &Add;, it is unpacked into the five parameters +argument to &Add;, it is unpacked into the six parameters key, help, default, -validator and +validator, converter, +and subst, with any missing members from the right filled in with the respective default values. This form allows it @@ -5236,13 +5238,16 @@ Help(vars.GenerateHelpText(env, sort=cmp)) vars.Save(filename, env) Saves the currently set variables into a script file named -by filename. -This provides a way to cache particular variable settings for reuse. -Only variables that are set to non-default values are saved. +filename. You can load these saved variables on a subsequent run -by passing filename to the -&Variables; function, - +by passing the file to the +&Variables; function. +This provides a way to cache particular variable settings for reuse. +Only variables set to non-default values are saved. +Each selected variable is saved as a &Python; assignment statement. +Previous contents of the save file are not preserved +except if they were used to populate the +Variables object.