ADDED   docs/manual/debugging.txt
Index: docs/manual/debugging.txt
==================================================================
--- /dev/null
+++ docs/manual/debugging.txt
@@ -0,0 +1,75 @@
+//  Copyright 2021, Matthew Welland.
+// 
+// This file is part of Megatest.
+// 
+//     Megatest is free software: you can redistribute it and/or modify
+//     it under the terms of the GNU General Public License as published by
+//     the Free Software Foundation, either version 3 of the License, or
+//     (at your option) any later version.
+// 
+//     Megatest is distributed in the hope that it will be useful,
+//     but WITHOUT ANY WARRANTY; without even the implied warranty of
+//     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//     GNU General Public License for more details.
+// 
+//     You should have received a copy of the GNU General Public License
+//     along with Megatest.  If not, see <http://www.gnu.org/licenses/>.
+
+Debugging
+---------
+
+A word on Bisecting
+~~~~~~~~~~~~~~~~~~~
+
+Bisecting is a debug strategy intended to speed up finding the root
+cause.
+
+["graphviz", "bisecting.png"]
+----------------------------------------------------------------------
+include::bisecting.dot[]
+----------------------------------------------------------------------
+
+It is common to start debugging where the problem was observed and
+then work back. However by inspecting the output at stage "C" in the
+example above you would potentially save a lot of debug effort.
+
+Examining The Environment
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Test Control Panel - xterm
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+From the dashboard click on a test PASS/FAIL button. This brings up a
+test control panel. Aproximately near the center left of the window
+there is a button "Start Xterm". Push this to get an xterm with the
+full context and environment loaded for that test. You can run scripts
+or ezsteps by copying from the testconfig (hint, load up the
+testconfig in a separate text editor window). This is the easiest
+way to debug your tests.
+
+During Config File Processing
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is often helpful to know the content of variables in various
+contexts as Megatest does the actions needed to run your tests. A handy technique is to force the startup of an xterm in the context being examined.
+
+For example, if an item list is not being generated as expected you
+can inject the startup of an xterm as if it were an item:
+
+.Original items table
+-----------------
+[items]
+CELLNAME [system getcellname.sh]
+-----------------
+
+.Items table modified for debug
+-----------------
+[items]
+DEBUG [system xterm]
+CELLNAME [system getcellnames.sh]
+-----------------
+
+When this test is run an xterm will pop up. In that xterm the
+environment is exactly that in which the script "getcellnames.sh"
+would run. You can now debug the script to find out why it isn't
+working as expected.