Index: winedev-debugger.sgml
===================================================================
RCS file: /cvsroot/wine/docs/en/winedev-debugger.sgml,v
retrieving revision 1.2
diff -u -r1.2 winedev-debugger.sgml
--- winedev-debugger.sgml	25 Sep 2005 16:13:41 -0000	1.2
+++ winedev-debugger.sgml	2 Oct 2005 21:43:27 -0000
@@ -41,9 +41,9 @@
         </itemizedlist>
         <para>
           A <varname>W-process</varname> is made of one or several
-          <varname>W-threads</varname>. Each
+          <varname>W-threads</varname>.  Each
           <varname>W-thread</varname> is mapped to one and only one
-          <varname>U-process</varname>. All
+          <varname>U-process</varname>.  All
           <varname>U-processes</varname> of a same
           <varname>W-process</varname> share the same address space.
         </para>
@@ -64,17 +64,17 @@
         </itemizedlist>
         <para>
           Each Windows' process has also a Windows' process id
-          (<varname>wpid</varname> in the following). It must be clear
+          (<varname>wpid</varname> in the following).  It must be clear
           that <varname>upid</varname> and <varname>wpid</varname> are
           different and shall not be used instead of the other.
         </para>
         <para>
           <varname>Wpid</varname> and <varname>tid</varname> are
-          defined (Windows) system wide. They must not be confused
+          defined (Windows) system wide.  They must not be confused
           with process or thread handles which, as any handle, is an
           indirection to a system object (in this case process or
-          thread). A same process can have several different handles
-          on the same kernel object. The handles can be defined as
+          thread).  A same process can have several different handles
+          on the same kernel object.  The handles can be defined as
           local (the values is only valid in a process), or system
           wide (the same handle can be used by any
           <varname>W-process</varname>).
@@ -101,17 +101,17 @@
           </listitem>
         </itemizedlist>
         <para>
-          Wine implements most of the Windows' debugging API. The
+          Wine implements most of the Windows' debugging API.  The
 	  first part of the debugging APIs (in
 	  <filename>KERNEL32.DLL</filename>) allows a W-process, called
 	  the debugger, to control the execution of another W-process,
-	  the debuggee. To control means stopping/resuming execution,
+	  the debuggee.  To control means stopping/resuming execution,
 	  enabling/disabling single stepping, setting breakpoints,
-	  reading/writing debuggee memory... Another part of the
+	  reading/writing debuggee memory...  Another part of the
 	  debugging APIs resides in <filename>DBGHELP.DLL</filename>
 	  (and its ancestor <filename>IMAGEHLP.DLL</filename>) and lets
 	  a debugger look into symbols and types from any module (if
-	  the module has been compiled with the proper options). 
+	  the module has been compiled with the proper options).
         </para>
         <para>
           <command>winedbg</command> is a Winelib application making
@@ -133,7 +133,7 @@
         <para>
           Any application (either a Windows' native executable, or a
           Winelib application) can be run through
-          <command>winedbg</command>. Command line options and tricks
+          <command>winedbg</command>.  Command line options and tricks
           are the same as for wine:
         </para>
         <screen>
@@ -148,13 +148,13 @@
         <para>
           <command>winedbg</command> can also be launched without any
           command line argument: <command>winedbg</command> is started
-          without any attached process. You can get a list of running
+          without any attached process.  You can get a list of running
           <varname>W-processes</varname> (and their
           <varname>wpid</varname>'s) using the <command>info
             process</command> command, and then, with the
           <command>attach</command> command, pick up the
           <varname>wpid</varname> of the <varname>W-process</varname>
-          you want to debug. This is a neat feature as it allows you
+          you want to debug.  This is a neat feature as it allows you
 	  to debug an already started application.
 	 </para>
       </sect2>
@@ -164,23 +164,23 @@
 
         <para>
           When something goes wrong, Windows tracks this as an
-          exception. Exceptions exist for segmentation violation,
+          exception.  Exceptions exist for segmentation violation,
           stack overflow, division by zero, etc.
         </para>
         <para>
           When an exception occurs, Wine checks if the
-	  <varname>W-process</varname> is debugged. If so, the
+	  <varname>W-process</varname> is debugged.  If so, the
 	  exception event is sent to the debugger, which takes care of
-	  it: end of the story. This mechanism is part of the standard
+	  it: end of the story.  This mechanism is part of the standard
 	  Windows' debugging API.
         </para>
         <para>
           If the <varname>W-process</varname> is not debugged, Wine
-          tries to launch a debugger. This debugger (normally
+          tries to launch a debugger.  This debugger (normally
           <command>winedbg</command>, see III Configuration for more
           details), at startup, attaches to the
           <varname>W-process</varname> which generated the exception
-          event. In this case, you are able to look at the causes of
+          event.  In this case, you are able to look at the causes of
           the exception, and either fix the causes (and continue
           further the execution) or dig deeper to understand what went
           wrong.
@@ -215,9 +215,9 @@
             <listitem>
               <para>
                 the debugger couldn't correct the cause of the
-                first chance exception. Wine will now try to walk
+                first chance exception.  Wine will now try to walk
                 the list of exception handlers to see if one of them
-                can handle the exception. If no exception handler is
+                can handle the exception.  If no exception handler is
                 found, the exception is sent once again to the
                 debugger to indicate the failure of the exception
                 handling.
@@ -230,7 +230,7 @@
             since some of Wine's code uses exceptions and
             <function>try/catch</function> blocks to provide some
             functionality, <command>winedbg</command> can be entered
-            in such cases with segv exceptions. This happens, for
+            in such cases with segv exceptions.  This happens, for
             example, with <function>IsBadReadPtr</function> function.
             In that case, the <command>pass</command> command shall be
             used, to let the handling of the exception to be done by
@@ -245,7 +245,7 @@
 
 	<para>
 	  You can stop the debugger while it's running by hitting
-	  Ctrl-C in its window. This will stop the debugged process,
+	  Ctrl-C in its window.  This will stop the debugged process,
 	  and let you manipulate the current context.
 	</para>
       </sect2>
@@ -266,7 +266,7 @@
       <title>Using the Wine Debugger</title>
 
       <para>
-        This section describes where to start debugging Wine. If at any
+        This section describes where to start debugging Wine.  If at any
         point you get stuck and want to ask for help, please read the
         <emphasis>How to Report A Bug</emphasis> section of the 
         <emphasis>Wine Users Guide</emphasis> for information on how to write
@@ -307,7 +307,7 @@
 |0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c):  movw        %es:0x38(%bx),%dx
         </screen>
         <para>
-          Steps to debug a crash. You may stop at any step, but please
+          Steps to debug a crash.  You may stop at any step, but please
           report the bug and provide as much of the information
           gathered to the bug report as feasible.
         </para>
@@ -315,10 +315,10 @@
         <orderedlist>
           <listitem>
             <para>
-              Get the reason for the crash. This is usually an access to
+              Get the reason for the crash.  This is usually an access to
               an invalid selector, an access to an out of range address
               in a valid selector, popping a segment register from the
-              stack or the like. When reporting a crash, report this
+              stack or the like.  When reporting a crash, report this
               <emphasis>whole</emphasis> crashdump even if it doesn't
               make sense to you.
             </para>
@@ -330,10 +330,10 @@
           </listitem>
           <listitem>
             <para>
-              Determine the cause of the crash. Since this is usually
+              Determine the cause of the crash.  Since this is usually
               a primary/secondary reaction to a failed or misbehaving
-              Wine function, rerun Wine with the<parameter>WINEDEBUG=+relay</parameter>
-              environment variable set. This will
+              Wine function, rerun Wine with the <parameter>WINEDEBUG=+relay</parameter>
+              environment variable set.  This will
               generate quite a lot of output, but usually the reason is
               located in the last call(s).  Those lines usually look like
               this:
@@ -345,9 +345,9 @@
       |          |       |         |           |Return address
       |          |       |         |textual parameter
       |          |       |
-      |          |       |Argument(s). This one is a win16 segmented pointer.
+      |          |       |Argument(s).  This one is a win16 segmented pointer.
       |          |Function called.
-      |The module, the function is called in. In this case it is KERNEL.
+      |The module, the function is called in.  In this case it is KERNEL.
 
 |Ret  KERNEL.90: LSTRLEN() retval=0x0004 ret=01e7:2ce7 ds=0227
                                   ^^^^^^
@@ -356,19 +356,19 @@
           </listitem>
           <listitem>
             <para>
-              If you have found a misbehaving function, try to find out
-              why it misbehaves. Find the function in the source code.
-              Try to make sense of the arguments passed. Usually there is
+              If you have found a misbehaving Wine function, try to find out
+              why it misbehaves.  Find the function in the source code.
+              Try to make sense of the arguments passed.  Usually there is
               a <function>WINE_DEFAULT_DEBUG_CHANNEL(&lt;channel>);</function>
-              at the beginning of the file. Rerun wine with the
+              at the beginning of the source file.  Rerun wine with the
               <parameter>WINEDEBUG=+xyz,+relay</parameter> environment variable set.
             </para>
             <para>
               Occasionally there are additional debug channels defined at the 
-              beginning of the file in the form.
+              beginning of the source file in the form
               <function>WINE_DECLARE_DEBUG_CHANNEL(&lt;channel>);</function>
               If so the offending function may also uses one of these alternate
-              channels. Look through the the function for  
+              channels.  Look through the the function for  
              <function>TRACE_(&lt;channel>)(" ... /n");</function> and add any
              additional channels to the commandline.
             </para>
@@ -385,37 +385,41 @@
               If this information isn't clear enough or if you want to
               know more about what's happening in the function itself,
               try running wine with <parameter>WINEDEBUG=+all</parameter>,
-              which dumps ALL included debug
-              information in wine.
+              which dumps ALL included debug information in wine.
+              It is often necessary to limit the debug output produced.
+              That can be done by piping the output through <command>grep</command>,
+              or alternatively with the registry value RelayExclude located
+              under
+              <programlisting>HKCU\\Software\\Wine\\Debug</programlisting>.
             </para>
           </listitem>
           <listitem>
             <para>
               If even that isn't enough, add more debug output for yourself 
-              into the functions you find relevant. See The section on Debug 
-              Logging in this guide for more information. You might
+              into the functions you find relevant.  See The section on Debug 
+              Logging in this guide for more information.  You might
               also try to run the program in <command>gdb</command>
-              instead of using the Wine debugger. If you do that, use
+              instead of using the Wine debugger.  If you do that, use
               <parameter>handle SIGSEGV nostop noprint</parameter> to
               disable the handling of seg faults inside
-              <command>gdb</command> (needed for Win16). 
+              <command>gdb</command> (needed for Win16).
             </para>
           </listitem>
           <listitem>
             <para>
-              You can also set a breakpoint for that function. Start wine 
-              useing <command>winedbg</command> instead of 
-              <command>wine</command>. Once the debugger is is running enter 
+              You can also set a breakpoint for that function.  Start wine 
+              using <command>winedbg</command> instead of 
+              <command>wine</command>.  Once the debugger is is running enter 
               <command>break</command> <parameter>KERNEL_LSTRLEN</parameter>
               (replace by function you want to debug, CASE IS RELEVANT) 
               to set a breakpoint.  Then
               use <command>continue</command> to start normal
-              program-execution. Wine will stop if it reaches the
-              breakpoint. If the program isn't yet at the crashing call
+              program-execution.  Wine will stop if it reaches the
+              breakpoint.  If the program isn't yet at the crashing call
               of that function, use <command>continue</command> again
-              until you are about to enter that function. You may now
+              until you are about to enter that function.  You may now
               proceed with single-stepping the function until you reach
-              the point of crash. Use the other debugger commands to
+              the point of crash.  Use the other debugger commands to
               print registers and the like.
             </para>
           </listitem>
@@ -427,11 +431,11 @@
 
         <para>
           Start the program with <command>winedbg</command> instead of
-          <command>wine</command>. When the program locks up switch to the 
+          <command>wine</command>.  When the program locks up switch to the 
           winedbg's terminal and press 
-          <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>. this
+          <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>.  This
           will stop the program and let you debug the program as you would for
-          a crash. 
+          a crash.
         </para>
       </sect2>
 
@@ -440,8 +444,8 @@
 
         <para>
           Sometimes programs are reporting failure using more or
-          less nondescript messageboxes. We can debug this using the
-          same method as Crashes, but there is one problem... For
+          less nondescript messageboxes.  We can debug this using the
+          same method as Crashes, but there is one problem...  For
           setting up a message box the program also calls Wine
           producing huge chunks of debug code.
         </para>
@@ -450,9 +454,9 @@
           the Messagebox you can start winedbg and set a
           breakpoint at <function>MessageBoxA</function> (called by win16
           and win32 programs) and proceed with
-          <command>continue</command>. With <parameter>WINEDEBUG=+all</parameter>
+          <command>continue</command>.  With <parameter>WINEDEBUG=+all</parameter>
           Wine will now stop directly before setting
-          up the Messagebox. Proceed as explained above.
+          up the Messagebox.  Proceed as explained above.
         </para>
         <para>
           You can also run wine using <command>WINEDEBUG=+relay wine
@@ -471,25 +475,45 @@
         <para>
           The best, freely available, disassembler for Win16 programs is
           <application>Windows Codeback</application>, archive name
-          <filename>wcbxxx.zip</> (e.g. <filename>wcb105a.zip</>), which
-          usually can be found in the <filename>Cica-Mirror</filename>
-          subdirectory on the Wine ftp sites. (See <filename>ANNOUNCE</>).
+          <filename>wcbxxx.zip</> (e.g. <filename>wcb105a.zip</>).
         </para>
         <para>
           Disassembling win32 programs is possible using
-          <application>Windows Disassembler 32</>. Look for
-          a file called <filename>w32dsm87.zip</> (or similar)
-          on <ulink url="http://www.winsite.com/">http://www.winsite.com</>
-          and mirrors.  The shareware version does not allow saving of
-          disassembly listings. You can also use the newer (and in the
-          full version better) <application>Interactive
-            Disassembler</application> (IDA) from the ftp sites mentioned
-          at the end of the document. Understanding disassembled code is
-          mostly a question of exercise.
+          eg. <application>GoVest</> by Ansgar Trimborn.  It can be found
+          <ulink url="http://www.geocities.com/GoVest/">here</>.
         </para>
         <para>
+          Another popular disassembler is
+          <application>Windows Disassembler 32</> from URSoft.
+          Look for a file called <filename>w32dsm87.zip</> (or similar) on
+          <ulink url="http://www.winsite.com/">winsite.com</> or
+          <ulink url="http://www.softpedia.com/">softpedia.com</>.
+        </para>
+        <para>
+          You can also use the newer (and in the full version better)
+          <application>Interactive Disassembler</> (IDA) from
+          DataRescue.  The version of IDA that has been most actively used by
+          Wine project enthusiasts is named <filename>ida35bx.zip</filename>,
+          although that version now seems impossible to locate.  Take a look
+          in the 'useful programs' section later on for links to working
+          versions of IDA.
+        </para>
+        <para>
+          Also of considerable fame amongst disassemblers are
+          <application>SoftIce</> from NuMega.  That software has since been
+          acquired by CompuWare (http://www.compuware.com/) and made part of
+          their Windows driver development suite.  Newer versions of SoftIce
+          needs to run as a Windows Service and therefore won't currently
+          work under Wine.
+        </para>
+        <para>
+          If nothing works for you, try one of the disassemblers found in
+          <ulink url="http://directory.google.com/Top/Computers/Programming/Disassemblers/DOS_and_Windows/">Google's directory</>.
+        </para>
+        <para>
+          Understanding disassembled code is mostly a question of exercise.
           Most code out there uses standard C function entries (for it
-          is usually  written in C). Win16 function entries usually
+          is usually  written in C).  Win16 function entries usually
           look like that:
         </para>
         <programlisting>
@@ -500,11 +524,11 @@
         </programlisting>
         <para>
           This is a <function>FAR</function> function with no local
-          storage. The arguments usually start at
-          <literal>[bp+6]</literal> with increasing offsets. Note, that
+          storage.  The arguments usually start at
+          <literal>[bp+6]</literal> with increasing offsets.  Note, that
           <literal>[bp+6]</literal> belongs to the
           <emphasis>rightmost</emphasis> argument, for exported win16
-          functions use the PASCAL calling convention. So, if we use
+          functions use the PASCAL calling convention.  So, if we use
           <function>strcmp(a,b)</function> with <parameter>a</parameter>
           and <parameter>b</parameter> both 32 bit variables
           <parameter>b</parameter> would be at <literal>[bp+6]</literal>
@@ -522,7 +546,7 @@
         <para>
           This does mostly the same as above, but also adds
           <literal>0x86</literal> bytes of stackstorage, which is
-          accessed using <literal>[bp-xx]</literal>. Before calling a
+          accessed using <literal>[bp-xx]</literal>.  Before calling a
           function, arguments are pushed on the stack using something
           like this:
         </para>
@@ -631,7 +655,7 @@
         </screen>
         <para>
           The code seems to find a writeable harddisk and tries to create
-          a file there. To work around this bug, you can define
+          a file there.   To work around this bug, you can define
           <medialabel>C:</medialabel> as a networkdrive, which is ignored
           by the code above.
         </para>
@@ -649,7 +673,7 @@
             <para>
               If you have a program crashing at such an early loader phase that you can't
               use the Wine debugger normally, but Wine already executes the program's
-              start code, then you may use a special trick. You should do a
+              start code, then you may use a special trick.  You should do a
               <programlisting>
 WINEDEBUG=+relay wine program
               </programlisting>
@@ -660,12 +684,12 @@
               </programlisting>
             </para>
             <para>
-              This way, you get into <command>winedbg</command>. Now you
+              This way, you get into <command>winedbg</command>.  Now you
               can set a breakpoint on any function the program calls in
               the start function and just type <userinput>c</userinput>
               to bypass the eventual calls of Winfile to this function
               until you are finally at the place where this function gets
-              called by the crashing start function. Now you can proceed
+              called by the crashing start function.  Now you can proceed
               with your debugging as usual.
             </para>
           </listitem>
@@ -679,7 +703,7 @@
 WINEDEBUG=+relay wine  &lt;program name> &>relmsg
               </programlisting>
               Then do a <command>more relmsg</command> and search for the
-              last occurrence of a call to the string "MESSAGEBOX". This is a line like
+              last occurrence of a call to the string "MESSAGEBOX".  This is a line like
               <programlisting>
 Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
               </programlisting>
@@ -718,7 +742,7 @@
             <para>
               As the segment value of the address is only
               <literal>4</literal>, I think that that is only an internal
-              program value. But the offset address reveals something
+              program value.  But the offset address reveals something
               quite interesting: Offset <literal>1056</literal> is
               <emphasis>very</emphasis> close to the return address of
               <function>FREELIBRARY()</function>:
@@ -729,15 +753,15 @@
             </para>
             <para>
               Provided that segment <literal>0x0004</literal> is indeed segment
-              <literal>0x1cf</literal>, we now we can use IDA                 (available at
-              <ulink url="http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip">
-               http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip</ulink>) to
-              disassemble the part that caused the error. We just have to find the address of
-              the call to <function>FreeLibrary()</function>. Some lines before that the
-              runtime error occurred. But be careful! In some cases you don't have to
-              disassemble the main program, but instead some DLL called by it in order to find
-              the correct place where the runtime error occurred. That can be determined by
-              finding the origin of the segment value (in this case <literal>0x1cf</literal>).
+              <literal>0x1cf</literal>, we now we can use IDA to disassemble
+              the part that caused the error.  We just have to find the
+              address of the call to <function>FreeLibrary()</function>.  Some
+              lines before that the runtime error occurred.  But be careful!
+              In some cases you don't have to disassemble the main program,
+              but instead some DLL called by it in order to find the correct
+              place where the runtime error occurred.  That can be determined
+              by finding the origin of the segment value (in this case
+              <literal>0x1cf</literal>).
             </para>
           </listitem>
           <listitem>
@@ -761,15 +785,39 @@
             <variablelist>
               <varlistentry>
                 <term>
+                  <application>GoVest</application>:
+                  <filename>govest.zip</filename> is available from
+                  <ulink url="http://www.geocities.com/GoVest/">http://www.geocities.com/GoVest/</>.
+                </term>
+                <listitem>
+                  <para>
+                    The win32 disassembler that currently works
+                    the best with Wine.
+                  </para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>
                   <application>IDA</application>:
-                  <filename>
-                    <ulink url="http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip">
-                     http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip</ulink>
-                  </filename>
+                  <filename>ida35bx.zip</filename> is near impossible to
+                  locate, but you might try a trial version of the new IDA Pro
+                  from
+                  <ulink url="http://www.datarescue.com/">http://www.datarescue.com</ulink>
+                  or try locating the free version of IDA Pro 4.3 by
+                  <ulink url="http://www.google.com/search?q=%22IDA+Pro+freeware%22+4.3">Googling</>.
+                  The newer versions mentioned above currently has problems
+                  installing under Wine.  In the mean time, you can use the
+                  free version of IDA Pro 3.85b, which you can also find by
+                  <ulink url="http://www.google.com/search?q=IDA+Pro+freeware+3.85b">Googling</>.
+                  Version 3.85b does not have a GUI.  It does have a textual
+                  interface, which currently has problems launching under
+                  Wine.  To get it to launch correctly, start it with
+                  <application>winedbg</> instead of <application>wine</>.
+                  Remember to 'c'ontinue the program after starting it.
                 </term>
                 <listitem>
                   <para>
-                    <emphasis>Very</emphasis> good DOS disassembler ! It's badly needed
+                    <emphasis>Very</emphasis> good DOS disassembler! It's badly needed
                     for debugging Wine sometimes.
                   </para>
                 </listitem>
@@ -784,7 +832,7 @@
                 </term>
                 <listitem>
                   <para>
-                    Traces DOS calls (Int 21h, DPMI, ...). Use it with
+                    Traces DOS calls (Int 21h, DPMI, ...).  Use it with
                     Windows to correct file management problems etc.
                   </para>
                 </listitem>
@@ -827,11 +875,11 @@
           After starting your program with
         </para>
         <screen>
-wine -debug myprog.exe
+winedbg myprog.exe
         </screen>
         <para>
           the program loads and you get a prompt at the program
-          starting point. Then you can set breakpoints:
+          starting point.  Then you can set breakpoints:
         </para>
         <screen>
   b RoutineName      (by routine name) OR
@@ -839,7 +887,7 @@
         </screen>
         <para>
           Then you hit <command>c</command> (continue) to run the
-          program. It stops at the breakpoint. You can type
+          program.  It stops at the breakpoint.  You can type
         </para>
         <screen>
   step               (to step one line) OR
@@ -898,7 +946,7 @@
               has the lowest 3 bits set.  Some sample selectors are
               0x1f7, 0x16f, 0x8f.  If these bits are set except for
               the lowest bit, as e.g. with 0x1f6,xi then it might be a
-              handle to global memory. Just set the lowest bit to get
+              handle to global memory.  Just set the lowest bit to get
               the selector in these cases.  A selector kind of
               "points" to a certain linear (see above) base address.
               It has more or less three important attributes: segment
@@ -951,17 +999,17 @@
       <title>Configuration</title>
 
       <sect2>
-        <title>Registry configuration</title>
+        <title>Windows Debugging configuration</title>
 
         <para>
           The Windows' debugging API uses a registry entry to know
           which debugger to invoke when an unhandled exception occurs
           (see <link endterm="dbg-exception-title"
-          linkend="dbg-on-exception"></link> for some details). Two
+          linkend="dbg-on-exception"></link> for some details).  Two
           values in key
         </para>
         <programlisting>
-"MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug"
+[MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug]
         </programlisting>
         <para>
           Determine the behavior:
@@ -971,16 +1019,16 @@
             <term>Debugger</term>
             <listitem>
               <para>
-                this is the command line used to launch the debugger
+                This is the command line used to launch the debugger
                 (it uses two <function>printf</function> formats
                 (<literal>%ld</literal>) to pass context dependent
-                information to  the debugger). You should put here a
+                information to the debugger).  You should put here a
                 complete path to your debugger
                 (<command>winedbg</command> can of course be used, but
-                any other Windows' debugging API aware debugger will
-                do).
-		The path to the debugger you chose to use must be reachable
-		via a DOS drive in the Wine config file !
+                any other Windows' debugging API aware debugger will do).
+                The path to the debugger you choose to use must be reachable
+                via one of the DOS drives configured under /dosdevices in
+                your $WINEPREFIX or ~/.wine folder.
               </para>
             </listitem>
           </varlistentry>
@@ -990,7 +1038,7 @@
               <para>
                 if this value is zero, a message box will ask the
                 user if he/she wishes to launch the debugger when an
-                unhandled exception occurs. Otherwise, the debugger
+                unhandled exception occurs.  Otherwise, the debugger
                 is automatically started.
               </para>
             </listitem>
@@ -1009,7 +1057,7 @@
         <note>
           <title>Note 1</title>
           <para>
-            creating this key is mandatory. Not doing so will not
+            creating this key is mandatory.  Not doing so will not
             fire the debugger when an exception occurs.
           </para>
         </note>
@@ -1037,8 +1085,8 @@
 
         <para>
           <command>winedbg</command> can be configured through a number
-          of options. Those options are stored in the registry, on a
-          per user basis. The key is (in <emphasis>my</emphasis> registry)
+          of options.  Those options are stored in the registry, on a
+          per user basis.  The key is (in <emphasis>my</emphasis> registry)
         </para>
         <programlisting>
 [HKCU\\Software\\Wine\\WineDbg]
@@ -1046,8 +1094,8 @@
         <para>
           Those options can be read/written while inside
           <command>winedbg</command>, as part of the debugger
-          expressions. To refer to one of these options, its name must
-          be  prefixed by a <literal>$</literal> sign. For example,
+          expressions.  To refer to one of these options, its name must
+          be  prefixed by a <literal>$</literal> sign.  For example,
         </para>
         <programlisting>
 set $BreakAllThreadsStartup = 1
@@ -1077,7 +1125,7 @@
 		start-up the debugger stops  set to
 		<literal>FALSE</literal> if only at the first thread
 		startup of a given process the debugger
-		stops. <literal>FALSE</literal> by default.
+		stops.  <literal>FALSE</literal> by default.
 	      </para>
 	    </listitem>
 	  </varlistentry>
@@ -1099,7 +1147,7 @@
 		<command>winedbg</command> attaches to an existing
 		process after an unhandled exception,
 		<command>winedbg</command> shall be entered on the
-		first attach event. Since the attach event is
+		first attach event.  Since the attach event is
 		meaningless in the context of an exception event (the
 		next event  which is the exception event is of course
 		relevant), that option is likely to be
@@ -1111,19 +1159,19 @@
 	    <term><varname>BreakOnFirstChance</varname></term>
 	    <listitem>
 	      <para>
-		An exception can generate two debug events. The first
+		An exception can generate two debug events.  The first
 		one is passed to the debugger (known as a first
-		chance) just after the exception. The debugger can
+		chance) just after the exception.  The debugger can
 		then decide either to resume execution (see
 		<command>winedbg</command>'s <command>cont</command>
 		command) or pass the exception up to the exception
 		handler chain in the program (if it exists)
 		(<command>winedbg</command> implements this through
-		the <command>pass</command> command). If none of the
+		the <command>pass</command> command).  If none of the
 		exception handlers takes care of the exception, the
 		exception event is sent again to the debugger (known
-		as last chance exception). You cannot pass on a last
-		exception. When the
+		as last chance exception).  You cannot pass on a last
+		exception.  When the
 		<varname>BreakOnFirstChance</varname> exception is
 		<literal>TRUE</literal>, then winedbg is entered for
 		both first and last chance execptions (to
@@ -1138,7 +1186,7 @@
 	      <para>
 		Set to <literal>TRUE</literal> if the debugger, when
 		looking up for a symbol from its name, displays all
-		the thunks with that name. The default value
+		the thunks with that name.  The default value
 		(<literal>FALSE</literal>) allows not to have to
 		choose between a symbol and all the import thunks
 		from all the DLLs using that symbols.
@@ -1147,6 +1195,49 @@
 	  </varlistentry>
 	</variablelist>
       </sect2>
+
+      <sect2>
+        <title>Configuring +relay behaviour</title>
+        <para>
+          When setting <parameter>WINEDEBUG</> to +relay and debugging,
+          you might get a lot of output.  You can limit the output by
+          configuring the value RelayExclude in the registry, located
+          under the key:
+        </para>
+        <programlisting>
+          [HKCU\\Software\\Wine\\Debug]
+        </programlisting>
+        <para>
+          Set the value of RelayExclude to a semicolon-separated list of
+          calls to exclude.  Example:
+          "RtlEnterCriticalSection;RtlLeaveCriticalSection;kernel32.97;kernel32.98".
+        </para>
+        <para>
+          RelayInclude is an option similar to RelayExclude, except that
+          functions listed here will be the only ones included in the output.
+          Also see section 3.4.3.5 for more options.
+        </para>
+        <para>
+          If your application runs too slow with +relay to get meaningful
+          output and you're stuck with multi-GB relay log files, but
+          you're not sure what to exclude, here's a trick to get you started.
+          First, run your application for a minute or so, piping it's output
+          to a file on disk:
+        </para>
+        <programlisting>
+          WINEDEBUG=+relay wine &lt;appname.exe> &>relay.log
+        </programlisting>
+        <para>
+          Then run this command to see which calls are performed the most:
+        </para>
+        <programlisting>
+          awk -F'(' '{print $1}' &lt; relay.log | awk '{print $2}' | sort | uniq -c | sort
+        </programlisting>
+        <para>
+          Exclude the bottom-most calls with RelayExclude after making
+          sure that they are irrelevant and run your application again.
+        </para>
+      </sect2>
     </sect1>
 
     <sect1 id="dbg-expr">
@@ -1156,11 +1247,11 @@
 
 	<para>
 	  Expressions in Wine Debugger are mostly written in a C
-	  form. However, there are a few discrepancies:
+	  form.  However, there are a few discrepancies:
 	  <itemizedlist>
 	    <listitem>
 	      <para>
-		Identifiers can take a '!' in their names. This allow
+		Identifiers can take a '!' in their names.  This allow
 		mainly to access symbols from different DLLs like
 		<function>USER32!CreateWindowExA</function>.
 	      </para>
@@ -1169,7 +1260,7 @@
 	      <para>
 	        In cast operation, when specifying a structure or an
 		union, you must use the <type>struct</type> or
-		<type>union</type> keyword (even if your program uses a typedef). 
+		<type>union</type> keyword (even if your program uses a typedef).
 	      </para>
 	    </listitem>
 	  </itemizedlist>
@@ -1177,7 +1268,7 @@
 	<para>
 	  When specifying an identifier by its name, if several
 	  symbols with the same name exist, the debugger will prompt
-	  for the symbol you want to use. Pick up the one you want
+	  for the symbol you want to use.  Pick up the one you want
 	  from its number.
 	</para>
 	<para>
@@ -1186,8 +1277,8 @@
 	</para>
 	<para>
 	  <command>winedbg</command> defines its own set of
-	  variables. The configuration variables from above are part
-	  of them. Some others include:
+	  variables.  The configuration variables from above are part
+	  of them.  Some others include:
           <variablelist>
             <varlistentry>
               <term><varname>$ThreadId</varname></term>
@@ -1212,7 +1303,7 @@
               <listitem>
                 <para>
                   All CPU registers are also available, using $ as a
-		  prefix. You can use <command>info regs</command> to
+		  prefix.  You can use <command>info regs</command> to
 		  get a list of avaible CPU registers
                 </para>
               </listitem>
@@ -1250,8 +1341,8 @@
 		  <entry><command>attach&nbsp;N</command></entry>
 		  <entry>
 		    attach to a W-process (N is its ID, numeric
-		    or hexadecimal (0xN)). IDs can be obtained using
-		    the info process command. Note the info process
+		    or hexadecimal (0xN)).  IDs can be obtained using
+		    the info process command.  Note the info process
 		    command returns hexadecimal values.
 		  </entry>
 		</row>
@@ -1373,7 +1464,7 @@
           <command>cont</command>, <command>step</command>,
 	  <command>next</command>, <command>stepi</command>,
 	  <command>nexti</command> can be postfixed by a number (N),
-	  meaning that the command must be executed N times. 
+	  meaning that the command must be executed N times.
         </para>
       </sect2>
 
@@ -1410,8 +1501,8 @@
 		  </entry>
 		  <entry>
 		    adds condition &lt;expr&gt; to (break|watch)point
-		    N. &lt;expr&gt; will be evaluated each time the
-		    breakpoint is hit. If the result is a zero value,
+		    N.  &lt;expr&gt; will be evaluated each time the
+		    breakpoint is hit.  If the result is a zero value,
 		    the breakpoint isn't triggered
 		  </entry>
 		</row>
@@ -1478,7 +1569,7 @@
 	  symbol cannot be found (for example, the symbol is contained
 	  in a not yet loaded module), winedbg will recall the name of
 	  the symbol and will try to set the breakpoint each time a
-	  new module is loaded (until it succeeds). 
+	  new module is loaded (until it succeeds).
         </para>
       </sect2>
 
@@ -1643,7 +1734,7 @@
 
         <para>
           You can specify the end target (to change the 10 lines
-          value) using the ','. For example:
+          value) using the ','.  For example:
 	  <table>
 	    <title>WineDbg's list command examples</title>
 	    <tgroup cols="2" align="left">
@@ -1678,7 +1769,7 @@
         </para>
 	<para>
 	  <command>winedbg</command> will automatically detect if the
-	  expression you entered contains a local variable. If so,
+	  expression you entered contains a local variable.  If so,
 	  display will only be shown if the context is still in the
 	  same function as the one the debugger was in when the
 	  display expression was entered.
@@ -1719,7 +1810,7 @@
 		  </entry>
 		  <entry>
 		    adds a display for expression
-		    &lt;expr&gt;. Printing evaluated &lt;expr&gt; is
+		    &lt;expr&gt;.  Printing evaluated &lt;expr&gt; is
 		    done using the given format (see
 		    <command>print</command> command for more on
 		    formats)
@@ -2054,11 +2145,11 @@
         <title>GDB mode</title>
 
         <para>
-	  WineDbg can act as a remote monitor for GDB. This allows to
+	  WineDbg can act as a remote monitor for GDB.  This allows to
 	  use all the power of GDB, but while debugging wine and/or
-	  any Win32 application. To enable this mode, just add
-	  <parameter>--gdb</parameter> to winedbg command line. You'll
-	  end up on a GDB prompt. You'll have to use the GDB commands
+	  any Win32 application.  To enable this mode, just add
+	  <parameter>--gdb</parameter> to winedbg command line.  You'll
+	  end up on a GDB prompt.  You'll have to use the GDB commands
 	  (not WineDbg's).
 	</para>
 
@@ -2076,7 +2167,7 @@
 	      <para>
 		Moreover, it also provides support for the Dwarf II
 		debug format (which became the default format (instead
-		of stabs) in gcc 3.1). 
+		of stabs) in gcc 3.1).
 	      </para>
 	    </listitem>
 	  </itemizedlist>
@@ -2157,7 +2248,7 @@
 		</para>
 	      </listitem>
 	    </orderedlist>
-	    The program should now be loaded and up and running. If
+	    The program should now be loaded and up and running.  If
 	    you want, you can also add in 1/ after the name of the
 	    exec all the needed parameters
           </para>
@@ -2193,7 +2284,7 @@
 		</para>
 	      </listitem>
 	    </orderedlist>
-	    The program should now be loaded and up and running. If
+	    The program should now be loaded and up and running.  If
 	    you want, you can also add in 1/ after the name of the
 	    exec all the needed parameters
           </para>
@@ -2229,7 +2320,7 @@
 	      <listitem>
 		<para>
 		  Wine is running on the pthread model (it won't work
-		  in the kthread one). See the Wine architecture
+		  in the kthread one).  See the Wine architecture
 		  documentation for further details.
 		</para>
 	      </listitem>
@@ -2261,7 +2352,7 @@
         </screen>
         <para>
           Switch to another console and enter <command>ps ax | grep
-            wine</command> to find all wine processes. Inside
+            wine</command> to find all wine processes.  Inside
           <command>gdb</command>, repeat for all Wine processes:
         </para>
         <screen>
@@ -2313,9 +2404,9 @@
 
         <para>
           You can use any Windows' debugging API compliant debugger
-          with Wine. Some reports have been made of success with
+          with Wine.  Some reports have been made of success with
           VisualStudio debugger (in remote mode, only the hub runs
-          in Wine). GoVest fully runs in Wine.
+          in Wine).  GoVest fully runs in Wine.
         </para>
       </sect2>
 
