Further reword {Append,Prepend}ENVPath entries [skip appveyor]

Signed-off-by: Mats Wichmann <[email protected]>

Author: mwichmann

SCons/Environment.xml

@@ -778,33 +778,38 @@ See also &f-link-env-AppendUnique;,
 </arguments>
 <summary>
 <para>
-Append one or more path prefixes to an entry in a dictionary-valued
-&consvar; in <parameter>env</parameter>.
-Optional <parameter>envname</parameter> specifies the
-the &consvar; to update;
+Append directory paths from
+<parameter>newpath</parameter> to
+a search-path entry <parameter>name</parameter>
+in &consvar; <parameter>envname</parameter>
+in the current enviromment (<parameter>env</parameter>).
+If <parameter>envname</parameter> is not given,
 the default is <literal>"ENV"</literal>
 (see &cv-link-ENV;).
-The required <parameter>name</parameter> parameter
-is the dictionary entry to update.
-The prefix(es) to add,
-given by <parameter>newpath</parameter>,
+<parameter>envname</parameter> is expected
+to refer to a dictionary-like object;
+if it does not exist in <parameter>env</parameter>
+it will be created as an initially empty dict.
+<parameter>newpath</parameter>
 may be specified as a string,
 a directory node, or a list of strings.
-If a string, it may contain multiple prefixes separated
+If a string, it may contain multiple paths separated
 by the system path separator
 (<systemitem>os.pathsep</systemitem>),
 or, if specified, by the value of <parameter>sep</parameter>.
 Top-relative path strings (starting with <literal>#</literal>) are recognized.
+The type of the existing value
+of <parameter>name</parameter> is preserved.
 </para>
+
 <para>
-Path prefixes will only appear once.
-Duplicate prefixes in <parameter>newpath</parameter> are removed,
+Paths will only appear once.
+Duplicate paths in <parameter>newpath</parameter> are removed,
 preserving the last occurrence to maintain path order.
-If <parameter>delete_existing</parameter> is true,
-existing duplicates are removed before appending;
-otherwise, new duplicates are skipped
-(the default is false).
-Prefixes are normalized for comparisons to avoid problems of
+If <parameter>delete_existing</parameter> is true (the default),
+existing duplicates are removed before appending,
+otherwise, new duplicates are skipped.
+Paths are normalized during comparisons to avoid problems of
 "same path, spelled differently",
 but retain their original form in the result.
 </para>
@@ -2872,33 +2877,38 @@ and &f-link-env-PrependUnique;.
 </arguments>
 <summary>
 <para>
-Prepend one or more path prefixes to an entry in a dictionary-valued
-&consvar; in <parameter>env</parameter>.
-Optional <parameter>envname</parameter> specifies the
-the &consvar; to update;
+Prepend directory paths from
+<parameter>newpath</parameter> to
+a search-path entry <parameter>name</parameter>
+in &consvar; <parameter>envname</parameter>
+in the current enviromment (<parameter>env</parameter>).
+If <parameter>envname</parameter> is not given,
 the default is <literal>"ENV"</literal>
 (see &cv-link-ENV;).
-The required <parameter>name</parameter> parameter
-is the dictionary entry to update.
-The prefix(es) to insert,
-given by <parameter>newpath</parameter>,
+<parameter>envname</parameter> is expected
+to refer to a dictionary-like object;
+if it does not exist in <parameter>env</parameter>
+it will be created as an initially empty dict.
+<parameter>newpath</parameter>
 may be specified as a string,
 a directory node, or a list of strings.
-If a string, it may contain multiple prefixes separated
+If a string, it may contain multiple paths separated
 by the system path separator
 (<systemitem>os.pathsep</systemitem>),
 or, if specified, by the value of <parameter>sep</parameter>.
 Top-relative path strings (starting with <literal>#</literal>) are recognized.
+The type of the existing value
+of <parameter>name</parameter> is preserved.
 </para>
+
 <para>
-Path prefixes will only appear once.
-Duplicate prefixes in <parameter>newpath</parameter> are removed,
-preserving the last occurrence to maintain path order.
-If <parameter>delete_existing</parameter> is true,
-existing duplicates are removed before prepending;
-otherwise, new duplicates are skipped
-(the default is false).
-Prefixes are normalized for comparisons to avoid problems of
+Paths will only appear once.
+Duplicate paths in <parameter>newpath</parameter> are removed,
+preserving the first occurrence to maintain path order.
+If <parameter>delete_existing</parameter> is true (the default),
+existing duplicates are removed before prepending,
+otherwise, new duplicates are skipped.
+Paths are normalized during comparisons to avoid problems of
 "same path, spelled differently",
 but retain their original form in the result.
 </para>

SCons/Util/envs.py

@@ -30,10 +30,11 @@ def PrependPath(
 
     Will only add any particular path once (leaving the first one it
     encounters and ignoring the rest, to preserve path order), and will
-    :mod:`os.path.normpath` and :mod:`os.path.normcase` all paths to help
-    assure this.  This can also handle the case where *oldpath*
-    is a list instead of a string, in which case a list will be returned
-    instead of a string. For example:
+    :mod:`os.path.normpath` and :mod:`os.path.normcase` all paths
+    for comparisons to help assure this. *oldpath* may be a list
+    instead of a string, in which case a list is returned.
+
+    Example:
 
     >>> p = PrependPath("/foo/bar:/foo", "/biz/boom:/foo")
     >>> print(p)
@@ -120,10 +121,11 @@ def AppendPath(
 
     Will only add any particular path once (leaving the last one it
     encounters and ignoring the rest, to preserve path order), and will
-    :mod:`os.path.normpath` and :mod:`os.path.normcase` all paths to help
-    assure this.  This can also handle the case where *oldpath*
-    is a list instead of a string, in which case a list will be returned
-    instead of a string. For example:
+    :mod:`os.path.normpath` and :mod:`os.path.normcase` all paths
+    for comparisons to help assure this. *oldpath* may be a list
+    instead of a string, in which case a list is returned.
+
+    Example:
 
     >>> p = AppendPath("/foo/bar:/foo", "/biz/boom:/foo")
     >>> print(p)

doc/generated/functions.gen

@@ -707,26 +707,40 @@ See also &f-link-env-AppendUnique;,
   <varlistentry id="f-AppendENVPath">
     <term><replaceable>env</replaceable>.<methodname>AppendENVPath</methodname>(<parameter>name, newpath, [envname, sep, delete_existing=False]</parameter>)</term>
     <listitem><para>
-Append path elements specified by <parameter>newpath</parameter>
-to the given search path string or list <parameter>name</parameter>
-in mapping <parameter>envname</parameter> in the &consenv;.
-Supplying <parameter>envname</parameter> is optional:
-the default is the execution environment &cv-link-ENV;.
-Optional <parameter>sep</parameter> is used as the search path separator,
-the default is the platform's separator (<systemitem>os.pathsep</systemitem>).
-A path element will only appear once.
-Any duplicates in <parameter>newpath</parameter> are dropped,
-keeping the last appearing (to preserve path order).
-If <parameter>delete_existing</parameter>
-is <constant>False</constant> (the default)
-any addition duplicating an existing path element is ignored;
-if <parameter>delete_existing</parameter>
-is <constant>True</constant> the existing value will
-be dropped and the path element will be added at the end.
-To help maintain uniqueness all paths are normalized (using
-<systemitem>os.path.normpath</systemitem>
-and
-<systemitem>os.path.normcase</systemitem>).
+Append directory paths from
+<parameter>newpath</parameter> to
+a search-path entry <parameter>name</parameter>
+in &consvar; <parameter>envname</parameter>
+in the current enviromment (<parameter>env</parameter>).
+If <parameter>envname</parameter> is not given,
+the default is <literal>"ENV"</literal>
+(see &cv-link-ENV;).
+<parameter>envname</parameter> is expected
+to refer to a dictionary-like object;
+if it does not exist in <parameter>env</parameter>
+it will be created as an initially empty dict.
+<parameter>newpath</parameter>
+may be specified as a string,
+a directory node, or a list of strings.
+If a string, it may contain multiple paths separated
+by the system path separator
+(<systemitem>os.pathsep</systemitem>),
+or, if specified, by the value of <parameter>sep</parameter>.
+Top-relative path strings (starting with <literal>#</literal>) are recognized.
+The type of the existing value
+of <parameter>name</parameter> is preserved.
+</para>
+
+<para>
+Paths will only appear once.
+Duplicate paths in <parameter>newpath</parameter> are removed,
+preserving the last occurrence to maintain path order.
+If <parameter>delete_existing</parameter> is true (the default),
+existing duplicates are removed before appending,
+otherwise, new duplicates are skipped.
+Paths are normalized during comparisons to avoid problems of
+"same path, spelled differently",
+but retain their original form in the result.
 </para>
 
 <para>
@@ -1031,8 +1045,8 @@ env4 = env.Clone(tools=['msvc', MyTool])
 The
 <parameter>parse_flags</parameter>
 keyword argument is also recognized, to allow merging command-line
-style arguments into the appropriate construction
-variables (see &f-link-env-MergeFlags;).
+style arguments into the appropriate &consvars;
+(see &f-link-env-MergeFlags;).
 </para>
 
 <example_commands>
@@ -3381,26 +3395,40 @@ and &f-link-env-PrependUnique;.
   <varlistentry id="f-PrependENVPath">
     <term><replaceable>env</replaceable>.<methodname>PrependENVPath</methodname>(<parameter>name, newpath, [envname, sep, delete_existing=True]</parameter>)</term>
     <listitem><para>
-Prepend path elements specified by <parameter>newpath</parameter>
-to the given search path string or list <parameter>name</parameter>
-in mapping <parameter>envname</parameter> in the &consenv;.
-Supplying <parameter>envname</parameter> is optional:
-the default is the execution environment &cv-link-ENV;.
-Optional <parameter>sep</parameter> is used as the search path separator,
-the default is the platform's separator (<systemitem>os.pathsep</systemitem>).
-A path element will only appear once.
-Any duplicates in <parameter>newpath</parameter> are dropped,
-keeping the first appearing (to preserve path order).
-If <parameter>delete_existing</parameter>
-is <constant>False</constant>
-any addition duplicating an existing path element is ignored;
-if <parameter>delete_existing</parameter>
-is <constant>True</constant> (the default) the existing value will
-be dropped and the path element will be inserted at the beginning.
-To help maintain uniqueness all paths are normalized (using
-<systemitem>os.path.normpath</systemitem>
-and
-<systemitem>os.path.normcase</systemitem>).
+Prepend directory paths from
+<parameter>newpath</parameter> to
+a search-path entry <parameter>name</parameter>
+in &consvar; <parameter>envname</parameter>
+in the current enviromment (<parameter>env</parameter>).
+If <parameter>envname</parameter> is not given,
+the default is <literal>"ENV"</literal>
+(see &cv-link-ENV;).
+<parameter>envname</parameter> is expected
+to refer to a dictionary-like object;
+if it does not exist in <parameter>env</parameter>
+it will be created as an initially empty dict.
+<parameter>newpath</parameter>
+may be specified as a string,
+a directory node, or a list of strings.
+If a string, it may contain multiple paths separated
+by the system path separator
+(<systemitem>os.pathsep</systemitem>),
+or, if specified, by the value of <parameter>sep</parameter>.
+Top-relative path strings (starting with <literal>#</literal>) are recognized.
+The type of the existing value
+of <parameter>name</parameter> is preserved.
+</para>
+
+<para>
+Paths will only appear once.
+Duplicate paths in <parameter>newpath</parameter> are removed,
+preserving the first occurrence to maintain path order.
+If <parameter>delete_existing</parameter> is true (the default),
+existing duplicates are removed before prepending,
+otherwise, new duplicates are skipped.
+Paths are normalized during comparisons to avoid problems of
+"same path, spelled differently",
+but retain their original form in the result.
 </para>
 
 <para>