Further refactoring of the TCL extension test procedure document, for

improved clarity and usability.

FossilOrigin-Name: bcdaef434142973a0805117495e561b2dcd1ec1465cacc9b944a3707291afc0d

1 files changed, 61 insertions, 60 deletions

diff --git a/doc/tcl-extension-testing.md b/doc/tcl-extension-testing.md
index 65baa1546..ec624ceb5 100644
--- a/doc/tcl-extension-testing.md
+++ b/doc/tcl-extension-testing.md
@@ -5,7 +5,7 @@
 The SQLite TCL extension logic (in the 
 "[tclsqlite.c](/file/src/tclsqlite.c)" source
 file) is statically linked into "textfixture" executable
-which is the program used to do more of the testing
+which is the program used to do most of the testing
 associated with "make test", "make devtest", and/or
 "make releasetest".  So the functionality of the SQLite
 TCL extension is thoroughly vetted during normal testing.  The
@@ -21,39 +21,39 @@ an ordinary tclsh can subsequently run "package require sqlite3".
 <ol type="1">
 <li value="1"> 
     [Fossil](https://fossil-scm.org/) installed.
-<li>
-    A Fossil check-out of the TCL source tree.  Let the directory
-    of this check-out be called **$TCLCO** (mnemonic: "TCL Check-Out").
-<li>
-    A Fossil check-out of the SQLite source tree.  Let the directory
-    of this check-out be called **$SRCCO** (mnemonic: "SouRCe Check-Out").
-<li>
-    Let **$TCLTD** (mnemonic: "TCL Test Directory") be the name of a directory
-    that does not exist at the start of the test, and which will be 
-    deleted at the end of the test, that will contain the test builds
-    of the TCL libraries and the SQLite TCL Extensions.
+<li> Check out source code and set environment variables:
+   <ol type="a">
+   <li> **TCLSOURCE** &rarr;
+    The top-level directory of a Fossil check-out of the TCL source tree.
+   <li> **SQLITESOURCE** &rarr;
+    A Fossil check-out of the SQLite source tree.
+   <li> **TCLBUILD** &rarr;
+    A directory that does not exist at the start of the test and which
+    will be deleted at the end of the test, and that will contain the
+    test builds of the TCL libraries and the SQLite TCL Extensions.
+   </ol>
 </ol>
 
 ### 2.2 Testing TCL 8.6 on unix
 
 <ol type="1">
-<li value="5">  `mkdir $TCLTD/tcl86`
-<li>  `cd $TCLCO/unix`
+<li value="3">  `mkdir -p $TCLBUILD/tcl86`
+<li>  `cd $TCLSOURCE/unix`
 <li>  `fossil up core-8-6-16` <br>
       &uarr; Or some other version of Tcl8.6.
 <li>  `fossil clean -x`
-<li>  `./configure --prefix=$TCLTD/tcl86`
+<li>  `./configure --prefix=$TCLBUILD/tcl86`
 <li>  `make install`
-<li> `cd $SRCCO`
+<li> `cd $SQLITESOURCE`
 <li> `fossil clean -x`
-<li> `./configure --with-tclsh=$TCLTD/tcl86/bin/tclsh8.6`
+<li> `./configure --with-tclsh=$TCLBUILD/tcl86/bin/tclsh8.6`
 <li> `make tclextension-install` <br>
-     &uarr; Verify extension installed at $TCLTD/tcl86/lib/tcl8.6/sqlite3.*
-<li> `makek tclextension-list` <br>
+     &uarr; Verify extension installed at $TCLBUILD/tcl86/lib/tcl8.6/sqlite3.*
+<li> `make tclextension-list` <br>
      &uarr; Verify TCL extension correctly installed.
 <li> `make tclextension-verify` <br>
      &uarr; Verify that the correct version is installed.
-<li> `$TCLTD/tcl86/bin/tclsh8.6 test/testrunner.tcl release --explain` <br>
+<li> `$TCLBUILD/tcl86/bin/tclsh8.6 test/testrunner.tcl release --explain` <br>
      &uarr; Verify thousands of lines of output with no errors. Or
      consider running "devtest" without --explain instead of "release".
 </ol>
@@ -61,21 +61,21 @@ an ordinary tclsh can subsequently run "package require sqlite3".
 ### 2.3 Testing TCL 9.0 on unix
 
 <ol>
-<li value="18">  `mkdir $TCLTD/tcl90`
+<li value="16">  `mkdir -p $TCLBUILD/tcl90`
 <li>  `fossil up core-9-0-0` <br>
       &uarr; Or some other version of Tcl9
 <li>  `fossil clean -x`
-<li>  `./configure --prefix=$TCLTD/tcl90`
+<li>  `./configure --prefix=$TCLBUILD/tcl90`
 <li>  `make install`
-<li> `cd $SRCCO`
+<li> `cd $SQLITESOURCE`
 <li> `fossil clean -x`
-<li> `./configure --with-tclsh=$TCLTD/tcl90/bin/tclsh9.0`
+<li> `./configure --with-tclsh=$TCLBUILD/tcl90/bin/tclsh9.0`
 <li> `make tclextension-install` <br>
-     &uarr; Verify extension installed at $TCLTD/tcl90/lib/sqlite3.*
-<li> `makek tclextension-list` <br>
+     &uarr; Verify extension installed at $TCLBUILD/tcl90/lib/sqlite3.*
+<li> `make tclextension-list` <br>
      &uarr; Verify TCL extension correctly installed.
 <li> `make tclextension-verify`
-<li> `$TCLTD/tcl90/bin/tclsh9.0 test/testrunner.tcl release --explain` <br>
+<li> `$TCLBUILD/tcl90/bin/tclsh9.0 test/testrunner.tcl release --explain` <br>
      &uarr; Verify thousands of lines of output with no errors.  Or
      consider running "devtest" without --explain instead of "release".
 </ol>
@@ -83,7 +83,7 @@ an ordinary tclsh can subsequently run "package require sqlite3".
 ### 2.4 Cleanup
 
 <ol type="1">
-<li value="30"> `rm -rf $TCLTD`
+<li value="28"> `rm -rf $TCLBUILD`
 </ol>
 
 ## 3.0 Testing On Windows
@@ -94,46 +94,47 @@ an ordinary tclsh can subsequently run "package require sqlite3".
 <li value="1"> 
     [Fossil](https://fossil-scm.org/) installed.
 <li>
-    A Fossil check-out of the TCL source tree.  Let the directory
-    of this check-out be called **%TCLCO%** (mnemonic: "TCL Check-Out").
-<li>
-    A Fossil check-out of the SQLite source tree.  Let the directory
-    of this check-out be called **%SRCCO%** (mnemonic: "SouRCe Check-Out").
-<li>
-    Let **%TCLTD%** (mnemonic: "TCL Test Directory") be the name of a directory
-    that does not exist at the start of the test, and which will be 
-    deleted at the end of the test, that will contain the test builds
-    of the TCL libraries and the SQLite TCL Extensions.
-<li>
     Unix-like command-line tools installed.  Example:
     [unxutils](https://unxutils.sourceforge.net/)
 <li> [Visual Studio](https://visualstudio.microsoft.com/vs/community/)
      installed.  VS2015 or later required.
-<li> `set ORIGINALPATH=%PATH%` <br>
-     &uarr; remember the original %PATH% value
+<li> Check out source code and set environment variables.
+   <ol type="a">
+   <li> **TCLSOURCE** &rarr;
+    The top-level directory of a Fossil check-out of the TCL source tree.
+   <li> **SQLITESOURCE** &rarr;
+    A Fossil check-out of the SQLite source tree.
+   <li> **TCLBUILD** &rarr;
+    A directory that does not exist at the start of the test and which
+    will be deleted at the end of the test, and that will contain the
+    test builds of the TCL libraries and the SQLite TCL Extensions.
+    <li> **ORIGINALPATH** &rarr;
+    The original value of %PATH%.  In other words, set as follows:
+    `set ORIGINALPATH %PATH%`
+   </ol>
 </ol>
 
 ### 3.2 Testing TCL 8.6 on Windows
 
 <ol type="1">
-<li value="8">  `mkdir %TCLTD%\tcl86`
-<li>  `cd %TCLCO%\win`
+<li value="5">  `mkdir %TCLBUILD%\tcl86`
+<li>  `cd %TCLSOURCE%\win`
 <li>  `fossil up core-8-6-16` <br>
       &uarr; Or some other version of Tcl8.6.
 <li>  `fossil clean -x`
-<li>  `set INSTALLDIR=%TCLTD%\tcl86`
+<li>  `set INSTALLDIR=%TCLBUILD%\tcl86`
 <li>  `nmake /f makefile.vc release` <br>
       &udarr; You *must* invoke the "release" and "install" targets
-      using separate invocations of "nmake" or tclsh86t.exe won't be
+      using separate "nmake" commands or tclsh86t.exe won't be
       installed.
 <li>  `nmake /f makefile.vc install`
-<li> `cd %SRCCO%`
+<li> `cd %SQLITESOURCE%`
 <li> `fossil clean -x`
-<li> `set TCLDIR=%TCLTD%\tcl86`
-<li> `set PATH=%TCLTD%\tcl86\bin;%ORIGINALPATH%`
-<li> `set TCLSH_CMD=%TCLTD%\tcl86\bin\tclsh86t.exe`
+<li> `set TCLDIR=%TCLBUILD%\tcl86`
+<li> `set PATH=%TCLBUILD%\tcl86\bin;%ORIGINALPATH%`
+<li> `set TCLSH_CMD=%TCLBUILD%\tcl86\bin\tclsh86t.exe`
 <li> `nmake /f Makefile.msc tclextension-install` <br>
-     &uarr; Verify extension installed at %TCLTD%\\tcl86\\lib\\tcl8.6\\sqlite3.*
+     &uarr; Verify extension installed at %TCLBUILD%\\tcl86\\lib\\tcl8.6\\sqlite3.*
 <li> `nmake /f Makefile.msc tclextension-verify`
 <li>`tclsh86t test/testrunner.tcl release --explain` <br>
      &uarr; Verify thousands of lines of output with no errors.  Or
@@ -143,24 +144,24 @@ an ordinary tclsh can subsequently run "package require sqlite3".
 ### 3.3 Testing TCL 9.0 on Windows
 
 <ol>
-<li value="23">  `mkdir %TCLTD%\tcl90`
-<li>  `cd %TCLCO%\win`
+<li value="20">  `mkdir %TCLBUILD%\tcl90`
+<li>  `cd %TCLSOURCE%\win`
 <li>  `fossil up core-9-0-0` <br>
       &uarr; Or some other version of Tcl9
 <li>  `fossil clean -x`
-<li>  `set INSTALLDIR=%TCLTD%\tcl90`
+<li>  `set INSTALLDIR=%TCLBUILD%\tcl90`
 <li>  `nmake /f makefile.vc release` <br>
       &udarr; You *must* invoke the "release" and "install" targets
-      using separate invocations of "nmake" or tclsh90.exe won't be
+      using separate "nmake" commands or tclsh90.exe won't be
       installed.
 <li>  `nmake /f makefile.vc install`
-<li> `cd %SRCCO%`
+<li> `cd %SQLITESOURCE%`
 <li> `fossil clean -x`
-<li> `set TCLDIR=%TCLTD%\tcl90`
-<li> `set PATH=%TCLTD%\tcl90\bin;%ORIGINALPATH%`
-<li> `set TCLSH_CMD=%TCLTD%\tcl90\bin\tclsh90.exe`
+<li> `set TCLDIR=%TCLBUILD%\tcl90`
+<li> `set PATH=%TCLBUILD%\tcl90\bin;%ORIGINALPATH%`
+<li> `set TCLSH_CMD=%TCLBUILD%\tcl90\bin\tclsh90.exe`
 <li> `nmake /f Makefile.msc tclextension-install` <br>
-     &uarr; Verify extension installed at %TCLTD%\\tcl90\\lib\\sqlite3.*
+     &uarr; Verify extension installed at %TCLBUILD%\\tcl90\\lib\\sqlite3.*
 <li> `nmake /f Makefile.msc tclextension-verify`
 <li> `tclsh90 test/testrunner.tcl release --explain` <br>
      &uarr; Verify thousands of lines of output with no errors.  Or
@@ -170,5 +171,5 @@ an ordinary tclsh can subsequently run "package require sqlite3".
 ### 3.4 Cleanup
 
 <ol type="1">
-<li value="38"> `rm -rf %TCLTD%`
+<li value="35"> `rm -rf %TCLBUILD%`
 </ol>