From 65028bc2220147ec5a9cb4776785ce9f7e8ac70f Mon Sep 17 00:00:00 2001
From: Mats Wichmann <mats@linux.com>
Date: Fri, 10 Jul 2026 09:08:39 -0600
Subject: [PATCH] Tweak wording for $PRINT_CMD_LINE_FUNC  [skip appveyor]

Clarification inspired by an issue that misued the arguments - no longer
indicate that source or target could be anything other than a node-list,
and that the function is responsible for converting to strings.

Fixes #2724

Signed-off-by: Mats Wichmann <mats@linux.com>
---
 CHANGES.txt      |  1 +
 RELEASE.txt      |  2 ++
 SCons/Action.xml | 33 ++++++++++++++++++++-------------
 3 files changed, 23 insertions(+), 13 deletions(-)

diff --git a/CHANGES.txt b/CHANGES.txt
index bfd3eb18a..c8e4c0703 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -146,6 +146,7 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       * Add info on the type of an option variable to GetOption and SetOption.
       * Tighten up the doc for Variables-Add() and add a note on file contents
         not being preserved to Variables-Save()
+      * Tweak the wording for $PRINT_CMD_LINE_FUNC.
 
 
 RELEASE 4.10.1 - Sun, 16 Nov 2025 10:51:57 -0700
diff --git a/RELEASE.txt b/RELEASE.txt
index 50438076c..7dd0e6a7d 100644
--- a/RELEASE.txt
+++ b/RELEASE.txt
@@ -167,6 +167,8 @@ DOCUMENTATION
 - Tighten up the doc for Variables-Add() and add a note on file contents
   not being preserved to Variables-Save()
 
+* Tweak the wording for $PRINT_CMD_LINE_FUNC.
+
 DEVELOPMENT
 -----------
 
diff --git a/SCons/Action.xml b/SCons/Action.xml
index e3558d249..2ca6461a0 100644
--- a/SCons/Action.xml
+++ b/SCons/Action.xml
@@ -81,32 +81,36 @@ otherwise, only the first segment is checked.
 <cvar name="PRINT_CMD_LINE_FUNC">
 <summary>
 <para>
-A &Python; function used to print the command lines as they are executed
-(unless command printing is disabled by the
+The function to print command lines as they are executed.
+Called unless command printing is disabled by the
 <link linkend="opt-question"><option>-q</option>/<option>--question</option></link>
 or
 <link linkend="opt-silent"><option>-s</option>/<option>--silent</option></link>
-options).
-The function must accept four arguments:
+options.
+The function will be called with four arguments:
 <varname>s</varname>,
 <varname>target</varname>,
 <varname>source</varname> and
 <varname>env</varname>.
 <varname>s</varname>
-is a string showing the command being executed,
+is the command line string to be executed,
 <varname>target</varname>,
-is the target being built (file node, list, or string name(s)),
+is the target(s) being built
 <varname>source</varname>,
-is the source(s) used (file node, list, or string name(s)),
+is the source(s) used
 and <varname>env</varname>
 is the environment being used.
 </para>
 
 <para>
-The function must do the printing itself.
-The default implementation,
-used if this variable is not set or is <constant>None</constant>,
-is to just print the string, as in:
+Any or all of the arguments can be used in composing the message.
+<varname>source</varname> and
+<varname>target</varname> will be lists of nodes,
+and need to be suitably converted for printing (see example).
+The default,
+used if the variable is not set or set to <constant>None</constant>,
+is to print only the string <parameter>s</parameter>,
+equivalent to:
 </para>
 <example_commands>
 def print_cmd_line(s, target, source, env):
@@ -114,7 +118,8 @@ def print_cmd_line(s, target, source, env):
 </example_commands>
 
 <para>
-Here is an example of a more interesting function:
+This example uses the source and target
+parameters to format a custom message:
 </para>
 
 <example_commands>
@@ -145,7 +150,9 @@ scons: done building targets.
 </screen>
 
 <para>
-Another example could be a function that logs the actual commands to a file.
+Another possible use for a print function is to show
+a very brief message on the console while logging
+the full command line to a file.
 </para>
 </summary>
 </cvar>