Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Tweak some things about Command() docs #4535

Merged
merged 1 commit into from
May 25, 2024
Merged

Conversation

mwichmann
Copy link
Collaborator

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.
  • I have updated CHANGES.txt (and read the README.rst)
  • I have updated the appropriate documentation

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.

This change actually started with reformatting some examples in the
manpage, which used Command, which used 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,
tough could back them out if it makes reviewing to 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.

Signed-off-by: Mats Wichmann <[email protected]>
@bdbaddog bdbaddog merged commit 9f75371 into SCons:master May 25, 2024
4 of 5 checks passed
@mwichmann mwichmann added this to the 4.8 milestone May 25, 2024
@mwichmann mwichmann deleted the doc/Command branch May 25, 2024 21:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants