scons icon indicating copy to clipboard operation
scons copied to clipboard

Tweak some things about Command() docs

Open mwichmann opened this issue 1 year ago • 0 comments

Adjust the description of the Command function (and builder entry), mainly to try out new terminology. We've said it's not really a builder, but it feels better to me to admit it is exactly a builder call, just not to one of the existing named builders. So the term introduced is "anonymous builder". Changes in docstring for Command, too, plus a little tweak to kwarg processing. Since Command refers to Builder's target_factory and source_factory arguments, looked at the examples there, and tweaked them to be a little closer to runnable examples (ideas taken from the testcase, which the examples seem to have been based on originally).

This change actually started with reformatting some examples in the manpage, some of which used Command, with the chdir argument which didn't seem to be mentioned in the description of how to use Command, which lists four keyword args and says all the rest are treated as construction variable settings (not true for chdir, which isn't one of the four). That led to thinking about rewording.

The original code reformatting changes, no longer directly related to the current change subject, are left in just because they seem low burden, though could back them out if it makes reviewing too hard.

A couple of other small tweaks:

  • some places referred to a section named "File and Directory Nodes" but it's no longer named that. Actual links to the section updated fine when it was renamed, but in Environment.xml, which produces shared content, you can't use manpage-specific links, so the textual references needed updating.
  • the code example for a warning was moved inside the warning - the effect on output is just an indent to match the warning.
  • Configure used both terms "custom checks" and "custom tests", now only the former; plus a link reference added.

Contributor Checklist:

  • [ ] I have created a new test or updated the unit tests to cover the new/changed functionality.
  • [X] I have updated CHANGES.txt (and read the README.rst)
  • [X] I have updated the appropriate documentation

mwichmann avatar May 22 '24 17:05 mwichmann