From 186736d72074ba06c962900bcd8c2d49fd5e828d Mon Sep 17 00:00:00 2001
From: Mats Wichmann <mats@linux.com>
Date: Tue, 11 Aug 2020 08:22:03 -0600
Subject: Tweak Installing Python section in User Guide  [skip appveyor]

Signed-off-by: Mats Wichmann <mats@linux.com>
---
 doc/user/build-install.xml | 49 ++++++++++++++++++++++++----------------------
 1 file changed, 26 insertions(+), 23 deletions(-)

diff --git a/doc/user/build-install.xml b/doc/user/build-install.xml
index 87a86aa..c106dc5 100644
--- a/doc/user/build-install.xml
+++ b/doc/user/build-install.xml
@@ -110,12 +110,13 @@ Python 3.7.1
     </screen>
 
     <para>
-    Note to Windows users: there are many different ways Python
-    can get installed or invoked on Windows, it is beyond the scope
-    of this guide to unravel all of them.  Try using the
-    <firstterm>Python launcher</firstterm> (see
-    <ulink url="https://www.python.org/dev/peps/pep-0397/">PEP 397</ulink>)
-    by using the name <command>py</command> instead of
+    Note to Windows users: there are a number of different ways Python
+    can be installed or invoked on Windows, it is beyond the scope
+    of this guide to unravel all of them. Many will have an additional
+    program called the <firstterm>Python launcher</firstterm> (described,
+    somewhat technically, in
+    <ulink url="https://www.python.org/dev/peps/pep-0397/">PEP 397</ulink>):
+    try using the command name <command>py</command> instead of
     <command>python</command>, if that is not available drop
     back to trying <command>python</command>.
     </para>
@@ -129,21 +130,23 @@ Python 3.7.1
     If Python is not installed on your system,
     or is not findable in the current search path,
     you will see an error message
-    stating something like "command not found"
+    stating something like <computeroutput>"command not found"</computeroutput>
     (on UNIX or Linux)
-    or "'python' is not recognized
-    as an internal or external command, operable progam or batch file"
+    or <computeroutput>"'python' is not recognized as an internal
+    or external command, operable progam or batch file"</computeroutput>
     (on Windows <command>cmd</command>).
-    In that case, you need to install Python
-    (or fix the search path)
+    In that case, you need to either install Python
+    or fix the search path
     before you can install &SCons;.
     </para>
 
     <para>
-    The canonical location for information
-    about downloading and installing Python is
-    <ulink url="http://www.python.org/download/">http://www.python.org/download/</ulink>.
-    See that page and associated links to get started.
+    The canonical location for downloading Python 
+    from Python's own website is:
+    <ulink url="https://www.python.org/download">https://www.python.org/download</ulink>.
+    There are useful system-specific entries on setup and
+    usage to be found at:
+    <ulink url="https://docs.python.org/3/using">https://docs.python.org/3/using</ulink>
     </para>
 
     <para>
@@ -153,7 +156,7 @@ Python 3.7.1
     by other means, and is easier than installing from source code.
     Many such systems have separate packages for
     Python 2 and Python 3 - make sure the Python 3 package is
-    installed, as &SCons; requires it.
+    installed, as the latest &SCons; requires it.
     Building from source may still be a
     useful option if you need a version that is not offered by
     the distribution you are using.
@@ -195,7 +198,7 @@ Python 3.7.1
     For those users using Anaconda or Miniconda, use the
     <command>conda</command> installer instead, so the &scons;
     install location will match the version of Python that
-    system will be using:
+    system will be using. For example:
     </para>
 
     <screen>
@@ -211,14 +214,14 @@ Python 3.7.1
     During the still-ongoing Python 2 to 3 transition,
     some distributions may still have two &SCons; packages available,
     one which uses Python 2 and one which uses Python 3.  Since
-    latest &scons; only runs on Python 3, to get the current version
+    the latest &scons; only runs on Python 3, to get the current version
     you should choose the Python 3 package.
     </para>
 
     <para>
     If you need a specific
     version of &SCons; that is different from the package available,
-    <filename>pip</filename> has a version option or you can follow
+    <systemitem>pip</systemitem> has a version option or you can follow
     the instructions in the next section.
     </para>
 
@@ -229,9 +232,9 @@ Python 3.7.1
 
     <para>
     If a pre-built &SCons; package is not available for your system,
-    and installing using <filename>pip</filename> is not suitable,
+    and installing using <systemitem>pip</systemitem> is not suitable,
     then you can still easily build and install &SCons; using the native
-    Python <filename>distutils</filename> package.
+    Python <systemitem>setuptools</systemitem> package.
     </para>
 
     <para>
@@ -265,11 +268,11 @@ Python 3.7.1
     install the &scons; script
     in the python which is used to run the setup.py's scripts directory
     (<filename>/usr/local/bin</filename> or
-    <filename>C:\Python27\Scripts</filename>),
+    <filename>C:\Python37\Scripts</filename>),
     and will install the &SCons; build engine
     in the corresponding library directory for the python used
     (<filename>/usr/local/lib/scons</filename> or
-    <filename>C:\Python27\scons</filename>).
+    <filename>C:\Python37\scons</filename>).
     Because these are system directories,
     you may need root (on Linux or UNIX) or Administrator (on Windows)
     privileges to install &SCons; like this.
-- 
cgit v0.12