gallium/docs: Cleanup debugging. Spelling, grammar, organization.

src/gallium/docs/source/debugging.rst

@@ -6,10 +6,10 @@ Debugging utilities in gallium.
 Debug Variables
 ^^^^^^^^^^^^^^^
 
-All drivers respond to a couple of debug enviromental variables. Below is
-a collection of them. Set them as you would any normal enviromental variable
-for the platform/operating system you are running. For linux this can be
-done by typing "export var=value" into a console and then running the
+All drivers respond to a set of common debug environment variables, as well as
+some driver-specific variables. Set them as normal environment variables for
+the platform or operating system you are running. For example, for Linux this
+can be done by typing "export var=value" into a console and then running the
 program from that console.
 
 Common
@@ -17,9 +17,9 @@ Common
 
 .. envvar:: GALLIUM_PRINT_OPTIONS <bool> (false)
 
-This options controls if the debug variables should be printed to stderr.
-This is probably the most usefull variable since it allows you to find
-which variables a driver responds to.
+This option controls if the debug variables should be printed to stderr. This
+is probably the most useful variable, since it allows you to find which
+variables a driver uses.
 
 .. envvar:: GALLIUM_RBUG <bool> (false)
 
@@ -27,29 +27,34 @@ Controls if the :ref:`rbug` should be used.
 
 .. envvar:: GALLIUM_TRACE <string> ("")
 
-If not set tracing is not used, if set it will write the output to the file
-specifed by the variable. So setting it to "trace.xml" will write the output
-to the file "trace.xml".
+If set, this variable will cause the :ref:`Trace` output to be written to the
+specified file. Paths may be relative or absolute; relative paths are relative
+to the working directory.  For example, setting it to "trace.xml" will cause
+the trace to be written to a file of the same name in the working directory.
 
 .. envvar:: GALLIUM_DUMP_CPU <bool> (false)
 
-Dump information about the current cpu that the driver is running on.
+Dump information about the current CPU that the driver is running on.
 
 .. envvar:: TGSI_PRINT_SANITY <bool> (false)
 
-Gallium has a inbuilt shader sanity checker, this option controls if results
-from it should be printed. This include warnings such as unused variables.
+Gallium has a built-in shader sanity checker.  This option controls whether
+the shader sanity checker prints its warnings and errors to stderr.
 
 .. envvar:: DRAW_USE_LLVM <bool> (false)
 
-Should the :ref:`draw` module use llvm for vertex and geometry shaders.
+Whether the :ref:`Draw` module will attempt to use LLVM for vertex and geometry shaders.
+
+
+State tracker-specific
+""""""""""""""""""""""
 
 .. envvar:: ST_DEBUG <flags> (0x0)
 
 Debug :ref:`flags` for the GL state tracker.
 
 
-Driver specific
+Driver-specific
 """""""""""""""
 
 .. envvar:: I915_DEBUG <flags> (0x0)
@@ -68,7 +73,7 @@ Dump all commands going to the hardware.
 
 Debug :ref:`flags` for the llvmpipe driver.
 
-.. envvar:: LP_NUM_THREADS <int> (num cpus)
+.. envvar:: LP_NUM_THREADS <int> (number of CPUs)
 
 Number of threads that the llvmpipe driver should use.
 
@@ -78,10 +83,10 @@ Number of threads that the llvmpipe driver should use.
 Flags
 """""
 
-The variables of type <flags> all take a string with comma seperated
-flags to enable different debugging for different parts of the drivers
-or state tracker. If set to "help" the driver will print a list of flags
-to which the variable can be set to. Order does not matter.
+The variables of type "flags" all take a string with comma-separated flags to
+enable different debugging for different parts of the drivers or state
+tracker. If set to "help", the driver will print a list of flags which the
+variable accepts. Order does not matter.
 
 
 .. _rbug:
@@ -89,8 +94,8 @@ to which the variable can be set to. Order does not matter.
 Remote Debugger
 ^^^^^^^^^^^^^^^
 
-Or rbug for short allows for runtime inspections of :ref:`Context`,
-:ref:`Screen`, Resources and Shaders; pauseing and stepping of draw calls;
-and runtime disable and replacement of shaders. Is used with rbug-gui which
-is hosted outside of the main mesa repositor. Rbug is can be used over a
-network connection so the debbuger does not need to be on the same machine.
+The remote debugger, commonly known as rbug, allows for runtime inspections of
+:ref:`Context`, :ref:`Screen`, :ref:`Resource` and :ref:`Shader` objects; and
+pausing and stepping of :ref:`Draw` calls. Is used with rbug-gui which is
+hosted outside of the main mesa repository. rbug is can be used over a network
+connection, so the debugger does not need to be on the same machine.