diff --git a/docs/xml/FAQ.xml b/docs/xml/FAQ.xml
index 66ff21c..7abd422 100644
--- a/docs/xml/FAQ.xml
+++ b/docs/xml/FAQ.xml
@@ -13,9 +13,9 @@
     <year>&vg-lifespan;</year>
     <holder><ulink url="&vg-developers;">Valgrind Developers</ulink></holder>
   </copyright>
-  <author>
-    <email><ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></email>
-  </author>
+  <legalnotice>
+    <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para>
+  </legalnotice>
 </bookinfo>
 
 
@@ -36,11 +36,10 @@
   <para>How do you pronounce "Valgrind"?</para>
  </question>
  <answer id="a-pronounce">
-  <para>The "Val" as in the world "value".  The "grind" is
-  pronounced with a short 'i' -- ie. "grinned" (rhymes with
-  "tinned") rather than "grined" (rhymes with "find").</para>
-  <para>Don't feel bad: almost everyone gets it wrong at
-  first.</para>
+  <para>The "Val" as in the world "value".  The "grind" is pronounced
+  with a short 'i' -- ie. "grinned" (rhymes with "tinned") rather than
+  "grined" (rhymes with "find").</para> <para>Don't feel bad: almost
+  everyone gets it wrong at first.</para>
  </answer>
 </qandaentry>
 
@@ -49,21 +48,23 @@
   <para>Where does the name "Valgrind" come from?</para>
  </question>
  <answer id="a-whence">
-  <para>From Nordic mythology.  Originally (before release) the
-  project was named Heimdall, after the watchman of the Nordic
-  gods.  He could "see a hundred miles by day or night, hear the
-  grass growing, see the wool growing on a sheep's back" (etc).
-  This would have been a great name, but it was already taken by
-  a security package "Heimdal".</para> <para>Keeping with the
-  Nordic theme, Valgrind was chosen.  Valgrind is the name of the
-  main entrance to Valhalla (the Hall of the Chosen Slain in
-  Asgard).  Over this entrance there resides a wolf and over it
-  there is the head of a boar and on it perches a huge eagle,
-  whose eyes can see to the far regions of the nine worlds.  Only
-  those judged worthy by the guardians are allowed to pass
-  through Valgrind.  All others are refused entrance.</para>
-  <para>It's not short for "value grinder", although that's not a
-  bad guess.</para>
+
+  <para>From Nordic mythology.  Originally (before release) the project
+  was named Heimdall, after the watchman of the Nordic gods.  He could
+  "see a hundred miles by day or night, hear the grass growing, see the
+  wool growing on a sheep's back" (etc).  This would have been a great
+  name, but it was already taken by a security package "Heimdal".</para>
+
+  <para>Keeping with the Nordic theme, Valgrind was chosen.  Valgrind is
+  the name of the main entrance to Valhalla (the Hall of the Chosen
+  Slain in Asgard).  Over this entrance there resides a wolf and over it
+  there is the head of a boar and on it perches a huge eagle, whose eyes
+  can see to the far regions of the nine worlds.  Only those judged
+  worthy by the guardians are allowed to pass through Valgrind.  All
+  others are refused entrance.</para>
+
+  <para>It's not short for "value grinder", although that's not a bad
+  guess.</para>
   </answer>
  </qandaentry>
 
@@ -85,12 +86,11 @@
 </screen>
  </question>
  <answer id="a-make_dies">
-  <para>It's probably a bug in 'make'.  Some, but not all,
-  instances of version 3.79.1 have this bug, see
-  www.mail-archive.com/bug-make@gnu.org/msg01658.html.  Try
-  upgrading to a more recent version of 'make'.  Alternatively,
-  we have heard that unsetting the CFLAGS environment variable
-  avoids the problem.</para>
+  <para>It's probably a bug in 'make'.  Some, but not all, instances of
+  version 3.79.1 have this bug, see
+  www.mail-archive.com/bug-make@gnu.org/msg01658.html.  Try upgrading to
+  a more recent version of 'make'.  Alternatively, we have heard that
+  unsetting the CFLAGS environment variable avoids the problem.</para>
  </answer>
 </qandaentry>
 
@@ -103,98 +103,101 @@
 <title>Valgrind aborts unexpectedly</title>
 
 <qandaentry id="faq.exit_errors">
- <question id="q-exit_errors">
-  <para>Programs run OK on Valgrind, but at exit produce a bunch
-  of errors involving <literal>__libc_freeres()</literal>
-  and then die with a segmentation fault.</para>
- </question>
- <answer id="a-exit_errors">
-  <para>When the program exits, Valgrind runs the procedure
-  <literal>__libc_freeres()</literal> in glibc.  This is a hook
-  for memory debuggers, so they can ask glibc to free up any
-  memory it has used.  Doing that is needed to ensure that
-  Valgrind doesn't incorrectly report space leaks in glibc.</para>
-  <para>Problem is that running
-  <literal>__libc_freeres()</literal> in older glibc versions
-  causes this crash.</para> <para>WORKAROUND FOR 1.1.X and later
-  versions of Valgrind: use the
-  <literal>--run-libc-freeres=no</literal> flag.  You may then get
-  space leak reports for glibc-allocations (please _don't_ report
-  these to the glibc people, since they are not real leaks), but
-  at least the program runs.</para>
- </answer>
+  <question id="q-exit_errors">
+    <para>Programs run OK on Valgrind, but at exit produce a bunch of
+    errors involving <literal>__libc_freeres()</literal> and then die
+    with a segmentation fault.</para>
+  </question>
+  <answer id="a-exit_errors">
+    <para>When the program exits, Valgrind runs the procedure
+    <function>__libc_freeres()</function> in glibc.  This is a hook for
+    memory debuggers, so they can ask glibc to free up any memory it has
+    used.  Doing that is needed to ensure that Valgrind doesn't
+    incorrectly report space leaks in glibc.</para>
+
+    <para>Problem is that running <literal>__libc_freeres()</literal> in
+    older glibc versions causes this crash.</para>
+
+    <para>WORKAROUND FOR 1.1.X and later versions of Valgrind: use the
+    <option>--run-libc-freeres=no</option> flag.  You may then get space
+    leak reports for glibc-allocations (please _don't_ report these to
+    the glibc people, since they are not real leaks), but at least the
+    program runs.</para>
+  </answer>
 </qandaentry>
 
 <qandaentry id="faq.bugdeath">
- <question id="q-bugdeath">
-  <para>My (buggy) program dies like this:</para>
+  <question id="q-bugdeath">
+    <para>My (buggy) program dies like this:</para>
 <screen>% valgrind: vg_malloc2.c:442 (bszW_to_pszW): Assertion 'pszW >= 0' failed.</screen>
- </question>
- <answer id="a-bugdeath">
-  <para>If Memcheck (the memory checker) shows any invalid reads,
-  invalid writes and invalid frees in your program, the above may
-  happen.  Reason is that your program may trash Valgrind's
-  low-level memory manager, which then dies with the above
-  assertion, or something like this.  The cure is to fix your
-  program so that it doesn't do any illegal memory accesses.  The
-  above failure will hopefully go away after that.</para>
- </answer>
+  </question>
+  <answer id="a-bugdeath">
+    <para>If Memcheck (the memory checker) shows any invalid reads,
+    invalid writes and invalid frees in your program, the above may
+    happen.  Reason is that your program may trash Valgrind's low-level
+    memory manager, which then dies with the above assertion, or
+    something like this.  The cure is to fix your program so that it
+    doesn't do any illegal memory accesses.  The above failure will
+    hopefully go away after that.</para>
+  </answer>
 </qandaentry>
 
 <qandaentry id="faq.msgdeath">
- <question id="q-msgdeath">
-  <para>My program dies, printing a message like this along the
+  <question id="q-msgdeath">
+    <para>My program dies, printing a message like this along the
     way:</para>
 <screen>% disInstr: unhandled instruction bytes: 0x66 0xF 0x2E 0x5</screen>
- </question>
- <answer id="a-msgdeath">
-  <para>Older versions did not support some x86 instructions,
-  particularly SSE/SSE2 instructions.  Try a newer Valgrind; we
-  now support almost all instructions.  If it still happens with
-  newer versions, if the failing instruction is an SSE/SSE2
-  instruction, you might be able to recompile your program
-  without it by using the flag
-  <computeroutput>-march</computeroutput> to gcc.  Either way,
-  let us know and we'll try to fix it.</para>
+  </question>
+  <answer id="a-msgdeath">
+    <para>Older versions did not support some x86 instructions,
+    particularly SSE/SSE2 instructions.  Try a newer Valgrind; we now
+    support almost all instructions.  If it still happens with newer
+    versions, if the failing instruction is an SSE/SSE2 instruction, you
+    might be able to recompile your program without it by using the flag
+    <option>-march</option> to gcc.  Either way, let us know and we'll
+    try to fix it.</para>
 
-  <para>Another possibility is that your program has a bug and
-  erroneously jumps to a non-code address, in which case you'll
-  get a SIGILL signal.  Memcheck/Addrcheck may issue a warning
-  just before this happens, but they might not if the jump
-  happens to land in addressable memory.</para>
- </answer>
+    <para>Another possibility is that your program has a bug and
+    erroneously jumps to a non-code address, in which case you'll get a
+    SIGILL signal.  Memcheck/Addrcheck may issue a warning just before
+    this happens, but they might not if the jump happens to land in
+    addressable memory.</para>
+  </answer>
 </qandaentry>
 
 <qandaentry id="faq.java">
- <question id="q-java">
-  <para>I tried running a Java program (or another program that uses a
-  just-in-time compiler) under Valgrind but something went wrong.
-  Does Valgrind handle such programs?</para>
- </question>
- <answer id="a-java">
-  <para>Valgrind can handle dynamically generated code, so long as none
-  of the generated code is later overwritten by other generated code.
-  If this happens, though, things will go wrong as Valgrind will continue
-  running its translations of the old code (this is true on x86 and AMD64,
-  on PPC32 there are explicit cache flush instructions which Valgrind
-  detects).  You should try running with
-  <computeroutput>--smc-check=all</computeroutput> in this case;  Valgrind
-  will run much more slowly, but should detect the use of the out-of-date
-  code.</para>
-  <para>Alternativaly, if you have the source code to the JIT compiler you
-  can insert calls to the
-  <computeroutput>VALGRIND_DISCARD_TRANSLATIONS</computeroutput> client
-  request to mark out-of-date code, saving you from using
-  <computeroutput>--smc-check=all</computeroutput>.</para>
-  <para>Apart from this, in theory Valgrind can run any Java program just
-  fine, even those that use JNI and are partially implemented in other
-  languages like C and C++.  In practice, Java implementations tend to do
-  nasty things that most programs do not, and Valgrind sometimes falls
-  over these corner cases.</para>
-  <para>If your Java programs do not run under Valgrind, even with
-  <computeroutput>--smc-check=all</computeroutput>, please file a bug
-  report and hopefully we'll be able to fix the problem.</para>
- </answer>
+  <question id="q-java">
+    <para>I tried running a Java program (or another program that uses a
+    just-in-time compiler) under Valgrind but something went wrong.
+    Does Valgrind handle such programs?</para>
+  </question>
+  <answer id="a-java">
+    <para>Valgrind can handle dynamically generated code, so long as
+    none of the generated code is later overwritten by other generated
+    code.  If this happens, though, things will go wrong as Valgrind
+    will continue running its translations of the old code (this is true
+    on x86 and AMD64, on PPC32 there are explicit cache flush
+    instructions which Valgrind detects).  You should try running with
+    <option>--smc-check=all</option> in this case; Valgrind will run
+    much more slowly, but should detect the use of the out-of-date
+    code.</para>
+
+    <para>Alternativaly, if you have the source code to the JIT compiler
+    you can insert calls to the
+    <computeroutput>VALGRIND_DISCARD_TRANSLATIONS</computeroutput>
+    client request to mark out-of-date code, saving you from using
+    <option>--smc-check=all</option>.</para>
+
+    <para>Apart from this, in theory Valgrind can run any Java program
+    just fine, even those that use JNI and are partially implemented in
+    other languages like C and C++.  In practice, Java implementations
+    tend to do nasty things that most programs do not, and Valgrind
+    sometimes falls over these corner cases.</para>
+
+    <para>If your Java programs do not run under Valgrind, even with
+    <option>--smc-check=all</option>, please file a bug report and
+    hopefully we'll be able to fix the problem.</para>
+  </answer>
 </qandaentry>
 
 </qandadiv>
@@ -205,93 +208,89 @@
 <title>Valgrind behaves unexpectedly</title>
 
 <qandaentry id="faq.reports">
- <question id="q-reports">
-  <para>My program uses the C++ STL and string classes.  Valgrind
-  reports 'still reachable' memory leaks involving these classes
-  at the exit of the program, but there should be none.</para>
- </question>
- <answer id="a-reports">
-  <para>First of all: relax, it's probably not a bug, but a
-  feature.  Many implementations of the C++ standard libraries
-  use their own memory pool allocators.  Memory for quite a
-  number of destructed objects is not immediately freed and given
-  back to the OS, but kept in the pool(s) for later re-use.  The
-  fact that the pools are not freed at the exit() of the program
-  cause Valgrind to report this memory as still reachable.  The
-  behaviour not to free pools at the exit() could be called a bug
-  of the library though.</para>
+  <question id="q-reports">
+    <para>My program uses the C++ STL and string classes.  Valgrind
+    reports 'still reachable' memory leaks involving these classes at
+    the exit of the program, but there should be none.</para>
+  </question>
+  <answer id="a-reports">
+    <para>First of all: relax, it's probably not a bug, but a feature.
+    Many implementations of the C++ standard libraries use their own
+    memory pool allocators.  Memory for quite a number of destructed
+    objects is not immediately freed and given back to the OS, but kept
+    in the pool(s) for later re-use.  The fact that the pools are not
+    freed at the exit() of the program cause Valgrind to report this
+    memory as still reachable.  The behaviour not to free pools at the
+    exit() could be called a bug of the library though.</para>
 
-  <para>Using gcc, you can force the STL to use malloc and to
-  free memory as soon as possible by globally disabling memory
-  caching.  Beware!  Doing so will probably slow down your
-  program, sometimes drastically.</para>
-  <itemizedlist>
-   <listitem>
-    <para>With gcc 2.91, 2.95, 3.0 and 3.1, compile all source
-    using the STL with <literal>-D__USE_MALLOC</literal>. Beware!
-    This is removed from gcc starting with version 3.3.</para>
-   </listitem>
-   <listitem>
-    <para>With gcc 3.2.2 and later, you should export the environment
-    variable <literal>GLIBCPP_FORCE_NEW</literal> before running
-    your program.</para>
-   </listitem>
-   <listitem>
-    <para>With gcc 3.4 and later, that variable has changed name to
-    <literal>GLIBCXX_FORCE_NEW</literal>.</para>
-   </listitem>
-  </itemizedlist>
+    <para>Using gcc, you can force the STL to use malloc and to free
+    memory as soon as possible by globally disabling memory caching.
+    Beware!  Doing so will probably slow down your program, sometimes
+    drastically.</para>
+    <itemizedlist>
+      <listitem>
+        <para>With gcc 2.91, 2.95, 3.0 and 3.1, compile all source using
+        the STL with <literal>-D__USE_MALLOC</literal>. Beware!  This is
+        removed from gcc starting with version 3.3.</para>
+      </listitem>
+      <listitem>
+        <para>With gcc 3.2.2 and later, you should export the
+        environment variable <literal>GLIBCPP_FORCE_NEW</literal> before
+        running your program.</para>
+      </listitem>
+      <listitem>
+        <para>With gcc 3.4 and later, that variable has changed name to
+        <literal>GLIBCXX_FORCE_NEW</literal>.</para>
+      </listitem>
+    </itemizedlist>
 
-  <para>There are other ways to disable memory pooling: using the
-  <literal>malloc_alloc</literal> template with your objects (not
-  portable, but should work for gcc) or even writing your own
-  memory allocators. But all this goes beyond the scope of this
-  FAQ.  Start by reading <ulink
-  url="http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3">
-  http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3</ulink>
-  if you absolutely want to do that. But beware:</para>
+    <para>There are other ways to disable memory pooling: using the
+    <literal>malloc_alloc</literal> template with your objects (not
+    portable, but should work for gcc) or even writing your own memory
+    allocators. But all this goes beyond the scope of this FAQ.  Start
+    by reading 
+    <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3">
+    http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3</ulink> if
+    you absolutely want to do that. But beware:</para>
 
-  <orderedlist>
-   <listitem>
-    <para>there are currently changes underway for gcc which are
-    not totally reflected in the docs right now ("now" == 26 Apr
-    03)</para>
-   </listitem>
-   <listitem>
-    <para>allocators belong to the more messy parts of the STL
-    and people went to great lengths to make it portable across
-    platforms. Chances are good that your solution will work on
-    your platform, but not on others.</para>
-   </listitem>
-  </orderedlist>
+    <orderedlist>
+      <listitem>
+        <para>there are currently changes underway for gcc which are not
+        totally reflected in the docs right now ("now" == 26 Apr 03)</para>
+      </listitem>
+      <listitem>
+        <para>allocators belong to the more messy parts of the STL and
+        people went to great lengths to make it portable across
+        platforms. Chances are good that your solution will work on your
+        platform, but not on others.</para>
+      </listitem>
+    </orderedlist>
  </answer>
 </qandaentry>
 
 
 <qandaentry id="faq.unhelpful">
- <question id="q-unhelpful">
-  <para>The stack traces given by Memcheck (or another tool)
-  aren't helpful.  How can I improve them?</para>
- </question>
- <answer id="a-unhelpful">
-  <para>If they're not long enough, use
-  <literal>--num-callers</literal> to make them longer.</para>
-  <para>If they're not detailed enough, make sure you are
-  compiling with <literal>-g</literal> to add debug information.
-  And don't strip symbol tables (programs should be unstripped
-  unless you run 'strip' on them; some libraries ship
-  stripped).</para>
+  <question id="q-unhelpful">
+    <para>The stack traces given by Memcheck (or another tool) aren't
+    helpful.  How can I improve them?</para>
+  </question>
+  <answer id="a-unhelpful">
+    <para>If they're not long enough, use <option>--num-callers</option>
+    to make them longer.</para>
 
-  <para>Also, for leak reports involving shared objects, if the shared
-  object is unloaded before the program terminates, Valgrind will discard
-  the debug information and the error message will be full of
-  <literal>???</literal> entries.  The workaround here is to avoid calling
-  dlclose() on these shared objects.
-  </para>
+    <para>If they're not detailed enough, make sure you are compiling
+    with <option>-g</option> to add debug information.  And don't strip
+    symbol tables (programs should be unstripped unless you run 'strip'
+    on them; some libraries ship stripped).</para>
 
-  <para>Also, <literal>-fomit-frame-pointer</literal> and
-  <literal>-fstack-check</literal> can make stack traces
-  worse.</para>
+    <para>Also, for leak reports involving shared objects, if the shared
+    object is unloaded before the program terminates, Valgrind will
+    discard the debug information and the error message will be full of
+    <literal>???</literal> entries.  The workaround here is to avoid
+    calling dlclose() on these shared objects.</para>
+
+    <para>Also, <option>-fomit-frame-pointer</option> and
+    <option>-fstack-check</option> can make stack traces worse.</para>
 
   <para>Some example sub-traces:</para>
 
@@ -352,18 +351,18 @@
 </qandaentry>
 
 <qandaentry id="faq.aliases">
- <question id="q-aliases">
-  <para>The stack traces given by Memcheck (or another tool) seem to
-  have the wrong function name in them.  What's happening?</para>
- </question>
- <answer id="a-aliases">
-  <para>Occasionally Valgrind stack traces get the wrong function names.
-  This is caused by glibc using aliases to effectively give one function two
-  names.  Most of the time Valgrind chooses a suitable name, but very
-  occasionally it gets it wrong.
-  Examples we know of are printing 'bcmp' instead of 'memcmp', 'index'
-  instead of 'strchr', and 'rindex' instead of 'strrchr'.</para>
- </answer>
+  <question id="q-aliases">
+    <para>The stack traces given by Memcheck (or another tool) seem to
+    have the wrong function name in them.  What's happening?</para>
+  </question>
+  <answer id="a-aliases">
+    <para>Occasionally Valgrind stack traces get the wrong function
+    names.  This is caused by glibc using aliases to effectively give
+    one function two names.  Most of the time Valgrind chooses a
+    suitable name, but very occasionally it gets it wrong.  Examples we
+    know of are printing 'bcmp' instead of 'memcmp', 'index' instead of
+    'strchr', and 'rindex' instead of 'strrchr'.</para>
+  </answer>
 </qandaentry>
 
 </qandadiv>
@@ -375,53 +374,53 @@
 <title>Memcheck doesn't find my bug</title>
 
 <qandaentry id="faq.hiddenbug">
- <question id="q-hiddenbug">
-  <para>I try running "valgrind --tool=memcheck my_program" and
-  get Valgrind's startup message, but I don't get any errors and
-  I know my program has errors.</para>
- </question>
- <answer id="a-hiddenbug">
-  <para>There are two possible causes of this.</para>
+  <question id="q-hiddenbug">
+    <para>I try running "valgrind --tool=memcheck my_program" and get
+    Valgrind's startup message, but I don't get any errors and I know my
+    program has errors.</para>
+  </question>
+  <answer id="a-hiddenbug">
+    <para>There are two possible causes of this.</para>
 
-  <para>First, by default, Valgrind only traces the top-level process.
-  So if your program spawns children, they won't be traced by
-  Valgrind by default.  Also, if your program is started by a
-  shell script, Perl script, or something similar, Valgrind will
-  trace the shell, or the Perl interpreter, or equivalent.</para>
+    <para>First, by default, Valgrind only traces the top-level process.
+    So if your program spawns children, they won't be traced by Valgrind
+    by default.  Also, if your program is started by a shell script,
+    Perl script, or something similar, Valgrind will trace the shell, or
+    the Perl interpreter, or equivalent.</para>
 
-  <para>To trace child processes, use the
-  <literal>--trace-children=yes</literal> option.</para>
+    <para>To trace child processes, use the
+    <option>--trace-children=yes</option> option.</para>
 
-  <para>If you are tracing large trees of processes, it can be
-  less disruptive to have the output sent over the network.  Give
-  Valgrind the flag
-  <literal>--log-socket=127.0.0.1:12345</literal> (if you want
-  logging output sent to <literal>port 12345</literal> on
-  <literal>localhost</literal>).  You can use the
-  valgrind-listener program to listen on that port:</para>
+    <para>If you are tracing large trees of processes, it can be less
+    disruptive to have the output sent over the network.  Give Valgrind
+    the flag <option>--log-socket=127.0.0.1:12345</option> (if you want
+    logging output sent to <literal>port 12345</literal> on
+    <literal>localhost</literal>).  You can use the valgrind-listener
+    program to listen on that port:</para>
 <programlisting>
 valgrind-listener 12345
 </programlisting>
 
-  <para>Obviously you have to start the listener process first.
-  See the manual for more details.</para>
+    <para>Obviously you have to start the listener process first.  See
+    the manual for more details.</para>
 
-  <para>Second, if your program is statically linked, most Valgrind tools
-  won't work as well, because they won't be able to replace certain
-  functions, such as malloc(), with their own versions.  A key indicator of
-  this is if Memcheck says:
+    <para>Second, if your program is statically linked, most Valgrind
+    tools won't work as well, because they won't be able to replace
+    certain functions, such as malloc(), with their own versions.  A key
+    indicator of this is if Memcheck says:
 <programlisting>
 No malloc'd blocks -- no leaks are possible
 </programlisting>
-when you know your program calls malloc().  The workaround is to avoid
-statically linking your program.</para>
- </answer>
+    when you know your program calls malloc().  The workaround is to
+    avoid statically linking your program.</para>
+  </answer>
 </qandaentry>
 
 
 <qandaentry id="faq.overruns">
- <question id="q-overruns">
-  <para>Why doesn't Memcheck find the array overruns in this program?</para>
+  <question id="q-overruns">
+    <para>Why doesn't Memcheck find the array overruns in this
+    program?</para>
 <programlisting>
 int static[5];
 
@@ -435,13 +434,12 @@
   return 0;
 }
 </programlisting>
- </question>
- <answer id="a-overruns">
-  <para>Unfortunately, Memcheck doesn't do bounds checking on
-  static or stack arrays.  We'd like to, but it's just not
-  possible to do in a reasonable way that fits with how Memcheck
-  works.  Sorry.</para>
- </answer>
+  </question>
+  <answer id="a-overruns">
+    <para>Unfortunately, Memcheck doesn't do bounds checking on static
+    or stack arrays.  We'd like to, but it's just not possible to do in
+    a reasonable way that fits with how Memcheck works.  Sorry.</para>
+  </answer>
 </qandaentry>
 
 </qandadiv>
@@ -453,59 +451,57 @@
 <title>Miscellaneous</title>
 
 <qandaentry id="faq.writesupp">
- <question id="q-writesupp">
-  <para>I tried writing a suppression but it didn't work.  Can
-  you write my suppression for me?</para>
- </question>
- <answer id="a-writesupp">
-  <para>Yes!  Use the
-  <computeroutput>--gen-suppressions=yes</computeroutput> feature
-  to spit out suppressions automatically for you.  You can then
-  edit them if you like, eg.  combining similar automatically
-  generated suppressions using wildcards like
-  <literal>'*'</literal>.</para>
+  <question id="q-writesupp">
+    <para>I tried writing a suppression but it didn't work.  Can you
+    write my suppression for me?</para>
+  </question>
+  <answer id="a-writesupp">
+    <para>Yes!  Use the <option>--gen-suppressions=yes</option> feature
+    to spit out suppressions automatically for you.  You can then edit
+    them if you like, eg.  combining similar automatically generated
+    suppressions using wildcards like <literal>'*'</literal>.</para>
 
-  <para>If you really want to write suppressions by hand, read
-  the manual carefully.  Note particularly that C++ function
-  names must be <literal>_mangled_</literal>.</para>
- </answer>
+    <para>If you really want to write suppressions by hand, read the
+    manual carefully.  Note particularly that C++ function names must be
+    <literal>_mangled_</literal>.</para>
+  </answer>
 </qandaentry>
 
 
 <qandaentry id="faq.deflost">
- <question id="q=deflost">
-  <para>With Memcheck/Addrcheck's memory leak detector, what's
-  the difference between "definitely lost", "possibly lost",
-  "still reachable", and "suppressed"?</para>
- </question>
- <answer id="a-deflost">
-  <para>The details are in the Memcheck section of the user manual.</para>
+  <question id="q-deflost">
+    <para>With Memcheck/Addrcheck's memory leak detector, what's the
+    difference between "definitely lost", "possibly lost", "still
+    reachable", and "suppressed"?</para>
+  </question>
+  <answer id="a-deflost">
+    <para>The details are in the Memcheck section of the user
+    manual.</para>
 
-  <para>In short:</para>
-   <itemizedlist>
-    <listitem>
-     <para>"definitely lost" means your program is leaking memory
-     -- fix it!</para>
-    </listitem>
-    <listitem>
-     <para>"possibly lost" means your program is probably leaking
-     memory, unless you're doing funny things with
-     pointers.</para>
-    </listitem>
-    <listitem>
-     <para>"still reachable" means your program is probably ok --
-     it didn't free some memory it could have.  This is quite
-     common and often reasonable.  Don't use
-     <computeroutput>--show-reachable=yes</computeroutput> if you
-     don't want to see these reports.</para>
-    </listitem>
-    <listitem>
-     <para>"suppressed" means that a leak error has been
-     suppressed.  There are some suppressions in the default
-     suppression files.  You can ignore suppressed errors.</para>
-    </listitem>
-   </itemizedlist>
- </answer>
+    <para>In short:</para>
+    <itemizedlist>
+      <listitem>
+        <para>"definitely lost" means your program is leaking memory --
+        fix it!</para>
+      </listitem>
+      <listitem>
+        <para>"possibly lost" means your program is probably leaking
+        memory, unless you're doing funny things with pointers.</para>
+      </listitem>
+      <listitem>
+        <para>"still reachable" means your program is probably ok -- it
+        didn't free some memory it could have.  This is quite common and
+        often reasonable.  Don't use
+        <option>--show-reachable=yes</option> if you don't want to see
+        these reports.</para>
+      </listitem>
+      <listitem>
+        <para>"suppressed" means that a leak error has been suppressed.
+        There are some suppressions in the default suppression files.
+        You can ignore suppressed errors.</para>
+      </listitem>
+    </itemizedlist>
+  </answer>
 </qandaentry>
 
 </qandadiv>
@@ -517,21 +513,16 @@
 <title>How To Get Further Assistance</title>
 
 <qandaentry id="e-help">
-
- <answer id="a-help">
+  <!-- <question><para/></question> -->
+  <answer id="a-help">
   <para>Please read all of this section before posting.</para>
 
   <para>If you think an answer is incomplete or inaccurate, please
   e-mail <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink>.</para>
-<!--
-  <para>Read the appropriate section(s) of the <xref linkend="set-index"/>.</para>
--->
+
   <para>Read the appropriate section(s) of the 
   <ulink url="&vg-bookset;">Valgrind Documentation</ulink>.</para>
 
-<!--
-  <para>Read the <xref linkend="dist"/>.</para>
--->
   <para>Read the 
   <ulink url="&vg-dist-docs;">Distribution Documents</ulink>.</para>
 
@@ -539,29 +530,30 @@
   <ulink url="http://news.gmane.org/gmane.comp.debugging.valgrind">valgrind-users</ulink> mailing list archives, using the group name 
   <computeroutput>gmane.comp.debugging.valgrind</computeroutput>.</para>
 
-  <para>Only when you have tried all of these things and are still stuck,
-  should you post to the <ulink url="&vg-users-list;">valgrind-users
-  mailing list</ulink>. In which case, please read the following
-  carefully.  Making a complete posting will greatly increase the chances
-  that an expert or fellow user reading it will have enough information
-  and motivation to reply.</para>
+  <para>Only when you have tried all of these things and are still
+  stuck, should you post to the 
+  <ulink url="&vg-users-list;">valgrind-users mailing list</ulink>. In
+  which case, please read the following carefully.  Making a complete
+  posting will greatly increase the chances that an expert or fellow
+  user reading it will have enough information and motivation to
+  reply.</para>
 
-  <para>Make sure you give full details of the problem,
-  including the full output of <computeroutput>valgrind -v</computeroutput>, 
-  if applicable.  Also which Linux distribution you're using (Red Hat, Debian, etc) 
-  and its version number.</para>
+  <para>Make sure you give full details of the problem, including the
+  full output of <computeroutput>valgrind -v</computeroutput>, if
+  applicable.  Also which Linux distribution you're using (Red Hat,
+  Debian, etc) and its version number.</para>
 
-  <para>You are in little danger of making your posting too long
-  unless you include large chunks of valgrind's (unsuppressed)
-  output, so err on the side of giving too much information.</para>
+  <para>You are in little danger of making your posting too long unless
+  you include large chunks of Valgrind's (unsuppressed) output, so err
+  on the side of giving too much information.</para>
 
-  <para>Clearly written subject lines and message bodies are appreciated,
-  too.</para>
+  <para>Clearly written subject lines and message bodies are
+  appreciated, too.</para>
 
   <para>Finally, remember that, despite the fact that most of the
-  community are very helpful and responsive to emailed questions,
-  you are probably requesting help from unpaid volunteers, so you
-  have no guarantee of receiving an answer.</para>
+  community are very helpful and responsive to emailed questions, you
+  are probably requesting help from unpaid volunteers, so you have no
+  guarantee of receiving an answer.</para>
 </answer>
 
 </qandaentry>
diff --git a/docs/xml/dist-docs.xml b/docs/xml/dist-docs.xml
index 85302a8..e963adf 100644
--- a/docs/xml/dist-docs.xml
+++ b/docs/xml/dist-docs.xml
@@ -6,17 +6,17 @@
 
 <book id="dist" xreflabel="Distribution Documents">
 
-  <bookinfo>
-    <title>Valgrind Distribution Documents</title>
+<bookinfo>
+  <title>Valgrind Distribution Documents</title>
   <releaseinfo>&rel-type; &rel-version; &rel-date;</releaseinfo>
   <copyright>
     <year>&vg-lifespan;</year>
     <holder><ulink url="&vg-developers;">Valgrind Developers</ulink></holder>
   </copyright>
-  <author>
-    <email><ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></email>
-  </author>
-  </bookinfo>
+  <legalnotice>
+    <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para>
+  </legalnotice>
+</bookinfo>
 
   <!-- Nb: because these are all text files, we have to wrap -->
   <!-- them in suitable XML.  Hence the chapter/title stuff  -->
diff --git a/docs/xml/index.xml b/docs/xml/index.xml
index 0feec65..475e631 100644
--- a/docs/xml/index.xml
+++ b/docs/xml/index.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0"?> <!-- -*- sgml -*- -->
 <!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" 
 [ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
 
 
diff --git a/docs/xml/manual-core.xml b/docs/xml/manual-core.xml
index 4585812..c825720 100644
--- a/docs/xml/manual-core.xml
+++ b/docs/xml/manual-core.xml
@@ -7,81 +7,77 @@
 <chapter id="manual-core" xreflabel="Valgrind's core">
 <title>Using and understanding the Valgrind core</title>
 
-<para>This section describes the Valgrind core services, flags
-and behaviours.  That means it is relevant regardless of what
-particular tool you are using.  A point of terminology: most
-references to "valgrind" in the rest of this section (Section 2)
-refer to the valgrind core services.</para>
+<para>This section describes the Valgrind core services, flags and
+behaviours.  That means it is relevant regardless of what particular
+tool you are using.  A point of terminology: most references to
+"valgrind" in the rest of this section (Section 2) refer to the Valgrind
+core services.</para>
 
 <sect1 id="manual-core.whatdoes" 
        xreflabel="What Valgrind does with your program">
 <title>What Valgrind does with your program</title>
 
-<para>Valgrind is designed to be as non-intrusive as possible. It
-works directly with existing executables. You don't need to
-recompile, relink, or otherwise modify, the program to be
-checked.</para>
+<para>Valgrind is designed to be as non-intrusive as possible. It works
+directly with existing executables. You don't need to recompile, relink,
+or otherwise modify, the program to be checked.</para>
 
-<para>Simply put <computeroutput>valgrind
---tool=tool_name</computeroutput> at the start of the command
-line normally used to run the program.  For example, if want to
-run the command <computeroutput>ls -l</computeroutput> using the
-heavyweight memory-checking tool Memcheck, issue the
-command:</para>
+<para>Simply put 
+<computeroutput>valgrind --tool=tool_name</computeroutput> 
+at the start of the command line normally used to run the program.  For
+example, if want to run the command 
+<computeroutput>ls -l</computeroutput> using the heavyweight
+memory-checking tool Memcheck, issue the command:</para>
 
 <programlisting><![CDATA[
 valgrind --tool=memcheck ls -l]]></programlisting>
 
 <para>(Memcheck is the default, so if you want to use it you can
-actually omit the <computeroutput>--tool</computeroutput> flag.</para>
+actually omit the <option>--tool</option> flag.</para>
 
-<para>Regardless of which tool is in use, Valgrind takes control
-of your program before it starts.  Debugging information is read
-from the executable and associated libraries, so that error
-messages and other outputs can be phrased in terms of source code
-locations (if that is appropriate).</para>
+<para>Regardless of which tool is in use, Valgrind takes control of your
+program before it starts.  Debugging information is read from the
+executable and associated libraries, so that error messages and other
+outputs can be phrased in terms of source code locations (if that is
+appropriate).</para>
 
-<para>Your program is then run on a synthetic CPU provided by
-the Valgrind core.  As new code is executed for the first time,
-the core hands the code to the selected tool.  The tool adds its
-own instrumentation code to this and hands the result back to the
-core, which coordinates the continued execution of this
-instrumented code.</para>
+<para>Your program is then run on a synthetic CPU provided by the
+Valgrind core.  As new code is executed for the first time, the core
+hands the code to the selected tool.  The tool adds its own
+instrumentation code to this and hands the result back to the core,
+which coordinates the continued execution of this instrumented
+code.</para>
 
-<para>The amount of instrumentation code added varies widely
-between tools.  At one end of the scale, Memcheck adds code to
-check every memory access and every value computed, increasing
-the size of the code at least 12 times, and making it run 25-50
-times slower than natively.  At the other end of the spectrum,
-the ultra-trivial "none" tool (a.k.a. Nulgrind) adds no
-instrumentation at all and causes in total "only" about a 4 times
-slowdown.</para>
+<para>The amount of instrumentation code added varies widely between
+tools.  At one end of the scale, Memcheck adds code to check every
+memory access and every value computed, increasing the size of the code
+at least 12 times, and making it run 25-50 times slower than natively.
+At the other end of the spectrum, the ultra-trivial "none" tool
+(a.k.a. Nulgrind) adds no instrumentation at all and causes in total
+"only" about a 4 times slowdown.</para>
 
-<para>Valgrind simulates every single instruction your program
-executes.  Because of this, the active tool checks, or profiles,
-not only the code in your application but also in all supporting
-dynamically-linked (<computeroutput>.so</computeroutput>-format)
-libraries, including the GNU C library, the X client libraries,
-Qt, if you work with KDE, and so on.</para>
+<para>Valgrind simulates every single instruction your program executes.
+Because of this, the active tool checks, or profiles, not only the code
+in your application but also in all supporting dynamically-linked
+(<computeroutput>.so</computeroutput>-format) libraries, including the
+GNU C library, the X client libraries, Qt, if you work with KDE, and so
+on.</para>
 
-<para>If you're using one of the error-detection tools, Valgrind
-will often detect errors in libraries, for example the GNU C or
-X11 libraries, which you have to use.  You might not be
-interested in these errors, since you probably have no control
-over that code.  Therefore, Valgrind allows you to selectively
-suppress errors, by recording them in a suppressions file which
-is read when Valgrind starts up.  The build mechanism attempts to
-select suppressions which give reasonable behaviour for the libc
-and XFree86 versions detected on your machine.  To make it easier
-to write suppressions, you can use the
-<computeroutput>--gen-suppressions=yes</computeroutput> option
-which tells Valgrind to print out a suppression for each error
-that appears, which you can then copy into a suppressions
-file.</para>
+<para>If you're using one of the error-detection tools, Valgrind will
+often detect errors in libraries, for example the GNU C or X11
+libraries, which you have to use.  You might not be interested in these
+errors, since you probably have no control over that code.  Therefore,
+Valgrind allows you to selectively suppress errors, by recording them in
+a suppressions file which is read when Valgrind starts up.  The build
+mechanism attempts to select suppressions which give reasonable
+behaviour for the libc and XFree86 versions detected on your machine.
+To make it easier to write suppressions, you can use the
+<option>--gen-suppressions=yes</option> option which tells Valgrind to
+print out a suppression for each error that appears, which you can then
+copy into a suppressions file.</para>
 
-<para>Different error-checking tools report different kinds of
-errors.  The suppression mechanism therefore allows you to say
-which tool or tool(s) each suppression applies to.</para>
+<para>Different error-checking tools report different kinds of errors.
+The suppression mechanism therefore allows you to say which tool or
+tool(s) each suppression applies to.</para>
 
 </sect1>
 
@@ -89,221 +85,199 @@
 <sect1 id="manual-core.started" xreflabel="Getting started">
 <title>Getting started</title>
 
-<para>First off, consider whether it might be beneficial to
-recompile your application and supporting libraries with
-debugging info enabled (the <computeroutput>-g</computeroutput>
-flag).  Without debugging info, the best Valgrind tools will be
-able to do is guess which function a particular piece of code
-belongs to, which makes both error messages and profiling output
-nearly useless.  With <computeroutput>-g</computeroutput>, you'll
-hopefully get messages which point directly to the relevant
-source code lines.</para>
+<para>First off, consider whether it might be beneficial to recompile
+your application and supporting libraries with debugging info enabled
+(the <option>-g</option> flag).  Without debugging info, the best
+Valgrind tools will be able to do is guess which function a particular
+piece of code belongs to, which makes both error messages and profiling
+output nearly useless.  With <option>-g</option>, you'll hopefully get
+messages which point directly to the relevant source code lines.</para>
 
-<para>Another flag you might like to consider, if you are working
-with C++, is <computeroutput>-fno-inline</computeroutput>.  That
-makes it easier to see the function-call chain, which can help
-reduce confusion when navigating around large C++ apps.  For
-whatever it's worth, debugging OpenOffice.org with Memcheck is a
-bit easier when using this flag.
-You don't have to do this, but doing so helps Valgrind
-produce more accurate and less confusing error reports.  Chances
-are you're set up like this already, if you intended to debug
-your program with GNU gdb, or some other debugger.</para>
+<para>Another flag you might like to consider, if you are working with
+C++, is <option>-fno-inline</option>.  That makes it easier to see the
+function-call chain, which can help reduce confusion when navigating
+around large C++ apps.  For whatever it's worth, debugging
+OpenOffice.org with Memcheck is a bit easier when using this flag.  You
+don't have to do this, but doing so helps Valgrind produce more accurate
+and less confusing error reports.  Chances are you're set up like this
+already, if you intended to debug your program with GNU gdb, or some
+other debugger.</para>
 
-<para>This paragraph applies only if you plan to use Memcheck: On
-rare occasions, optimisation levels at
-<computeroutput>-O2</computeroutput> and above have been observed
-to generate code which fools Memcheck into wrongly reporting
-uninitialised value errors.  We have looked in detail into fixing
-this, and unfortunately the result is that doing so would give a
-further significant slowdown in what is already a slow tool.  So
-the best solution is to turn off optimisation altogether.  Since
-this often makes things unmanagably slow, a plausible compromise
-is to use <computeroutput>-O</computeroutput>.  This gets you the
-majority of the benefits of higher optimisation levels whilst
-keeping relatively small the chances of false complaints from
-Memcheck.  All other tools (as far as we know) are unaffected by
-optimisation level.</para>
+<para>This paragraph applies only if you plan to use Memcheck: On rare
+occasions, optimisation levels at <computeroutput>-O2</computeroutput>
+and above have been observed to generate code which fools Memcheck into
+wrongly reporting uninitialised value errors.  We have looked in detail
+into fixing this, and unfortunately the result is that doing so would
+give a further significant slowdown in what is already a slow tool.  So
+the best solution is to turn off optimisation altogether.  Since this
+often makes things unmanagably slow, a plausible compromise is to use
+<computeroutput>-O</computeroutput>.  This gets you the majority of the
+benefits of higher optimisation levels whilst keeping relatively small
+the chances of false complaints from Memcheck.  All other tools (as far
+as we know) are unaffected by optimisation level.</para>
 
-<para>Valgrind understands both the older "stabs" debugging
-format, used by gcc versions prior to 3.1, and the newer DWARF2
-format used by gcc 3.1 and later.  We continue to refine and
-debug our debug-info readers, although the majority of effort
-will naturally enough go into the newer DWARF2 reader.</para>
+<para>Valgrind understands both the older "stabs" debugging format, used
+by gcc versions prior to 3.1, and the newer DWARF2 format used by gcc
+3.1 and later.  We continue to refine and debug our debug-info readers,
+although the majority of effort will naturally enough go into the newer
+DWARF2 reader.</para>
 
 <para>When you're ready to roll, just run your application as you
-would normally, but place <computeroutput>valgrind
---tool=tool_name</computeroutput> in front of your usual
-command-line invocation.  Note that you should run the real
-(machine-code) executable here.  If your application is started
-by, for example, a shell or perl script, you'll need to modify it
-to invoke Valgrind on the real executables.  Running such scripts
-directly under Valgrind will result in you getting error reports
-pertaining to <computeroutput>/bin/sh</computeroutput>,
-<computeroutput>/usr/bin/perl</computeroutput>, or whatever
-interpreter you're using.  This may not be what you want and can
-be confusing.  You can force the issue by giving the flag
-<computeroutput>--trace-children=yes</computeroutput>, but
-confusion is still likely.</para>
+would normally, but place 
+<computeroutput>valgrind --tool=tool_name</computeroutput> in front of
+your usual command-line invocation.  Note that you should run the real
+(machine-code) executable here.  If your application is started by, for
+example, a shell or perl script, you'll need to modify it to invoke
+Valgrind on the real executables.  Running such scripts directly under
+Valgrind will result in you getting error reports pertaining to
+<computeroutput>/bin/sh</computeroutput>,
+<computeroutput>/usr/bin/perl</computeroutput>, or whatever interpreter
+you're using.  This may not be what you want and can be confusing.  You
+can force the issue by giving the flag
+<option>--trace-children=yes</option>, but confusion is still
+likely.</para>
 
 </sect1>
 
 
-<sect1 id="manual-core.comment" xreflabel="The commentary">
-<title>The commentary</title>
+<sect1 id="manual-core.comment" xreflabel="The Commentary">
+<title>The Commentary</title>
 
-<para>Valgrind tools write a commentary, a stream of text,
-detailing error reports and other significant events.  All lines
-in the commentary have following form:
+<para>Valgrind tools write a commentary, a stream of text, detailing
+error reports and other significant events.  All lines in the commentary
+have following form:
 
 <programlisting><![CDATA[
 ==12345== some-message-from-Valgrind]]></programlisting>
 </para>
 
-<para>The <computeroutput>12345</computeroutput> is the process
-ID.  This scheme makes it easy to distinguish program output from
-Valgrind commentary, and also easy to differentiate commentaries
-from different processes which have become merged together, for
-whatever reason.</para>
+<para>The <computeroutput>12345</computeroutput> is the process ID.
+This scheme makes it easy to distinguish program output from Valgrind
+commentary, and also easy to differentiate commentaries from different
+processes which have become merged together, for whatever reason.</para>
 
-<para>By default, Valgrind tools write only essential messages to
-the commentary, so as to avoid flooding you with information of
-secondary importance.  If you want more information about what is
-happening, re-run, passing the
-<computeroutput>-v</computeroutput> flag to Valgrind.
-A second <computeroutput>-v</computeroutput> gives yet more detail.
+<para>By default, Valgrind tools write only essential messages to the
+commentary, so as to avoid flooding you with information of secondary
+importance.  If you want more information about what is happening,
+re-run, passing the <option>-v</option> flag to Valgrind.  A second
+<option>-v</option> gives yet more detail.
 </para>
 
-<para>You can direct the commentary to three different
-places:</para>
+<para>You can direct the commentary to three different places:</para>
 
 <orderedlist>
 
- <listitem id="manual-core.out2fd" xreflabel="Directing output to fd">
-   <para>The default: send it to a file descriptor, which is by
-   default 2 (stderr).  So, if you give the core no options, it
-   will write commentary to the standard error stream.  If you
-   want to send it to some other file descriptor, for example
-   number 9, you can specify
-   <computeroutput>--log-fd=9</computeroutput>.</para>
-   <para>This is the simplest and most common arrangement, but can
-   cause problems when Valgrinding entire trees of
-   processes which expect specific file descriptors, particularly
-   stdin/stdout/stderr, to be available for their own use.
-   </para>
+  <listitem id="manual-core.out2fd" xreflabel="Directing output to fd">
+    <para>The default: send it to a file descriptor, which is by default
+    2 (stderr).  So, if you give the core no options, it will write
+    commentary to the standard error stream.  If you want to send it to
+    some other file descriptor, for example number 9, you can specify
+    <option>--log-fd=9</option>.</para>
+
+    <para>This is the simplest and most common arrangement, but can
+    cause problems when valgrinding entire trees of processes which
+    expect specific file descriptors, particularly stdin/stdout/stderr,
+    to be available for their own use.</para>
   </listitem>
 
   <listitem id="manual-core.out2file" 
-            xreflabel="Directing output to file">
-   <para>A less intrusive option is to write the commentary to a
-   file, which you specify by
-   <computeroutput>--log-file=filename</computeroutput>.  Note
-   carefully that the commentary is <command>not</command>
-   written to the file you specify, but instead to one called
-   <computeroutput>filename.12345</computeroutput>, if for
-   example the pid of the traced process is 12345.  This is
-   helpful when valgrinding a whole tree of processes at once,
-   since it means that each process writes to its own logfile,
-   rather than the result being jumbled up in one big
-   logfile.  If <computeroutput>filename.12345</computeroutput> already
-   exists, then it will name new files
-   <computeroutput>filename.12345.1</computeroutput> and so on.
-   </para>
+            xreflabel="Directing output to file"> <para>A less intrusive
+    option is to write the commentary to a file, which you specify by
+    <option>--log-file=filename</option>.  Note carefully that the
+    commentary is <command>not</command> written to the file you
+    specify, but instead to one called
+    <filename>filename.12345</filename>, if for example the pid of the
+    traced process is 12345.  This is helpful when valgrinding a whole
+    tree of processes at once, since it means that each process writes
+    to its own logfile, rather than the result being jumbled up in one
+    big logfile.  If <filename>filename.12345</filename> already exists,
+    then it will name new files <filename>filename.12345.1</filename>
+    and so on.</para>
 
-   <para>If you want to specify precisely the file name to use,
-   without the trailing
-   <computeroutput>.12345</computeroutput> part, you can instead use
-   <computeroutput>--log-file-exactly=filename</computeroutput>.
-   </para>
+    <para>If you want to specify precisely the file name to use, without
+    the trailing <computeroutput>.12345</computeroutput> part, you can
+    instead use <option>--log-file-exactly=filename</option>.</para>
 
-   <para>You can also use the
-   <computeroutput>--log-file-qualifier=&lt;VAR&gt;</computeroutput> option
-   to modify the filename via according to the environment variable
-   <computeroutput>VAR</computeroutput>.  This is rarely needed, but
-   very useful in certain circumstances (eg. when running MPI programs).
-   In this case, the trailing <computeroutput>.12345</computeroutput>
-   part is replaced by the contents of
-   <computeroutput>$VAR</computeroutput>.  The idea is that you
-   specify a variable which will be set differently for each process
-   in the job, for example <computeroutput>BPROC_RANK</computeroutput>
-   or whatever is applicable in your MPI setup.
-   </para>
+    <para>You can also use the
+    <option>--log-file-qualifier=&lt;VAR&gt;</option> option to modify
+    the filename via according to the environment variable
+    <varname>VAR</varname>.  This is rarely needed, but very useful in
+    certain circumstances (eg. when running MPI programs).  In this
+    case, the trailing <computeroutput>.12345</computeroutput> part is
+    replaced by the contents of <varname>$VAR</varname>.  The idea is
+    that you specify a variable which will be set differently for each
+    process in the job, for example
+    <computeroutput>BPROC_RANK</computeroutput> or whatever is
+    applicable in your MPI setup.</para>
   </listitem>
 
   <listitem id="manual-core.out2socket" 
-            xreflabel="Directing output to network socket">
-   <para>The least intrusive option is to send the commentary to
-   a network socket.  The socket is specified as an IP address
-   and port number pair, like this:
-   <computeroutput>--log-socket=192.168.0.1:12345</computeroutput>
-   if you want to send the output to host IP 192.168.0.1 port
-   12345 (I have no idea if 12345 is a port of pre-existing
-   significance).  You can also omit the port number:
-   <computeroutput>--log-socket=192.168.0.1</computeroutput>, in
-   which case a default port of 1500 is used.  This default is
-   defined by the constant
-   <computeroutput>VG_CLO_DEFAULT_LOGPORT</computeroutput> in the
-   sources.</para>
+            xreflabel="Directing output to network socket"> <para>The
+    least intrusive option is to send the commentary to a network
+    socket.  The socket is specified as an IP address and port number
+    pair, like this: <option>--log-socket=192.168.0.1:12345</option> if
+    you want to send the output to host IP 192.168.0.1 port 12345 (I
+    have no idea if 12345 is a port of pre-existing significance).  You
+    can also omit the port number:
+    <option>--log-socket=192.168.0.1</option>, in which case a default
+    port of 1500 is used.  This default is defined by the constant
+    <computeroutput>VG_CLO_DEFAULT_LOGPORT</computeroutput> in the
+    sources.</para>
 
-   <para>Note, unfortunately, that you have to use an IP address
-   here, rather than a hostname.</para>
+    <para>Note, unfortunately, that you have to use an IP address here,
+    rather than a hostname.</para>
 
-   <para>Writing to a network socket is pretty useless if you
-   don't have something listening at the other end.  We provide a
-   simple listener program,
-   <computeroutput>valgrind-listener</computeroutput>, which
-   accepts connections on the specified port and copies whatever
-   it is sent to stdout.  Probably someone will tell us this is a
-   horrible security risk.  It seems likely that people will
-   write more sophisticated listeners in the fullness of
-   time.</para>
+    <para>Writing to a network socket is pretty useless if you don't
+    have something listening at the other end.  We provide a simple
+    listener program,
+    <computeroutput>valgrind-listener</computeroutput>, which accepts
+    connections on the specified port and copies whatever it is sent to
+    stdout.  Probably someone will tell us this is a horrible security
+    risk.  It seems likely that people will write more sophisticated
+    listeners in the fullness of time.</para>
 
-   <para>valgrind-listener can accept simultaneous connections
-   from up to 50 valgrinded processes.  In front of each line of
-   output it prints the current number of active connections in
-   round brackets.</para>
+    <para>valgrind-listener can accept simultaneous connections from up
+    to 50 valgrinded processes.  In front of each line of output it
+    prints the current number of active connections in round
+    brackets.</para>
 
-   <para>valgrind-listener accepts two command-line flags:</para>
+    <para>valgrind-listener accepts two command-line flags:</para>
     <itemizedlist>
-     <listitem>
-      <para><computeroutput>-e</computeroutput> or 
-      <computeroutput>--exit-at-zero</computeroutput>: when the
-      number of connected processes falls back to zero, exit.
-      Without this, it will run forever, that is, until you send
-      it Control-C.</para>
-     </listitem>
-     <listitem>
-      <para><computeroutput>portnumber</computeroutput>: changes
-      the port it listens on from the default (1500).  The
-      specified port must be in the range 1024 to 65535.  The
-      same restriction applies to port numbers specified by a
-      <computeroutput>--log-socket=</computeroutput> to Valgrind
-      itself.</para>
-     </listitem>
+       <listitem>
+         <para><option>-e</option> or <option>--exit-at-zero</option>: 
+         when the number of connected processes falls back to zero,
+         exit.  Without this, it will run forever, that is, until you
+         send it Control-C.</para>
+       </listitem>
+       <listitem>
+        <para><option>portnumber</option>: changes the port it listens
+        on from the default (1500).  The specified port must be in the
+        range 1024 to 65535.  The same restriction applies to port
+        numbers specified by a <option>--log-socket</option> to
+        Valgrind itself.</para>
+      </listitem>
     </itemizedlist>
 
-    <para>If a valgrinded process fails to connect to a listener,
-    for whatever reason (the listener isn't running, invalid or
-    unreachable host or port, etc), Valgrind switches back to
-    writing the commentary to stderr.  The same goes for any
-    process which loses an established connection to a listener.
-    In other words, killing the listener doesn't kill the
-    processes sending data to it.</para>
+    <para>If a valgrinded process fails to connect to a listener, for
+    whatever reason (the listener isn't running, invalid or unreachable
+    host or port, etc), Valgrind switches back to writing the commentary
+    to stderr.  The same goes for any process which loses an established
+    connection to a listener.  In other words, killing the listener
+    doesn't kill the processes sending data to it.</para>
   </listitem>
- </orderedlist>
 
-<para>Here is an important point about the relationship between
-the commentary and profiling output from tools.  The commentary
-contains a mix of messages from the Valgrind core and the
-selected tool.  If the tool reports errors, it will report them
-to the commentary.  However, if the tool does profiling, the
-profile data will be written to a file of some kind, depending on
-the tool, and independent of what
-<computeroutput>--log-*</computeroutput> options are in force.
-The commentary is intended to be a low-bandwidth, human-readable
-channel.  Profiling data, on the other hand, is usually
-voluminous and not meaningful without further processing, which
-is why we have chosen this arrangement.</para>
+</orderedlist>
+
+<para>Here is an important point about the relationship between the
+commentary and profiling output from tools.  The commentary contains a
+mix of messages from the Valgrind core and the selected tool.  If the
+tool reports errors, it will report them to the commentary.  However, if
+the tool does profiling, the profile data will be written to a file of
+some kind, depending on the tool, and independent of what
+<option>--log-*</option> options are in force.  The commentary is
+intended to be a low-bandwidth, human-readable channel.  Profiling data,
+on the other hand, is usually voluminous and not meaningful without
+further processing, which is why we have chosen this arrangement.</para>
 
 </sect1>
 
@@ -312,8 +286,8 @@
 <title>Reporting of errors</title>
 
 <para>When one of the error-checking tools (Memcheck, Addrcheck,
-Helgrind) detects something bad happening in the program, an
-error message is written to the commentary.  For example:</para>
+Helgrind) detects something bad happening in the program, an error
+message is written to the commentary.  For example:</para>
 
 <programlisting><![CDATA[
 ==25832== Invalid read of size 4
@@ -321,42 +295,39 @@
 ==25832==    by 0x80487AF: main (bogon.cpp:66)
 ==25832==  Address 0xBFFFF74C is not stack'd, malloc'd or free'd]]></programlisting>
 
-<para>This message says that the program did an illegal 4-byte
-read of address 0xBFFFF74C, which, as far as Memcheck can tell,
-is not a valid stack address, nor corresponds to any currently
-malloc'd or free'd blocks.  The read is happening at line 45 of
-<filename>bogon.cpp</filename>, called from line 66 of the same
-file, etc.  For errors associated with an identified
-malloc'd/free'd block, for example reading free'd memory,
-Valgrind reports not only the location where the error happened,
-but also where the associated block was malloc'd/free'd.</para>
+<para>This message says that the program did an illegal 4-byte read of
+address 0xBFFFF74C, which, as far as Memcheck can tell, is not a valid
+stack address, nor corresponds to any currently malloc'd or free'd
+blocks.  The read is happening at line 45 of
+<filename>bogon.cpp</filename>, called from line 66 of the same file,
+etc.  For errors associated with an identified malloc'd/free'd block,
+for example reading free'd memory, Valgrind reports not only the
+location where the error happened, but also where the associated block
+was malloc'd/free'd.</para>
 
-<para>Valgrind remembers all error reports.  When an error is
-detected, it is compared against old reports, to see if it is a
-duplicate.  If so, the error is noted, but no further commentary
-is emitted.  This avoids you being swamped with bazillions of
-duplicate error reports.</para>
+<para>Valgrind remembers all error reports.  When an error is detected,
+it is compared against old reports, to see if it is a duplicate.  If so,
+the error is noted, but no further commentary is emitted.  This avoids
+you being swamped with bazillions of duplicate error reports.</para>
 
-<para>If you want to know how many times each error occurred, run
-with the <computeroutput>-v</computeroutput> option.  When
-execution finishes, all the reports are printed out, along with,
-and sorted by, their occurrence counts.  This makes it easy to
-see which errors have occurred most frequently.</para>
+<para>If you want to know how many times each error occurred, run with
+the <option>-v</option> option.  When execution finishes, all the
+reports are printed out, along with, and sorted by, their occurrence
+counts.  This makes it easy to see which errors have occurred most
+frequently.</para>
 
-<para>Errors are reported before the associated operation
-actually happens.  If you're using a tool (Memcheck, Addrcheck)
-which does address checking, and your program attempts to read
-from address zero, the tool will emit a message to this effect,
-and the program will then duly die with a segmentation
-fault.</para>
+<para>Errors are reported before the associated operation actually
+happens.  If you're using a tool (Memcheck, Addrcheck) which does
+address checking, and your program attempts to read from address zero,
+the tool will emit a message to this effect, and the program will then
+duly die with a segmentation fault.</para>
 
-<para>In general, you should try and fix errors in the order that
-they are reported.  Not doing so can be confusing.  For example,
-a program which copies uninitialised values to several memory
-locations, and later uses them, will generate several error
-messages, when run on Memcheck.  The first such error message may
-well give the most direct clue to the root cause of the
-problem.</para>
+<para>In general, you should try and fix errors in the order that they
+are reported.  Not doing so can be confusing.  For example, a program
+which copies uninitialised values to several memory locations, and later
+uses them, will generate several error messages, when run on Memcheck.
+The first such error message may well give the most direct clue to the
+root cause of the problem.</para>
 
 <para>The process of detecting duplicate errors is quite an
 expensive one and can become a significant performance overhead
@@ -371,10 +342,9 @@
 if necessary.</para>
 
 <para>To avoid this cutoff you can use the
-<computeroutput>--error-limit=no</computeroutput> flag.  Then
-Valgrind will always show errors, regardless of how many there
-are.  Use this flag carefully, since it may have a bad effect on
-performance.</para>
+<option>--error-limit=no</option> flag.  Then Valgrind will always show
+errors, regardless of how many there are.  Use this flag carefully,
+since it may have a bad effect on performance.</para>
 
 </sect1>
 
@@ -382,136 +352,124 @@
 <sect1 id="manual-core.suppress" xreflabel="Suppressing errors">
 <title>Suppressing errors</title>
 
-<para>The error-checking tools detect numerous problems in the
-base libraries, such as the GNU C library, and the XFree86 client
-libraries, which come pre-installed on your GNU/Linux system.
-You can't easily fix these, but you don't want to see these
-errors (and yes, there are many!)  So Valgrind reads a list of
-errors to suppress at startup.  A default suppression file is
-cooked up by the <computeroutput>./configure</computeroutput>
-script when the system is built.</para>
+<para>The error-checking tools detect numerous problems in the base
+libraries, such as the GNU C library, and the XFree86 client libraries,
+which come pre-installed on your GNU/Linux system.  You can't easily fix
+these, but you don't want to see these errors (and yes, there are many!)
+So Valgrind reads a list of errors to suppress at startup.  A default
+suppression file is cooked up by the
+<computeroutput>./configure</computeroutput> script when the system is
+built.</para>
 
-<para>You can modify and add to the suppressions file at your
-leisure, or, better, write your own.  Multiple suppression files
-are allowed.  This is useful if part of your project contains
-errors you can't or don't want to fix, yet you don't want to
-continuously be reminded of them.</para>
+<para>You can modify and add to the suppressions file at your leisure,
+or, better, write your own.  Multiple suppression files are allowed.
+This is useful if part of your project contains errors you can't or
+don't want to fix, yet you don't want to continuously be reminded of
+them.</para>
 
-<formalpara><title>Note:</title>
-<para>By far the easiest way to add suppressions is to use the
-<computeroutput>--gen-suppressions=yes</computeroutput> flag
+<formalpara><title>Note:</title> <para>By far the easiest way to add
+suppressions is to use the <option>--gen-suppressions=yes</option> flag
 described in <xref linkend="manual-core.flags"/>.</para>
 </formalpara>
 
-<para>Each error to be suppressed is described very specifically,
-to minimise the possibility that a suppression-directive
-inadvertantly suppresses a bunch of similar errors which you did
-want to see.  The suppression mechanism is designed to allow
-precise yet flexible specification of errors to suppress.</para>
+<para>Each error to be suppressed is described very specifically, to
+minimise the possibility that a suppression-directive inadvertantly
+suppresses a bunch of similar errors which you did want to see.  The
+suppression mechanism is designed to allow precise yet flexible
+specification of errors to suppress.</para>
 
-<para>If you use the <computeroutput>-v</computeroutput> flag, at
-the end of execution, Valgrind prints out one line for each used
-suppression, giving its name and the number of times it got used.
-Here's the suppressions used by a run of <computeroutput>valgrind
---tool=memcheck ls -l</computeroutput>:</para>
+<para>If you use the <option>-v</option> flag, at the end of execution,
+Valgrind prints out one line for each used suppression, giving its name
+and the number of times it got used.  Here's the suppressions used by a
+run of <computeroutput>valgrind --tool=memcheck ls l</computeroutput>:</para>
 
 <programlisting><![CDATA[
 --27579-- supp: 1 socketcall.connect(serv_addr)/__libc_connect/__nscd_getgrgid_r
 --27579-- supp: 1 socketcall.connect(serv_addr)/__libc_connect/__nscd_getpwuid_r
 --27579-- supp: 6 strrchr/_dl_map_object_from_fd/_dl_map_object]]></programlisting>
 
-<para>Multiple suppressions files are allowed.  By default,
-Valgrind uses
-<computeroutput>$PREFIX/lib/valgrind/default.supp</computeroutput>.
-You can ask to add suppressions from another file, by specifying
-<computeroutput>--suppressions=/path/to/file.supp</computeroutput>.
+<para>Multiple suppressions files are allowed.  By default, Valgrind
+uses <filename>$PREFIX/lib/valgrind/default.supp</filename>.  You can
+ask to add suppressions from another file, by specifying
+<option>--suppressions=/path/to/file.supp</option>.
 </para>
 
-<para>If you want to understand more about suppressions, look at
-an existing suppressions file whilst reading the following
-documentation.  The file
-<computeroutput>glibc-2.2.supp</computeroutput>, in the source
+<para>If you want to understand more about suppressions, look at an
+existing suppressions file whilst reading the following documentation.
+The file <filename>glibc-2.2.supp</filename>, in the source
 distribution, provides some good examples.</para>
 
 <para>Each suppression has the following components:</para>
 
- <itemizedlist>
+<itemizedlist>
 
   <listitem>
-   <para>First line: its name.  This merely gives a handy name to
-   the suppression, by which it is referred to in the summary of
-   used suppressions printed out when a program finishes.  It's
-   not important what the name is; any identifying string will
-   do.</para>
+    <para>First line: its name.  This merely gives a handy name to the
+    suppression, by which it is referred to in the summary of used
+    suppressions printed out when a program finishes.  It's not
+    important what the name is; any identifying string will do.</para>
   </listitem>
 
   <listitem>
-   <para>Second line: name of the tool(s) that the suppression is
-   for (if more than one, comma-separated), and the name of the
-   suppression itself, separated by a colon (Nb: no spaces are
-   allowed), eg:</para>
-
+    <para>Second line: name of the tool(s) that the suppression is for
+    (if more than one, comma-separated), and the name of the suppression
+    itself, separated by a colon (Nb: no spaces are allowed), eg:</para>
 <programlisting><![CDATA[
 tool_name1,tool_name2:suppression_name]]></programlisting>
 
-   <para>Recall that Valgrind-2.0.X is a modular system, in which
-   different instrumentation tools can observe your program
-   whilst it is running.  Since different tools detect different
-   kinds of errors, it is necessary to say which tool(s) the
-   suppression is meaningful to.</para>
+    <para>Recall that valgrind-2.0.X is a modular system, in which
+    different instrumentation tools can observe your program whilst it
+    is running.  Since different tools detect different kinds of errors,
+    it is necessary to say which tool(s) the suppression is meaningful
+    to.</para>
 
-   <para>Tools will complain, at startup, if a tool does not
-   understand any suppression directed to it.  Tools ignore
-   suppressions which are not directed to them.  As a result, it
-   is quite practical to put suppressions for all tools into the
-   same suppression file.</para>
+    <para>Tools will complain, at startup, if a tool does not understand
+    any suppression directed to it.  Tools ignore suppressions which are
+    not directed to them.  As a result, it is quite practical to put
+    suppressions for all tools into the same suppression file.</para>
 
-   <para>Valgrind's core can detect certain PThreads API errors,
-   for which this line reads:</para>
+    <para>Valgrind's core can detect certain PThreads API errors, for
+    which this line reads:</para>
 
 <programlisting><![CDATA[
 core:PThread]]></programlisting>
   </listitem>
 
   <listitem>
-   <para>Next line: a small number of suppression types have
-   extra information after the second line (eg. the
-   <computeroutput>Param</computeroutput> suppression for
-   Memcheck)</para>
+    <para>Next line: a small number of suppression types have extra
+    information after the second line (eg. the <varname>Param</varname>
+    suppression for Memcheck)</para>
   </listitem>
 
   <listitem>
-   <para>Remaining lines: This is the calling context for the
-   error -- the chain of function calls that led to it.  There
-   can be up to four of these lines.</para>
+    <para>Remaining lines: This is the calling context for the error --
+    the chain of function calls that led to it.  There can be up to four
+    of these lines.</para>
 
-   <para>Locations may be either names of shared
-   objects/executables or wildcards matching function names.
-   They begin <computeroutput>obj:</computeroutput> and
-   <computeroutput>fun:</computeroutput> respectively.  Function
-   and object names to match against may use the wildcard
-   characters <computeroutput>*</computeroutput> and
-   <computeroutput>?</computeroutput>.</para>
+    <para>Locations may be either names of shared objects/executables or
+    wildcards matching function names.  They begin
+    <computeroutput>obj:</computeroutput> and
+    <computeroutput>fun:</computeroutput> respectively.  Function and
+    object names to match against may use the wildcard characters
+    <computeroutput>*</computeroutput> and
+    <computeroutput>?</computeroutput>.</para>
 
-   <formalpara><title>Important note:</title>
-    <para>C++ function names must be <command>mangled</command>.
-    If you are writing suppressions by hand, use the
-    <computeroutput>--demangle=no</computeroutput> option to get
-    the mangled names in your error messages.</para>
-   </formalpara>
+    <para><command>Important note: </command> C++ function names must be
+    <command>mangled</command>.  If you are writing suppressions by
+    hand, use the <option>--demangle=no</option> option to get the
+    mangled names in your error messages.</para>
   </listitem>
 
   <listitem>
-   <para>Finally, the entire suppression must be between curly
-   braces. Each brace must be the first character on its own
-   line.</para>
+    <para>Finally, the entire suppression must be between curly
+    braces. Each brace must be the first character on its own
+    line.</para>
   </listitem>
 
  </itemizedlist>
 
-<para>A suppression only suppresses an error when the error
-matches all the details in the suppression.  Here's an
-example:</para>
+<para>A suppression only suppresses an error when the error matches all
+the details in the suppression.  Here's an example:</para>
 
 <programlisting><![CDATA[
 {
@@ -524,14 +482,14 @@
 
 
 <para>What it means is: for Memcheck only, suppress a
-use-of-uninitialised-value error, when the data size is 4, when
-it occurs in the function
-<computeroutput>__gconv_transform_ascii_internal</computeroutput>,
-when that is called from any function of name matching
-<computeroutput>__mbr*toc</computeroutput>, when that is called
-from <computeroutput>mbtowc</computeroutput>.  It doesn't apply
-under any other circumstances.  The string by which this
-suppression is identified to the user is
+use-of-uninitialised-value error, when the data size is 4, when it
+occurs in the function
+<computeroutput>__gconv_transform_ascii_internal</computeroutput>, when
+that is called from any function of name matching
+<computeroutput>__mbr*toc</computeroutput>, when that is called from
+<computeroutput>mbtowc</computeroutput>.  It doesn't apply under any
+other circumstances.  The string by which this suppression is identified
+to the user is
 <computeroutput>__gconv_transform_ascii_internal/__mbrtowc/mbtowc</computeroutput>.</para>
 
 <para>(See <xref linkend="mc-manual.suppfiles"/> for more details
@@ -549,17 +507,17 @@
 }]]></programlisting>
 
 <para>Suppress any size 4 uninitialised-value error which occurs
-anywhere in <computeroutput>libX11.so.6.2</computeroutput>, when
-called from anywhere in the same library, when called from
-anywhere in <computeroutput>libXaw.so.7.0</computeroutput>.  The
-inexact specification of locations is regrettable, but is about
-all you can hope for, given that the X11 libraries shipped with
-Red Hat 7.2 have had their symbol tables removed.</para>
+anywhere in <filename>libX11.so.6.2</filename>, when called from
+anywhere in the same library, when called from anywhere in
+<filename>libXaw.so.7.0</filename>.  The inexact specification of
+locations is regrettable, but is about all you can hope for, given that
+the X11 libraries shipped with Red Hat 7.2 have had their symbol tables
+removed.</para>
 
-<para>Note: since the above two examples did not make it clear,
-you can freely mix the <computeroutput>obj:</computeroutput> and
-<computeroutput>fun:</computeroutput> styles of description
-within a single suppression record.</para>
+<para>Note: since the above two examples did not make it clear, you can
+freely mix the <computeroutput>obj:</computeroutput> and
+<computeroutput>fun:</computeroutput> styles of description within a
+single suppression record.</para>
 
 </sect1>
 
@@ -568,170 +526,225 @@
        xreflabel="Command-line flags for the Valgrind core">
 <title>Command-line flags for the Valgrind core</title>
 
-<para>As mentioned above, Valgrind's core accepts a common set of
-flags.  The tools also accept tool-specific flags, which are
-documented seperately for each tool.</para>
+<para>As mentioned above, Valgrind's core accepts a common set of flags.
+The tools also accept tool-specific flags, which are documented
+seperately for each tool.</para>
 
 <para>You invoke Valgrind like this:</para>
 
 <programlisting><![CDATA[
-valgrind [valgrind-options] your-prog [your-prog options]]]></programlisting>
+valgrind [valgrind-options] your-prog [your-prog-options]]]></programlisting>
 
-<para>Valgrind's default settings succeed in giving reasonable
-behaviour in most cases.  We group the available options by rough
+<para>Valgrind's default settings succeed in giving reasonable behaviour
+in most cases.  We group the available options by rough
 categories.</para>
 
 <sect2 id="manual-core.toolopts" xreflabel="Tool-selection option">
 <title>Tool-selection option</title>
 
 <para>The single most important option.</para>
-  <itemizedlist>
-   <listitem id="tool_name">
-    <para><computeroutput>--tool=&lt;name&gt;</computeroutput>
-    [default=memcheck]</para>
+
+<itemizedlist>
+  <listitem id="tool_name">
+    <para><option>--tool=&lt;name&gt;</option> [default=memcheck]</para>
     <para>Run the Valgrind tool called <emphasis>name</emphasis>,
     e.g. Memcheck, Addrcheck, Cachegrind, etc.</para>
-   </listitem>
-  </itemizedlist>
+  </listitem>
+</itemizedlist>
+
 </sect2>
 
+
+
 <sect2 id="manual-core.basicopts" xreflabel="Basic Options">
 <title>Basic Options</title>
 
 <para>These options work with all tools.</para>
 
- <itemizedlist>
-   <listitem>
-    <para><computeroutput>--help</computeroutput></para>
-    <para>Show help for all options, both for the core and for
-    the selected tool.</para>
-   </listitem>
+<variablelist id="basic.opts">
 
-   <listitem>
-    <para><computeroutput>--help-debug</computeroutput></para>
-    <para>Same as <computeroutput>--help</computeroutput>, but
-     also lists debugging options which usually are only of use
-     to Valgrind's developers.</para>
-   </listitem>
+  <varlistentry id="opt.help" xreflabel="--help">
+    <term><option>-h --help</option></term>
+    <listitem>
+      <para>Show help for all options, both for the core and for the
+      selected tool.</para>
+    </listitem>
+  </varlistentry>
 
-   <listitem>
-    <para><computeroutput>--version</computeroutput></para>
-    <para>Show the version number of the Valgrind core.  Tools
-    can have their own version numbers.  There is a scheme in
-    place to ensure that tools only execute when the core version
-    is one they are known to work with.  This was done to
-    minimise the chances of strange problems arising from
-    tool-vs-core version incompatibilities.</para>
-   </listitem>
+  <varlistentry id="opt.help-debug" xreflabel="--help-debug">
+    <term><option>--help-debug</option></term>
+    <listitem>
+      <para>Same as <option>--help</option>, but also lists debugging
+      options which usually are only of use to Valgrind's
+      developers.</para>
+    </listitem>
+  </varlistentry>
 
-   <listitem>
-    <para><computeroutput>-q --quiet</computeroutput></para>
-    <para>Run silently, and only print error messages.  Useful if
-    you are running regression tests or have some other automated
-    test machinery.</para>
-   </listitem>
+  <varlistentry id="opt.version" xreflabel="--version">
+    <term><option>--version</option></term>
+    <listitem>
+      <para>Show the version number of the Valgrind core. Tools can have
+      their own version numbers. There is a scheme in place to ensure
+      that tools only execute when the core version is one they are
+      known to work with. This was done to minimise the chances of
+      strange problems arising from tool-vs-core version
+      incompatibilities.</para>
+    </listitem>
+  </varlistentry>
 
-   <listitem id="verbosity">
-    <para><computeroutput>-v --verbose</computeroutput></para>
-    <para>Be more verbose.  Gives extra information on various
-    aspects of your program, such as: the shared objects loaded,
-    the suppressions used, the progress of the instrumentation
-    and execution engines, and warnings about unusual behaviour.
-    Repeating the flag increases the verbosity level.</para>
-   </listitem>
+  <varlistentry id="opt.quiet" xreflabel="--quiet">
+    <term><option>-q --quiet</option></term>
+    <listitem>
+      <para>Run silently, and only print error messages. Useful if you
+      are running regression tests or have some other automated test
+      machinery.</para>
+    </listitem>
+  </varlistentry>
 
-   <listitem>
-    <para><computeroutput>-d</computeroutput></para>
-    <para>Emit information for debugging Valgrind itself.  This
-    is usually only of interest to the Valgrind developers.
-    Repeating the flag produces more detailed output.  If you
-    want to send us a bug report, a log of the output
-    generated by <computeroutput>-v -v -d -d</computeroutput>
-    will make your report more useful.
-    </para>
-   </listitem>
+  <varlistentry id="opt.verbose" xreflabel="--verbose">
+    <term><option>-v --verbose</option></term>
+    <listitem>
+      <para>Be more verbose. Gives extra information on various aspects
+      of your program, such as: the shared objects loaded, the
+      suppressions used, the progress of the instrumentation and
+      execution engines, and warnings about unusual behaviour. Repeating
+      the flag increases the verbosity level.</para>
+    </listitem>
+  </varlistentry>
 
-   <listitem id="trace_children">
-    <para><computeroutput>--trace-children=no</computeroutput>
-    [default]</para>
-    <para><computeroutput>--trace-children=yes</computeroutput></para>
-    <para>When enabled, Valgrind will trace into child processes.
-    This is confusing and usually not what you want, so is
-    disabled by default.</para>
-   </listitem>
+  <varlistentry id="opt.d" xreflabel="-d">
+    <term><option>-d</option></term>
+    <listitem>
+      <para>Emit information for debugging Valgrind itself.  This is
+      usually only of interest to the Valgrind developers.  Repeating
+      the flag produces more detailed output.  If you want to send us a
+      bug report, a log of the output generated by 
+      <option>-v -v -d -d</option> will make your report more
+      useful.</para>
+    </listitem>
+  </varlistentry>
 
-   <listitem id="track_fds">
-    <para><computeroutput>--track-fds=no</computeroutput> [default]</para>
-    <para><computeroutput>--track-fds=yes</computeroutput></para>
-    <para>When enabled, Valgrind will print out a list of open
-    file descriptors on exit.  Along with each file descriptor,
-    Valgrind prints out a stack backtrace of where the file was
-    opened and any details relating to the file descriptor such
-    as the file name or socket details.</para>
-   </listitem>
+  <varlistentry id="opt.tool" xreflabel="--tool">
+    <term>
+      <option><![CDATA[--tool=<toolname> [default: memcheck] ]]></option>
+    </term>
+    <listitem>
+      <para>Run the Valgrind tool called <varname>toolname</varname>,
+      e.g. Memcheck, Addrcheck, Cachegrind, etc.</para>
+    </listitem>
+  </varlistentry>
 
-   <listitem id="time_stamp">
-    <para><computeroutput>--time-stamp=no</computeroutput> [default]</para>
-    <para><computeroutput>--time-stamp=yes</computeroutput></para>
-    <para>When enabled, Valgrind will precede each message with 
-    an indication of the elapsed wallclock time since startup,
-    expressed as days, hours, minutes, seconds and milliseconds.
-    </para>
-   </listitem>
+  <varlistentry id="opt.trace-children" xreflabel="--trace-children">
+    <term>
+      <option><![CDATA[--trace-children=<yes|no> [default: no] ]]></option>
+    </term>
+    <listitem>
+      <para>When enabled, Valgrind will trace into child processes.
+      This can be confusing and isn't usually what you want, so it is
+      disabled by default.</para>
+    </listitem>
+  </varlistentry>
 
-   <listitem id="log2fd">
-    <para><computeroutput>--log-fd=&lt;number&gt;</computeroutput>
-    [default: 2, stderr]</para>
-    <para>Specifies that Valgrind should send all of its messages
-    to the specified file descriptor.  The default, 2, is the
-    standard error channel (stderr).  Note that this may
-    interfere with the client's own use of stderr.</para>
-   </listitem>
+  <varlistentry id="opt.track-fds" xreflabel="--track-fds">
+    <term>
+      <option><![CDATA[--track-fds=<yes|no> [default: no] ]]></option>
+    </term>
+    <listitem>
+      <para>When enabled, Valgrind will print out a list of open file
+      descriptors on exit.  Along with each file descriptor is printed a
+      stack backtrace of where the file was opened and any details
+      relating to the file descriptor such as the file name or socket
+      details.</para>
+    </listitem>
+  </varlistentry>
 
-   <listitem id="log2file_pid">
-    <para><computeroutput>--log-file=&lt;filename&gt;</computeroutput></para>
-    <para>Specifies that Valgrind should send all of its messages
-    to the specified file.  In fact, the file name used is
-    created by concatenating the text
-    <computeroutput>filename</computeroutput>, "." and the
-    process ID, so as to create a file per process.  The
-    specified file name may not be the empty string.</para>
-   </listitem>
+  <varlistentry id="opt.time-stamp" xreflabel="--time-stamp">
+    <term>
+      <option><![CDATA[--time-stamp=<yes|no> [default: no] ]]></option>
+    </term>
+    <listitem>
+      <para>When enabled, each message is preceded with an indication of
+      the elapsed wallclock time since startup, expressed as days,
+      hours, minutes, seconds and milliseconds.</para>
+    </listitem>
+  </varlistentry>
 
-   <listitem id="log2file">
-    <para><computeroutput>--log-file-exactly=&lt;filename&gt;</computeroutput></para>
-    <para>Just like <computeroutput>--log-file</computeroutput>, but
-    the "." suffix is not added.  If you trace multiple processes
-    with Valgrind when using this option the log file may get all messed
-    up.
-    </para>
-   </listitem>
+  <varlistentry id="opt.log-fd" xreflabel="--log-fd">
+    <term>
+      <option><![CDATA[--log-fd=<number> [default: 2, stderr] ]]></option>
+    </term>
+    <listitem>
+      <para>Specifies that Valgrind should send all of its messages to
+      the specified file descriptor.  The default, 2, is the standard
+      error channel (stderr).  Note that this may interfere with the
+      client's own use of stderr, as Valgrind's output will be
+      interleaved with any output that the client sends to
+      stderr.</para>
+    </listitem>
+  </varlistentry>
 
-   <listitem id="log2file_qualifier">
-    <para><computeroutput>--log-file-qualifer=&lt;VAR&gt;</computeroutput></para>
-    <para>When used in conjunction with
-    <computeroutput>--log-file=</computeroutput>, causes the log file
-    name to be qualified using the contents of environment variable
-    <computeroutput>VAR</computeroutput>.  This is useful when running
-    MPI programs.
-    For further details, see <xref linkend="manual-core.comment"/>.
-    </para>
-   </listitem>
+  <varlistentry id="opt.log-file" xreflabel="--log-file">
+    <term>
+      <option><![CDATA[--log-file=<filename> ]]></option>
+    </term>
+    <listitem>
+      <para>Specifies that Valgrind should send all of its messages to
+      the specified file. In fact, the file name used is created by
+      concatenating the text <filename>filename</filename>, "." and the
+      process ID, (ie. <![CDATA[<filename>.<pid>]]>), so as to create a
+      file per process.  The specified file name may not be the empty
+      string.</para>
+    </listitem>
+  </varlistentry>
 
-   <listitem id="log2socket">
-    <para><computeroutput>--log-socket=&lt;ip-address:port-number&gt;</computeroutput></para>
-    <para>Specifies that Valgrind should send all of its messages
-    to the specified port at the specified IP address.  The port
-    may be omitted, in which case port 1500 is used.  If a
-    connection cannot be made to the specified socket, Valgrind
-    falls back to writing output to the standard error (stderr).
-    This option is intended to be used in conjunction with the
-    <computeroutput>valgrind-listener</computeroutput> program.
-    For further details, see <xref linkend="manual-core.comment"/>.</para>
-   </listitem>
+  <varlistentry id="opt.log-file-exactly" xreflabel="--log-file-exactly">
+    <term>
+      <option><![CDATA[--log-file-exactly=<filename> ]]></option>
+    </term>
+    <listitem>
+      <para>Just like <option>--log-file</option>, but the suffix
+      <computeroutput>".pid"</computeroutput> is not added.  If you
+      trace multiple processes with Valgrind when using this option the
+      log file may get all messed up.</para>
+    </listitem>
+  </varlistentry>
 
-  </itemizedlist>
- </sect2>
+  <varlistentry id="opt.log-file-qualifier" xreflabel="--log-file-qualifier">
+    <term>
+      <option><![CDATA[--log-file-qualifier=<VAR> ]]></option>
+    </term>
+    <listitem>
+      <para>When used in conjunction with <option>--log-file</option>,
+      causes the log file name to be qualified using the contents of the
+      environment variable <computeroutput>$VAR</computeroutput>.  This
+      is useful when running MPI programs.  For further details, see
+      <link linkend="manual-core.comment">Section 2.3 "The Commentary"</link>
+      in the manual.
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry id="opt.log-socket" xreflabel="--log-socket">
+    <term>
+      <option><![CDATA[--log-socket=<ip-address:port-number> ]]></option>
+    </term>
+    <listitem>
+      <para>Specifies that Valgrind should send all of its messages to
+      the specified port at the specified IP address.  The port may be
+      omitted, in which case port 1500 is used.  If a connection cannot
+      be made to the specified socket, Valgrind falls back to writing
+      output to the standard error (stderr).  This option is intended to
+      be used in conjunction with the
+      <computeroutput>valgrind-listener</computeroutput> program.  For
+      further details, see 
+      <link linkend="manual-core.comment">Section 2.3 "The Commentary"</link>
+      in the manual.</para>
+    </listitem>
+  </varlistentry>
+
+</variablelist>
+
+</sect2>
 
 
 <sect2 id="manual-core.erropts" xreflabel="Error-related Options">
@@ -740,235 +753,268 @@
 <para>These options are used by all tools that can report
 errors, e.g. Memcheck, but not Cachegrind.</para>
 
-  <itemizedlist>
+<variablelist id="error-related.opts">
 
-   <listitem id="xml_output">
-    <para><computeroutput>--xml=no</computeroutput> [default]</para>
-    <para><computeroutput>--xml=yes</computeroutput></para>
-    <para>When enabled, output will be in XML format.  This is aimed at
-    making life easier for tools that consume Valgrind's output as input,
-    such as GUI front ends.  Currently this option only works with Memcheck
-    and Nulgrind.
-    </para>
-   </listitem>
-    
-   <listitem id="xml_user_comment">
-    <para><computeroutput>--xml-user-comment=&lt;string&gt;</computeroutput> [default=""]</para>
-    <para>Embeds an extra user comment string in the XML output.  Only works
-    with <computeroutput>--xml=yes</computeroutput> is specified;  ignored
-    otherwise.</para>
-   </listitem>
-    
-   <listitem id="auto_demangle">
-    <para><computeroutput>--demangle=no</computeroutput></para>
-    <para><computeroutput>--demangle=yes</computeroutput> [default]</para>
-    <para>Disable/enable automatic demangling (decoding) of C++
-    names.  Enabled by default.  When enabled, Valgrind will
-    attempt to translate encoded C++ names back to
-    something approaching the original.  The demangler handles
-    symbols mangled by g++ versions 2.X and 3.X.</para>
+  <varlistentry id="opt.xml" xreflabel="--xml">
+    <term>
+      <option><![CDATA[--xml=<yes|no> [default: no] ]]></option>
+    </term>
+    <listitem>
+      <para>When enabled, output will be in XML format.  This is aimed
+      at making life easier for tools that consume Valgrind's output as
+      input, such as GUI front ends.  Currently this option only works
+      with Memcheck and Nulgrind.</para>
+    </listitem>
+  </varlistentry>
 
-    <para>An important fact about demangling is that function
-    names mentioned in suppressions files should be in their
-    mangled form.  Valgrind does not demangle function names when
-    searching for applicable suppressions, because to do
-    otherwise would make suppressions file contents dependent on
-    the state of Valgrind's demangling machinery, and would also
-    be slow and pointless.</para>
-   </listitem>
+  <varlistentry id="opt.xml-user-comment" xreflabel="--xml-user-comment">
+    <term>
+      <option><![CDATA[--xml-user-comment=<string> ]]></option>
+    </term>
+    <listitem>
+      <para>Embeds an extra user comment string at the start of the XML
+      output.  Only works when <option>--xml=yes</option> is specified;
+      ignored otherwise.</para>
+    </listitem>
+  </varlistentry>
 
-   <listitem id="num_callers">
-    <para><computeroutput>--num-callers=&lt;number&gt;</computeroutput> [default=12]</para>
-    <para>By default, Valgrind shows twelve levels of function call
-    names to help you identify program locations.  You can change
-    that number with this option.  This can help in determining
-    the program's location in deeply-nested call chains.  Note
-    that errors are commoned up using only the top three function
-    locations (the place in the current function, and that of its
-    two immediate callers).  So this doesn't affect the total
-    number of errors reported.</para>
+  <varlistentry id="opt.demangle" xreflabel="--demangle">
+    <term>
+      <option><![CDATA[--demangle=<yes|no> [default: yes] ]]></option>
+    </term>
+    <listitem>
+      <para>Enable/disable automatic demangling (decoding) of C++ names.
+      Enabled by default.  When enabled, Valgrind will attempt to
+      translate encoded C++ names back to something approaching the
+      original.  The demangler handles symbols mangled by g++ versions
+      2.X, 3.X and 4.X.</para>
 
-    <para>The maximum value for this is 50.  Note that higher
-    settings will make Valgrind run a bit more slowly and take a
-    bit more memory, but can be useful when working with programs
-    with deeply-nested call chains.</para>
-   </listitem>
+      <para>An important fact about demangling is that function names
+      mentioned in suppressions files should be in their mangled form.
+      Valgrind does not demangle function names when searching for
+      applicable suppressions, because to do otherwise would make
+      suppressions file contents dependent on the state of Valgrind's
+      demangling machinery, and would also be slow and pointless.</para>
+    </listitem>
+  </varlistentry>
 
-   <listitem id="error_limit">
-    <para><computeroutput>--error-limit=yes</computeroutput>
-    [default]</para>
-    <para><computeroutput>--error-limit=no</computeroutput></para>
-    <para>When enabled, Valgrind stops reporting errors after
-    100000 in total, or 1000 different ones, have been seen.  This
-    is to stop the error tracking machinery from becoming a huge
-    performance overhead in programs with many errors.</para>
-   </listitem>
+  <varlistentry id="opt.num-callers" xreflabel="--num-callers">
+    <term>
+      <option><![CDATA[--num-callers=<number> [default: 12] ]]></option>
+    </term>
+    <listitem>
+      <para>By default, Valgrind shows twelve levels of function call
+      names to help you identify program locations.  You can change that
+      number with this option.  This can help in determining the
+      program's location in deeply-nested call chains.  Note that errors
+      are commoned up using only the top four function locations (the
+      place in the current function, and that of its three immediate
+      callers).  So this doesn't affect the total number of errors
+      reported.</para>
 
-   <listitem id="stack_traces">
-    <para><computeroutput>--show-below-main=yes</computeroutput></para>
-    <para><computeroutput>--show-below-main=no</computeroutput>
-    [default]</para>
-    <para>By default, stack traces for errors do not show any
-    functions that appear beneath
-    <computeroutput>main()</computeroutput> (or similar functions
-    such as glibc's <computeroutput>__libc_start_main()</computeroutput>, if
-    <computeroutput>main()</computeroutput> is not present in the stack
-    trace); most of the time it's uninteresting C library stuff.  If this
-    option is enabled, these entries below
-    <computeroutput>main()</computeroutput> will be shown.</para>
-   </listitem>
+      <para>The maximum value for this is 50. Note that higher settings
+      will make Valgrind run a bit more slowly and take a bit more
+      memory, but can be useful when working with programs with
+      deeply-nested call chains.</para>
+    </listitem>
+  </varlistentry>
 
-   <listitem id="supps_files">
-    <para><computeroutput>--suppressions=&lt;filename&gt;</computeroutput>
-    [default: $PREFIX/lib/valgrind/default.supp]</para>
-    <para>Specifies an extra file from which to read descriptions
-    of errors to suppress.  You may use as many extra
-    suppressions files as you like.</para>
-   </listitem>
+  <varlistentry id="opt.error-limit" xreflabel="--error-limit">
+    <term>
+      <option><![CDATA[--error-limit=<yes|no> [default: yes] ]]></option>
+    </term>
+    <listitem>
+      <para>When enabled, Valgrind stops reporting errors after 100,000
+      in total, or 1,000 different ones, have been seen.  This is to
+      stop the error tracking machinery from becoming a huge performance
+      overhead in programs with many errors.</para>
+    </listitem>
+  </varlistentry>
 
-   <listitem id="gen_supps">
-    <para><computeroutput>--gen-suppressions=no</computeroutput>
-    [default]</para>
-    <para><computeroutput>--gen-suppressions=yes</computeroutput></para>
-    <para><computeroutput>--gen-suppressions=all</computeroutput></para>
+  <varlistentry id="opt.stack-traces" xreflabel="--show-below-main">
+    <term>
+      <option><![CDATA[--show-below-main=<yes|no> [default: no] ]]></option>
+    </term>
+    <listitem>
+      <para>By default, stack traces for errors do not show any
+      functions that appear beneath <function>main()</function> 
+      (or similar functions such as glibc's
+      <function>__libc_start_main()</function>, if
+      <function>main()</function> is not present in the stack trace);
+      most of the time it's uninteresting C library stuff.  If this
+      option is enabled, those entries below <function>main()</function>
+      will be shown.</para>
+    </listitem>
+  </varlistentry>
 
-    <para>When set to <computeroutput>yes</computeroutput>, Valgrind
-    will pause after every error shown, and print the line:
-    <computeroutput>---- Print suppression ?  --- [Return/N/n/Y/y/C/c]
-    ----</computeroutput></para>
+  <varlistentry id="opt.suppressions" xreflabel="--suppressions">
+    <term>
+      <option><![CDATA[--suppressions=<filename> [default: $PREFIX/lib/valgrind/default.supp] ]]></option>
+    </term>
+    <listitem>
+      <para>Specifies an extra file from which to read descriptions of
+      errors to suppress.  You may use as many extra suppressions files
+      as you like.</para>
+    </listitem>
+  </varlistentry>
 
-    <para>The prompt's behaviour is the same as for the 
-    <computeroutput>--db-attach</computeroutput> option.</para>
+  <varlistentry id="opt.gen-suppressions" xreflabel="--gen-supressions">
+    <term>
+      <option><![CDATA[--gen-suppressions=<yes|no|all> [default: no] ]]></option>
+    </term>
+    <listitem>
+      <para>When set to <varname>yes</varname>, Valgrind will pause
+      after every error shown and print the line:
+      <literallayout>    ---- Print suppression ? --- [Return/N/n/Y/y/C/c] ----</literallayout>
 
-    <para>If you choose to, Valgrind will print out a suppression
-    for this error.  You can then cut and paste it into a
-    suppression file if you don't want to hear about the error in
-    the future.</para>
+      The prompt's behaviour is the same as for the
+      <option>--db-attach</option> option (see below).</para>
 
-    <para>When set to <computeroutput>all</computeroutput>, Valgrind
-    will print a suppression for every reported error, without
-    querying the user.</para>
+      <para>If you choose to, Valgrind will print out a suppression for
+      this error.  You can then cut and paste it into a suppression file
+      if you don't want to hear about the error in the future.</para>
 
-    <para>This option is particularly useful with C++ programs,
-    as it prints out the suppressions with mangled names, as
-    required.</para>
+      <para>When set to <varname>all</varname>, Valgrind will print a
+      suppression for every reported error, without querying the
+      user.</para>
 
-    <para>Note that the suppressions printed are as specific as
-    possible.  You may want to common up similar ones, eg. by
-    adding wildcards to function names.  Also, sometimes two
-    different errors are suppressed by the same suppression, in
-    which case Valgrind will output the suppression more than
-    once, but you only need to have one copy in your suppression
-    file (but having more than one won't cause problems).  Also,
-    the suppression name is given as <computeroutput>&lt;insert a
-    suppression name here&gt;</computeroutput>; the name doesn't
-    really matter, it's only used with the
-    <computeroutput>-v</computeroutput> option which prints out
-    all used suppression records.</para>
-   </listitem>
+      <para>This option is particularly useful with C++ programs, as it
+      prints out the suppressions with mangled names, as
+      required.</para>
 
-   <listitem id="attach_debugger">
-    <para><computeroutput>--db-attach=no</computeroutput> [default]</para>
-    <para><computeroutput>--db-attach=yes</computeroutput></para>
-    <para>When enabled, Valgrind will pause after every error
-    shown, and print the line: <computeroutput>---- Attach to
-    debugger ? --- [Return/N/n/Y/y/C/c] ----</computeroutput></para>
+      <para>Note that the suppressions printed are as specific as
+      possible.  You may want to common up similar ones, eg. by adding
+      wildcards to function names.  Also, sometimes two different errors
+      are suppressed by the same suppression, in which case Valgrind
+      will output the suppression more than once, but you only need to
+      have one copy in your suppression file (but having more than one
+      won't cause problems).  Also, the suppression name is given as
+      <computeroutput>&lt;insert a suppression name
+      here&gt;</computeroutput>; the name doesn't really matter, it's
+      only used with the <option>-v</option> option which prints out all
+      used suppression records.</para>
+    </listitem>
+  </varlistentry>
 
-    <para>Pressing <literal>Ret</literal>, or 
-    <literal>N Ret</literal> or <literal>n Ret</literal>, causes
-    Valgrind not to start a debugger for this error.</para>
+  <varlistentry id="opt.db-attach" xreflabel="--db-attach">
+    <term>
+      <option><![CDATA[--db-attach=<yes|no> [default: no] ]]></option>
+    </term>
+    <listitem>
+      <para>When enabled, Valgrind will pause after every error shown
+      and print the line:
+      <literallayout>    ---- Attach to debugger ? --- [Return/N/n/Y/y/C/c] ----</literallayout>
 
-    <para><literal>Y Ret</literal> or <literal>y Ret</literal>
-    causes Valgrind to start a debugger, for the program at this
-    point.  When you have finished with the debugger, quit from
-    it, and the program will continue.  Trying to continue from
-    inside the debugger doesn't work.</para>
+      Pressing <varname>Ret</varname>, or <varname>N Ret</varname> or
+      <varname>n Ret</varname>, causes Valgrind not to start a debugger
+      for this error.</para>
 
-    <para><literal>C Ret</literal> or <literal>c Ret</literal>
-    causes Valgrind not to start a debugger, and not to ask
-    again.</para>
+      <para>Pressing <varname>Y Ret</varname> or
+      <varname>y Ret</varname> causes Valgrind to start a debugger for
+      the program at this point. When you have finished with the
+      debugger, quit from it, and the program will continue. Trying to
+      continue from inside the debugger doesn't work.</para>
 
-    <formalpara>
-     <title>Note:</title>
-     <para><computeroutput>--db-attach=yes</computeroutput>
-     conflicts with
-     <computeroutput>--trace-children=yes</computeroutput>.  You
-     can't use them together.  Valgrind refuses to start up in
-     this situation.</para>
-    </formalpara>
-    <para>1 May 2002: this is a historical relic which could be
-    easily fixed if it gets in your way.  Mail us and complain if
-    this is a problem for you.</para> <para>Nov 2002: if you're
-    sending output to a logfile or to a network socket, I guess
-    this option doesn't make any sense.  Caveat emptor.</para>
-   </listitem>
+      <para><varname>C Ret</varname> or <varname>c Ret</varname> causes
+      Valgrind not to start a debugger, and not to ask again.</para>
 
-   <listitem id="which_debugger">
-    <para><computeroutput>--db-command=&lt;command&gt;</computeroutput>
-    [default: gdb -nw %f %p]</para>
-    <para>This specifies how Valgrind will invoke the debugger.
-    By default it will use whatever GDB is detected at build
-    time, which is usually
-    <computeroutput>/usr/bin/gdb</computeroutput>.  Using this
-    command, you can specify some alternative command to invoke
-    the debugger you want to use.</para>
+      <para><command>Note:</command> <option>--db-attach=yes</option>
+      conflicts with <option>--trace-children=yes</option>.  You can't
+      use them together.  Valgrind refuses to start up in this
+      situation.</para>
 
-    <para>The command string given can include one or instances
-    of the <literal>%p</literal> and <literal>%f</literal>
-    expansions. Each instance of <literal>%p</literal> expands to
-    the PID of the process to be debugged and each instance of
-    <literal>%f</literal> expands to the path to the executable
-    for the process to be debugged.</para>
-   </listitem>
+      <para>May 2002: this is a historical relic which could be easily
+      fixed if it gets in your way.  Mail us and complain if this is a
+      problem for you.</para>
+      <para>Nov 2002: if you're sending output to a logfile or to a
+      network socket, I guess this option doesn't make any sense.
+      Caveat emptor.</para>
+    </listitem>
+  </varlistentry>
 
-   <listitem id="input_fd">
-    <para><computeroutput>--input-fd=&lt;number&gt;</computeroutput>
-    [default=0, stdin]</para>
-    <para>When using
-    <computeroutput>--db-attach=yes</computeroutput> and
-    <computeroutput>--gen-suppressions=yes</computeroutput>,
-    Valgrind will stop so as to read keyboard input from you,
-    when each error occurs.  By default it reads from the
-    standard input (stdin), which is problematic for programs
-    which close stdin.  This option allows you to specify an
-    alternative file descriptor from which to read input.</para>
-   </listitem>
+  <varlistentry id="opt.db-command" xreflabel="--db-command">
+    <term>
+      <option><![CDATA[--db-command=<command> [default: gdb -nw %f %p] ]]></option>
+    </term>
+    <listitem>
+      <para>Specify the debugger to use with the
+      <option>--db-attach</option> command. The default debugger is
+      gdb. This option is a template that is expanded by Valgrind at
+      runtime.  <literal>%f</literal> is replaced with the executable's
+      file name and <literal>%p</literal> is replaced by the process ID
+      of the executable.</para>
 
-   <listitem id="max_frames">
-    <para><computeroutput>--max-stackframe=&lt;number&gt;</computeroutput>
-                          [default=2000000]
-    </para>
-    <para>You may need to use this option if your program has large
-    stack-allocated arrays.  Valgrind keeps track of your program's
-    stack pointer.  If it changes by more than the threshold amount,
-    Valgrind assumes your program is switching to a different stack,
-    and Memcheck behaves differently than it would for a stack pointer
-    change smaller than the threshold.  Usually this heuristic works
-    well.  However, if your program allocates large structures on the
-    stack, this heuristic will be fooled, and Memcheck will
-    subsequently report large numbers of invalid stack accesses.  This
-    option allows you to change the threshold to a different value.
-    </para>
-    <para>
-    You should only consider use of this flag if Valgrind's debug output
-    directs you to do so.  In that case it will tell you the new
-    threshold you should specify.
-    </para>
-    <para>
-    In general, allocating large structures on the stack is a bad
-    idea, because (1) you can easily run out of stack space,
-    especially on systems with limited memory or which expect to
-    support large numbers of threads each with a small stack, and (2)
-    because the error checking performed by Memcheck is more effective
-    for heap-allocated data than for stack-allocated data.  If you
-    have to use this flag, you may wish to consider rewriting your
-    code to allocate on the heap rather than on the stack.
-   </para>
-   </listitem>
+      <para>This specifies how Valgrind will invoke the debugger.  By
+      default it will use whatever GDB is detected at build time, which
+      is usually <computeroutput>/usr/bin/gdb</computeroutput>.  Using
+      this command, you can specify some alternative command to invoke
+      the debugger you want to use.</para>
 
-  </itemizedlist>
+      <para>The command string given can include one or instances of the
+      <literal>%p</literal> and <literal>%f</literal> expansions. Each
+      instance of <literal>%p</literal> expands to the PID of the
+      process to be debugged and each instance of <literal>%f</literal>
+      expands to the path to the executable for the process to be
+      debugged.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry id="opt.input-fd" xreflabel="--input-fd">
+    <term>
+      <option><![CDATA[--input-fd=<number> [default: 0, stdin] ]]></option>
+    </term>
+    <listitem>
+      <para>When using <option>--db-attach=yes</option> and
+      <option>--gen-suppressions=yes</option>, Valgrind will stop so as
+      to read keyboard input from you, when each error occurs.  By
+      default it reads from the standard input (stdin), which is
+      problematic for programs which close stdin.  This option allows
+      you to specify an alternative file descriptor from which to read
+      input.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry id="opt.max-stackframe" xreflabel="--max-stackframe">
+    <term>
+      <option><![CDATA[--max-stackframe=<number> [default: 2000000] ]]></option>
+    </term>
+    <listitem>
+      <para>The maximum size of a stack frame - if the stack pointer moves by
+      more than this amount then Valgrind will assume that
+      the program is switching to a different stack.</para>
+
+      <para>You may need to use this option if your program has large
+      stack-allocated arrays.  Valgrind keeps track of your program's
+      stack pointer.  If it changes by more than the threshold amount,
+      Valgrind assumes your program is switching to a different stack,
+      and Memcheck behaves differently than it would for a stack pointer
+      change smaller than the threshold.  Usually this heuristic works
+      well.  However, if your program allocates large structures on the
+      stack, this heuristic will be fooled, and Memcheck will
+      subsequently report large numbers of invalid stack accesses.  This
+      option allows you to change the threshold to a different
+      value.</para>
+
+      <para>You should only consider use of this flag if Valgrind's
+      debug output directs you to do so.  In that case it will tell you
+      the new threshold you should specify.</para>
+
+      <para>In general, allocating large structures on the stack is a
+      bad idea, because (1) you can easily run out of stack space,
+      especially on systems with limited memory or which expect to
+      support large numbers of threads each with a small stack, and (2)
+      because the error checking performed by Memcheck is more effective
+      for heap-allocated data than for stack-allocated data.  If you
+      have to use this flag, you may wish to consider rewriting your
+      code to allocate on the heap rather than on the stack.</para>
+    </listitem>
+  </varlistentry>
+
+</variablelist>
+
 </sect2>
 
+
 <sect2 id="manual-core.mallocopts" xreflabel="malloc()-related Options">
 <title><computeroutput>malloc()</computeroutput>-related Options</title>
 
@@ -976,138 +1022,146 @@
 <computeroutput>malloc()</computeroutput> (e.g. Memcheck and
 Addrcheck), the following options apply.</para>
 
-  <itemizedlist>
+<variablelist id="malloc-related.opts">
 
-   <listitem id="alignment">
-    <para><computeroutput>--alignment=&lt;number&gt;</computeroutput>
-    [default: 8]</para>
-    <para>By default Valgrind's
-    <computeroutput>malloc</computeroutput>,
-    <computeroutput>realloc</computeroutput>, etc, return 8-byte
-    aligned addresses.  This is standard for
-    most processors.  Some programs might however assume that
-    <computeroutput>malloc</computeroutput> et al return 16- or
-    more aligned memory.  The supplied value must be between 4
-    and 4096 inclusive, and must be a power of two.</para>
-   </listitem>
-
-  </itemizedlist>
-
- </sect2>
-
-
- <sect2 id="manual-core.rareopts" xreflabel="Uncommon Options">
-  <title>Uncommon Options</title>
-
-  <para>These options apply to all tools, as they affect certain
-  obscure workings of the Valgrind core.  Most people won't need
-  to use these.</para>
-
-  <itemizedlist>
-
-   <listitem id="free_glibc">
-    <para><computeroutput>--run-libc-freeres=yes</computeroutput>
-     [default]</para>
-    <para><computeroutput>--run-libc-freeres=no</computeroutput></para>
-    <para>The GNU C library
-    (<computeroutput>libc.so</computeroutput>), which is used by
-    all programs, may allocate memory for its own uses.  Usually
-    it doesn't bother to free that memory when the program ends -
-    there would be no point, since the Linux kernel reclaims all
-    process resources when a process exits anyway, so it would
-    just slow things down.</para>
-
-    <para>The glibc authors realised that this behaviour causes
-    leak checkers, such as Valgrind, to falsely report leaks in
-    glibc, when a leak check is done at exit.  In order to avoid
-    this, they provided a routine called
-    <computeroutput>__libc_freeres</computeroutput> specifically
-    to make glibc release all memory it has allocated.  Memcheck
-    and Addrcheck therefore try and run
-    <computeroutput>__libc_freeres</computeroutput> at
-    exit.</para>
-
-    <para>Unfortunately, in some versions of glibc,
-    <computeroutput>__libc_freeres</computeroutput> is
-    sufficiently buggy to cause segmentation faults.  This is
-    particularly noticeable on Red Hat 7.1.  So this flag is
-    provided in order to inhibit the run of
-    <computeroutput>__libc_freeres</computeroutput>.  If your
-    program seems to run fine on Valgrind, but segfaults at exit,
-    you may find that
-    <computeroutput>--run-libc-freeres=no</computeroutput> fixes
-    that, although at the cost of possibly falsely reporting
-    space leaks in
-    <computeroutput>libc.so</computeroutput>.</para>
-   </listitem>
-
-   <listitem id="simulation_hints">
-    <para><computeroutput>--sim-hints=hint1,hint2,...</computeroutput></para>
-    <para>Pass miscellaneous hints to Valgrind which slightly
-    modify the simulated behaviour in nonstandard or dangerous
-    ways, possibly to help the simulation of strange features.
-    By default no hints are enabled.  Use with caution!
-    Currently known hints are:</para>
-    <itemizedlist>
-     <listitem><para><computeroutput>lax-ioctls</computeroutput></para>
-      <para>Be very lax about ioctl handling; the only assumption
-      is that the size is correct. Doesn't require the full
-      buffer to be initialized when writing.  Without this, using
-      some device drivers with a large number of strange ioctl
-      commands becomes very tiresome.</para>
-     </listitem>
-
-     <listitem><para><computeroutput>enable-inner</computeroutput></para> 
-      <para>Enable some special magic needed when the program being
-      run is itself Valgrind.
-      </para>
-     </listitem>
-
-    </itemizedlist>
-   </listitem>
-
-   <listitem id="kernel_variant">
-    <para><computeroutput>--kernel-variant=variant1,variant2,...</computeroutput>
-    </para>
-    <para>Handle system calls and ioctls arising from minor variants
-    of the default kernel for this platform.  This is useful for
-    running on hacked kernels or with kernel modules which support
-    nonstandard ioctls, for example.  Use with caution.  If you don't
-    understand what this option does then you almost certainly don't
-    need it.
-    Currently known variants are:</para>
-    <itemizedlist>
-     <listitem><para><computeroutput>bproc</computeroutput></para>
-      <para>Support the sys_broc system call on x86.  This is for
-      running on BProc, which is a minor variant of standard Linux
-      which is sometimes used for building clusters.
-      </para>
-     </listitem>
-    </itemizedlist>
-   </listitem>
-
-   <listitem id="show_emwarns">
-    <para><computeroutput>--show-emwarns=no</computeroutput> [default]</para>
-    <para><computeroutput>--show-emwarns=yes</computeroutput></para>
-    <para>When enabled, Valgrind will emit warnings about its CPU emulation
-    in certain cases.  These are usually not interesting.</para>
-   </listitem>
-
-   <listitem id="smc_support">
-    <para><computeroutput>--smc-check=none</computeroutput></para>
-    <para><computeroutput>--smc-check=stack</computeroutput> [default]</para>
-    <para><computeroutput>--smc-check=all</computeroutput></para>
-    <para>This option controls Valgrind's detection of self-modifying code.
-    Valgrind can do no detection, detect self-modifying code on the stack,
-    or detect self-modifying code anywhere.  Note that the default option
-    will catch the vast majority of cases, as far as we know.  Running with
-    <computeroutput>all</computeroutput> will slow Valgrind down greatly
-    (but running with <computeroutput>none</computeroutput> will rarely
-    speed things up, since very little code gets put on the stack for most
-    programs). </para>
+  <varlistentry id="opt.alignment" xreflabel="--alignment">
+    <term>
+      <option><![CDATA[--alignment=<number> [default: 8] ]]></option>
+    </term>
+    <listitem>
+      <para>By default Valgrind's <function>malloc()</function>,
+      <function>realloc()</function>, etc, return 8-byte aligned
+      addresses.  This is standard for most processors.  However, some
+      programs might assume that <function>malloc()</function> et al
+      return 16-byte or more aligned memory.  The supplied value must be
+      between 8 and 4096 inclusive, and must be a power of two.</para>
     </listitem>
+  </varlistentry>
 
-  </itemizedlist>
+</variablelist>
+
+</sect2>
+
+
+<sect2 id="manual-core.rareopts" xreflabel="Uncommon Options">
+<title>Uncommon Options</title>
+
+<para>These options apply to all tools, as they affect certain obscure
+workings of the Valgrind core.  Most people won't need to use
+these.</para>
+
+<variablelist id="uncommon.opts">
+
+  <varlistentry id="opt.run-libc-freeres" xreflabel="--run-libc-freeres">
+    <term>
+      <option><![CDATA[--run-libc-freeres=<yes|no> [default: yes] ]]></option>
+    </term>
+    <listitem>
+      <para>The GNU C library (<function>libc.so</function>), which is
+      used by all programs, may allocate memory for its own uses.
+      Usually it doesn't bother to free that memory when the program
+      ends - there would be no point, since the Linux kernel reclaims
+      all process resources when a process exits anyway, so it would
+      just slow things down.</para>
+
+      <para>The glibc authors realised that this behaviour causes leak
+      checkers, such as Valgrind, to falsely report leaks in glibc, when
+      a leak check is done at exit.  In order to avoid this, they
+      provided a routine called <function>__libc_freeres</function>
+      specifically to make glibc release all memory it has allocated.
+      Memcheck and Addrcheck therefore try and run
+      <function>__libc_freeres</function> at exit.</para>
+
+      <para>Unfortunately, in some versions of glibc,
+      <function>__libc_freeres</function> is sufficiently buggy to cause
+      segmentation faults.  This is particularly noticeable on Red Hat
+      7.1.  So this flag is provided in order to inhibit the run of
+      <function>__libc_freeres</function>.  If your program seems to run
+      fine on Valgrind, but segfaults at exit, you may find that
+      <option>--run-libc-freeres=no</option> fixes that, although at the
+      cost of possibly falsely reporting space leaks in
+      <filename>libc.so</filename>.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry id="opt.sim-hints" xreflabel="--sim-hints">
+    <term>
+      <option><![CDATA[--sim-hints=hint1,hint2,... ]]></option>
+    </term>
+    <listitem>
+      <para>Pass miscellaneous hints to Valgrind which slightly modify
+      the simulated behaviour in nonstandard or dangerous ways, possibly
+      to help the simulation of strange features.  By default no hints
+      are enabled.  Use with caution!  Currently known hints are:</para>
+      <itemizedlist>
+        <listitem>
+          <para><option>lax-ioctls: </option> Be very lax about ioctl
+          handling; the only assumption is that the size is
+          correct. Doesn't require the full buffer to be initialized
+          when writing.  Without this, using some device drivers with a
+          large number of strange ioctl commands becomes very
+          tiresome.</para>
+        </listitem>
+        <listitem>
+          <para><option>enable-inner: </option> Enable some special
+          magic needed when the program being run is itself
+          Valgrind.</para>
+        </listitem>
+      </itemizedlist>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry id="opt.kernel-variant" xreflabel="--kernel-variant">
+    <term>
+      <option>--kernel-variant=variant1,variant2,...</option>
+    </term>
+    <listitem>
+      <para>Handle system calls and ioctls arising from minor variants
+      of the default kernel for this platform.  This is useful for
+      running on hacked kernels or with kernel modules which support
+      nonstandard ioctls, for example.  Use with caution.  If you don't
+      understand what this option does then you almost certainly don't
+      need it.  Currently known variants are:</para>
+      <itemizedlist>
+        <listitem>
+          <para><option>bproc: </option> Support the sys_broc system
+          call on x86.  This is for running on BProc, which is a minor
+          variant of standard Linux which is sometimes used for building
+          clusters.</para>
+        </listitem>
+      </itemizedlist>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry id="opt.show-emwarns" xreflabel="--show-emwarns">
+    <term>
+      <option><![CDATA[--show-emwarns=<yes|no> [default: no] ]]></option>
+    </term>
+    <listitem>
+      <para>When enabled, Valgrind will emit warnings about its CPU
+      emulation in certain cases.  These are usually not
+      interesting.</para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry id="opt.smc-check" xreflabel="--smc-check">
+    <term>
+      <option><![CDATA[--smc-check=<none|stack|all> [default: stack] ]]></option>
+    </term>
+    <listitem>
+      <para>This option controls Valgrind's detection of self-modifying
+      code.  Valgrind can do no detection, detect self-modifying code on
+      the stack, or detect self-modifying code anywhere.  Note that the
+      default option will catch the vast majority of cases, as far as we
+      know.  Running with <varname>all</varname> will slow Valgrind down
+      greatly (but running with <varname>none</varname> will rarely
+      speed things up, since very little code gets put on the stack for
+      most programs).</para>
+    </listitem>
+  </varlistentry>
+
+</variablelist>
+
 </sect2>
 
 
@@ -1264,14 +1318,13 @@
   <varlistentry>
    <term><command><computeroutput>VALGRIND_COUNT_ERRORS</computeroutput>:</command></term>
    <listitem>
-    <para>returns the number of errors found so far by Valgrind.
-    Can be useful in test harness code when combined with the
-    <computeroutput>--log-fd=-1</computeroutput> option; this
-    runs Valgrind silently, but the client program can detect
-    when errors occur.  Only useful for tools that report errors,
-    e.g. it's useful for Memcheck, but for Cachegrind it will
-    always return zero because Cachegrind doesn't report
-    errors.</para>
+    <para>returns the number of errors found so far by Valgrind.  Can be
+    useful in test harness code when combined with the
+    <option>--log-fd=-1</option> option; this runs Valgrind silently,
+    but the client program can detect when errors occur.  Only useful
+    for tools that report errors, e.g. it's useful for Memcheck, but for
+    Cachegrind it will always return zero because Cachegrind doesn't
+    report errors.</para>
    </listitem>
   </varlistentry>
 
@@ -1350,10 +1403,10 @@
     program on the <emphasis>real</emphasis> CPU, not the virtual
     CPU that Valgrind normally runs code on.  These are used in
     various ways internally to Valgrind.  They might be useful to
-    client programs.</para> <formalpara><title>Warning:</title>
-    <para>Only use these if you <emphasis>really</emphasis> know
-    what you are doing.</para>
-    </formalpara>
+    client programs.</para> 
+
+    <para><command>Warning:</command> Only use these if you
+    <emphasis>really</emphasis> know what you are doing.</para>
    </listitem>
   </varlistentry>
 
@@ -1507,33 +1560,34 @@
 </para>
 
 <para>There are three options (in addition to the usual
-<computeroutput>--prefix=</computeroutput> which affect how Valgrind is built:
+<option>--prefix=</option> which affect how Valgrind is built:
 <itemizedlist>
- <listitem>
-  <para><computeroutput>--enable-inner</computeroutput></para>
-  <para>This builds Valgrind with some special magic hacks which
-   make it possible to run it on a standard build of Valgrind
-   (what the developers call "self-hosting").  Ordinarily you
-   should not use this flag as various kinds of safety checks
-   are disabled.
-   </para>
- </listitem>
 
- <listitem>
-  <para><computeroutput>--enable-tls</computeroutput></para>
-  <para>TLS (Thread Local Storage) is a relatively new mechanism which
-  requires compiler, linker and kernel support.  Valgrind automatically test
-  if TLS is supported and enable this option.  Sometimes it cannot test for
-  TLS, so this option allows you to override the automatic test.</para>
- </listitem>
-
- <listitem>
-  <para><computeroutput>--with-vex=</computeroutput></para>
-  <para>Specifies the path to the underlying VEX dynamic-translation 
-   library.  By default this is taken to be in the VEX directory
-   off the root of the source tree.
+  <listitem>
+    <para><option>--enable-inner</option></para>
+    <para>This builds Valgrind with some special magic hacks which make
+     it possible to run it on a standard build of Valgrind (what the
+     developers call "self-hosting").  Ordinarily you should not use
+     this flag as various kinds of safety checks are disabled.
    </para>
- </listitem>
+  </listitem>
+
+  <listitem>
+    <para><option>--enable-tls</option></para>
+    <para>TLS (Thread Local Storage) is a relatively new mechanism which
+    requires compiler, linker and kernel support.  Valgrind
+    automatically test if TLS is supported and enable this option.
+    Sometimes it cannot test for TLS, so this option allows you to
+    override the automatic test.</para>
+  </listitem>
+
+  <listitem>
+    <para><option>--with-vex=</option></para>
+    <para>Specifies the path to the underlying VEX dynamic-translation
+     library.  By default this is taken to be in the VEX directory off
+     the root of the source tree.
+   </para>
+  </listitem>
 </itemizedlist>
 </para>
 
@@ -1589,83 +1643,79 @@
 <sect1 id="manual-core.limits" xreflabel="Limitations">
 <title>Limitations</title>
 
-<para>The following list of limitations seems long.
-However, most programs actually work fine.</para>
+<para>The following list of limitations seems long.  However, most
+programs actually work fine.</para>
 
-<para>Valgrind will run Linux ELF 
-binaries, on a kernel 2.4.X or 2.6.X system, on the x86, amd64
-and ppc32 architectures, subject to
-the following constraints:</para>
+<para>Valgrind will run Linux ELF binaries, on a kernel 2.4.X or 2.6.X
+system, on the x86, amd64 and ppc32 architectures, subject to the
+following constraints:</para>
 
  <itemizedlist>
   <listitem>
-   <para>On x86 and amd64, there is no support for 3DNow! instructions.  If
-   the translator encounters these, Valgrind will generate a SIGILL when the
-   instruction is executed.  Apart from that, on x86 and amd64, 
+   <para>On x86 and amd64, there is no support for 3DNow! instructions.
+   If the translator encounters these, Valgrind will generate a SIGILL
+   when the instruction is executed.  Apart from that, on x86 and amd64,
    essentially all instructions are supported, up to and including SSE2.
-   Version 3.1.0 includes limited support for SSE3 on x86.  This could be 
-   improved
-   if necessary.</para>
-   <para>On ppc32, almost all integer, floating point and Altivec instructions
-   are supported.</para>
+   Version 3.1.0 includes limited support for SSE3 on x86.  This could
+   be improved if necessary.</para>
+
+   <para>On ppc32, almost all integer, floating point and Altivec
+   instructions are supported.</para>
   </listitem>
 
   <listitem>
    <para>Atomic instruction sequences are not properly supported, in the
-   sense that their atomicity is not preserved.  This will affect
-   any use of synchronization via memory shared between processes.  They
+   sense that their atomicity is not preserved.  This will affect any
+   use of synchronization via memory shared between processes.  They
    will appear to work, but fail sporadically.</para>
   </listitem>
 
   <listitem>
-   <para>If your program does its own memory management, rather
-   than using malloc/new/free/delete, it should still work, but
-   Valgrind's error checking won't be so effective.  If you
-   describe your program's memory management scheme using "client
-   requests" (see <xref linkend="manual-core.clientreq"/>), 
-   Memcheck can do
-   better.  Nevertheless, using malloc/new and free/delete is
-   still the best approach.</para>
+   <para>If your program does its own memory management, rather than
+   using malloc/new/free/delete, it should still work, but Valgrind's
+   error checking won't be so effective.  If you describe your program's
+   memory management scheme using "client requests" 
+   (see <xref linkend="manual-core.clientreq"/>), Memcheck can do
+   better.  Nevertheless, using malloc/new and free/delete is still the
+   best approach.</para>
   </listitem>
 
   <listitem>
-   <para>Valgrind's signal simulation is not as robust as it
-   could be.  Basic POSIX-compliant sigaction and sigprocmask
-   functionality is supplied, but it's conceivable that things
-   could go badly awry if you do weird things with signals.
-   Workaround: don't.  Programs that do non-POSIX signal tricks
-   are in any case inherently unportable, so should be avoided if
-   possible.</para>
+   <para>Valgrind's signal simulation is not as robust as it could be.
+   Basic POSIX-compliant sigaction and sigprocmask functionality is
+   supplied, but it's conceivable that things could go badly awry if you
+   do weird things with signals.  Workaround: don't.  Programs that do
+   non-POSIX signal tricks are in any case inherently unportable, so
+   should be avoided if possible.</para>
   </listitem>
 
   <listitem>
-   <para>Machine instructions, and system calls, have been
-   implemented on demand.  So it's possible, although unlikely,
-   that a program will fall over with a message to that effect.
-   If this happens, please report ALL the details printed out, so
-   we can try and implement the missing feature.</para>
+   <para>Machine instructions, and system calls, have been implemented
+   on demand.  So it's possible, although unlikely, that a program will
+   fall over with a message to that effect.  If this happens, please
+   report ALL the details printed out, so we can try and implement the
+   missing feature.</para>
   </listitem>
 
   <listitem>
-   <para>Memory consumption of your program is majorly increased
-   whilst running under Valgrind.  This is due to the large
-   amount of administrative information maintained behind the
-   scenes.  Another cause is that Valgrind dynamically translates
-   the original executable.  Translated, instrumented code is
-   12-18 times larger than the original so you can easily end
-   up with 50+ MB of translations when running (eg) a web
-   browser.</para>
+   <para>Memory consumption of your program is majorly increased whilst
+   running under Valgrind.  This is due to the large amount of
+   administrative information maintained behind the scenes.  Another
+   cause is that Valgrind dynamically translates the original
+   executable.  Translated, instrumented code is 12-18 times larger than
+   the original so you can easily end up with 50+ MB of translations
+   when running (eg) a web browser.</para>
   </listitem>
 
   <listitem>
-   <para>Valgrind can handle dynamically-generated code just
-   fine.  If you regenerate code over the top of old code
-   (ie. at the same memory addresses), if the code is on the stack Valgrind
-   will realise the code has changed, and work correctly.  This is necessary
-   to handle the trampolines GCC uses to implemented nested functions.
-   If you regenerate code somewhere other than the stack, you will need to
-   use the <computeroutput>--smc-check=all</computeroutput> flag, and
-   Valgrind will run more slowly than normal.</para>
+   <para>Valgrind can handle dynamically-generated code just fine.  If
+   you regenerate code over the top of old code (ie. at the same memory
+   addresses), if the code is on the stack Valgrind will realise the
+   code has changed, and work correctly.  This is necessary to handle
+   the trampolines GCC uses to implemented nested functions.  If you
+   regenerate code somewhere other than the stack, you will need to use
+   the <option>--smc-check=all</option> flag, and Valgrind will run more
+   slowly than normal.</para>
   </listitem>
 
   <listitem>
@@ -1674,26 +1724,25 @@
    the IEEE754 standard.</para>
 
    <para>Precision: There is no support for 80 bit arithmetic.
-   Internally, Valgrind represents all such "long double"
-   numbers in 64 bits, and so
-   there may be some differences in results.  Whether or not this is
-   critical remains to be seen.  Note, the x86/amd64 fldt/fstpt
-   instructions (read/write 80-bit numbers) are correctly simulated,
-   using conversions to/from 64 bits, so that in-memory images of
-   80-bit numbers look correct if anyone wants to see.</para>
+   Internally, Valgrind represents all such "long double" numbers in 64
+   bits, and so there may be some differences in results.  Whether or
+   not this is critical remains to be seen.  Note, the x86/amd64
+   fldt/fstpt instructions (read/write 80-bit numbers) are correctly
+   simulated, using conversions to/from 64 bits, so that in-memory
+   images of 80-bit numbers look correct if anyone wants to see.</para>
 
    <para>The impression observed from many FP regression tests is that
    the accuracy differences aren't significant.  Generally speaking, if
    a program relies on 80-bit precision, there may be difficulties
    porting it to non x86/amd64 platforms which only support 64-bit FP
    precision.  Even on x86/amd64, the program may get different results
-   depending on whether it is compiled to use SSE2 instructions
-   (64-bits only), or x87 instructions (80-bit).  The net effect is to
-   make FP programs behave as if they had been run on a machine with
-   64-bit IEEE floats, for example PowerPC.  On amd64 FP arithmetic is
-   done by default on SSE2, so amd64 looks more like PowerPC than x86
-   from an FP perspective, and there are far fewer noticable accuracy
-   differences than with x86.</para>
+   depending on whether it is compiled to use SSE2 instructions (64-bits
+   only), or x87 instructions (80-bit).  The net effect is to make FP
+   programs behave as if they had been run on a machine with 64-bit IEEE
+   floats, for example PowerPC.  On amd64 FP arithmetic is done by
+   default on SSE2, so amd64 looks more like PowerPC than x86 from an FP
+   perspective, and there are far fewer noticable accuracy differences
+   than with x86.</para>
 
    <para>Rounding: Valgrind does observe the 4 IEEE-mandated rounding
    modes (to nearest, to +infinity, to -infinity, to zero) for the
@@ -1719,10 +1768,9 @@
    <para>When Valgrind detects that the program is trying to exceed any
    of these limitations (setting exception handlers, rounding mode, or
    precision control), it can print a message giving a traceback of
-   where this has happened, and continue execution.  This behaviour
-   used to be the default, but the messages are annoying and so showing
-   them is now optional.  Use
-   <computeroutput>--show-emwarns=yes</computeroutput> to see
+   where this has happened, and continue execution.  This behaviour used
+   to be the default, but the messages are annoying and so showing them
+   is now optional.  Use <option>--show-emwarns=yes</option> to see
    them.</para>
 
    <para>The above limitations define precisely the IEEE754 'default'
@@ -1731,15 +1779,15 @@
   </listitem>
    
   <listitem>
-   <para>As of version 3.0.0, Valgrind has the following limitations
-   in its implementation of x86/AMD64 SSE2 FP arithmetic.</para>
+   <para>As of version 3.0.0, Valgrind has the following limitations in
+   its implementation of x86/AMD64 SSE2 FP arithmetic.</para>
 
-   <para>Essentially the same: no exceptions, and limited observance
-   of rounding mode.  Also, SSE2 has control bits which make it treat
+   <para>Essentially the same: no exceptions, and limited observance of
+   rounding mode.  Also, SSE2 has control bits which make it treat
    denormalised numbers as zero (DAZ) and a related action, flush
    denormals to zero (FTZ).  Both of these cause SSE2 arithmetic to be
-   less accurate than IEEE requires.  Valgrind detects, ignores, and
-   can warn about, attempts to enable either mode.</para>
+   less accurate than IEEE requires.  Valgrind detects, ignores, and can
+   warn about, attempts to enable either mode.</para>
   </listitem>
 
   <listitem>
@@ -1824,71 +1872,75 @@
  <itemizedlist>
 
   <listitem>
-   <para><computeroutput>More than 100 errors detected.
-   Subsequent errors will still be recorded, but in less detail
-   than before.</computeroutput></para>
-   <para>After 100 different errors have been shown, Valgrind
-   becomes more conservative about collecting them.  It then
-   requires only the program counters in the top two stack frames
-   to match when deciding whether or not two errors are really
-   the same one.  Prior to this point, the PCs in the top four
-   frames are required to match.  This hack has the effect of
-   slowing down the appearance of new errors after the first 100.
-   The 100 constant can be changed by recompiling Valgrind.</para>
+    <para><computeroutput>More than 100 errors detected.  Subsequent
+    errors will still be recorded, but in less detail than
+    before.</computeroutput></para>
+
+    <para>After 100 different errors have been shown, Valgrind becomes
+    more conservative about collecting them.  It then requires only the
+    program counters in the top two stack frames to match when deciding
+    whether or not two errors are really the same one.  Prior to this
+    point, the PCs in the top four frames are required to match.  This
+    hack has the effect of slowing down the appearance of new errors
+    after the first 100.  The 100 constant can be changed by recompiling
+    Valgrind.</para>
   </listitem>
 
   <listitem>
-   <para><computeroutput>More than 1000 errors detected.  I'm not
-   reporting any more.  Final error counts may be inaccurate.  Go
-   fix your program!</computeroutput></para>
-   <para>After 1000 different errors have been detected, Valgrind
-   ignores any more.  It seems unlikely that collecting even more
-   different ones would be of practical help to anybody, and it
-   avoids the danger that Valgrind spends more and more of its
-   time comparing new errors against an ever-growing collection.
-   As above, the 1000 number is a compile-time constant.</para>
+    <para><computeroutput>More than 1000 errors detected.  I'm not
+    reporting any more.  Final error counts may be inaccurate.  Go fix
+    your program!</computeroutput></para>
+
+    <para>After 1000 different errors have been detected, Valgrind
+    ignores any more.  It seems unlikely that collecting even more
+    different ones would be of practical help to anybody, and it avoids
+    the danger that Valgrind spends more and more of its time comparing
+    new errors against an ever-growing collection.  As above, the 1000
+    number is a compile-time constant.</para>
   </listitem>
 
   <listitem>
-   <para><computeroutput>Warning: client switching
-   stacks?</computeroutput></para>
-   <para>Valgrind spotted such a large change in the stack
-   pointer, <literal>%esp</literal>, that it guesses the client
-   is switching to a different stack.  At this point it makes a
-   kludgey guess where the base of the new stack is, and sets
-   memory permissions accordingly.  You may get many bogus error
-   messages following this, if Valgrind guesses wrong.  At the
-   moment "large change" is defined as a change of more that
-   2000000 in the value of the <literal>%esp</literal> (stack
-   pointer) register.</para>
+    <para><computeroutput>Warning: client switching stacks?</computeroutput></para>
+
+    <para>Valgrind spotted such a large change in the stack pointer,
+    <literal>%esp</literal>, that it guesses the client is switching to
+    a different stack.  At this point it makes a kludgey guess where the
+    base of the new stack is, and sets memory permissions accordingly.
+    You may get many bogus error messages following this, if Valgrind
+    guesses wrong.  At the moment "large change" is defined as a change
+    of more that 2000000 in the value of the <literal>%esp</literal>
+    (stack pointer) register.</para>
   </listitem>
 
   <listitem>
-   <para><computeroutput>Warning: client attempted to close
-   Valgrind's logfile fd &lt;number&gt;</computeroutput></para>
-   <para>Valgrind doesn't allow the client to close the logfile,
-   because you'd never see any diagnostic information after that
-   point.  If you see this message, you may want to use the
-   <computeroutput>--log-fd=&lt;number&gt;</computeroutput> option
-   to specify a different logfile file-descriptor number.</para>
+    <para><computeroutput>Warning: client attempted to close Valgrind's
+    logfile fd &lt;number&gt;</computeroutput></para>
+
+    <para>Valgrind doesn't allow the client to close the logfile,
+    because you'd never see any diagnostic information after that point.
+    If you see this message, you may want to use the
+    <option>--log-fd=&lt;number&gt;</option> option to specify a
+    different logfile file-descriptor number.</para>
   </listitem>
 
   <listitem>
-   <para><computeroutput>Warning: noted but unhandled ioctl
-   &lt;number&gt;</computeroutput></para>
-   <para>Valgrind observed a call to one of the vast family of
-   <computeroutput>ioctl</computeroutput> system calls, but did
-   not modify its memory status info (because I have not yet got
-   round to it).  The call will still have gone through, but you
-   may get spurious errors after this as a result of the
-   non-update of the memory info.</para>
+    <para><computeroutput>Warning: noted but unhandled ioctl
+    &lt;number&gt;</computeroutput></para>
+
+    <para>Valgrind observed a call to one of the vast family of
+    <computeroutput>ioctl</computeroutput> system calls, but did not
+    modify its memory status info (because I have not yet got round to
+    it).  The call will still have gone through, but you may get
+    spurious errors after this as a result of the non-update of the
+    memory info.</para>
   </listitem>
 
   <listitem>
-   <para><computeroutput>Warning: set address range perms: large
-   range &lt;number></computeroutput></para>
-   <para>Diagnostic message, mostly for benefit of the valgrind
-   developers, to do with memory permissions.</para>
+    <para><computeroutput>Warning: set address range perms: large range
+    &lt;number></computeroutput></para>
+
+    <para>Diagnostic message, mostly for benefit of the Valgrind
+    developers, to do with memory permissions.</para>
   </listitem>
 
  </itemizedlist>
diff --git a/docs/xml/manual-intro.xml b/docs/xml/manual-intro.xml
index c7080d0..35e4a85 100644
--- a/docs/xml/manual-intro.xml
+++ b/docs/xml/manual-intro.xml
@@ -8,13 +8,12 @@
 <sect1 id="manual-intro.overview" xreflabel="An Overview of Valgrind">
 <title>An Overview of Valgrind</title>
 
-<para>Valgrind is a suite of simulation-based debugging and
-profiling tools for programs running on Linux (x86, amd64 and ppc32).
-The system consists of a core, which
-provides a synthetic CPU in software, and a series of tools,
-each of which performs some kind of debugging, profiling, or
-similar task.  The architecture is modular, so that new tools can
-be created easily and without disturbing the existing
+<para>Valgrind is a suite of simulation-based debugging and profiling
+tools for programs running on Linux (x86, amd64 and ppc32).  The system
+consists of a core, which provides a synthetic CPU in software, and a
+series of tools, each of which performs some kind of debugging,
+profiling, or similar task.  The architecture is modular, so that new
+tools can be created easily and without disturbing the existing
 structure.</para>
 
 <para>A number of useful tools are supplied as standard.  In
@@ -23,11 +22,10 @@
 <orderedlist>
 
   <listitem>
-    <para><command>Memcheck</command> detects memory-management
-    problems in your programs.  All reads and writes of memory
-    are checked, and calls to malloc/new/free/delete are
-    intercepted. As a result, Memcheck can detect the following
-    problems:</para>
+    <para><command>Memcheck</command> detects memory-management problems
+    in your programs.  All reads and writes of memory are checked, and
+    calls to malloc/new/free/delete are intercepted. As a result,
+    Memcheck can detect the following problems:</para>
 
     <itemizedlist>
      <listitem>
@@ -60,124 +58,118 @@
       functions</para></listitem> 
     </itemizedlist>
 
-    <para>Problems like these can be difficult to find by other
-    means, often lying undetected for long periods, then causing
-    occasional, difficult-to-diagnose crashes.</para>
+    <para>Problems like these can be difficult to find by other means,
+    often lying undetected for long periods, then causing occasional,
+    difficult-to-diagnose crashes.</para>
    </listitem>
  
    <listitem>
-    <para><command>Addrcheck</command> is a lightweight version
-    of Memcheck.  It is identical to Memcheck except for the
-    single detail that it does not do any uninitialised-value
-    checks.  All of the other checks -- primarily the
-    fine-grained address checking -- are still done.  The
-    downside of this is that you don't catch the
+    <para><command>Addrcheck</command> is a lightweight version of
+    Memcheck.  It is identical to Memcheck except for the single detail
+    that it does not do any uninitialised-value checks.  All of the
+    other checks -- primarily the fine-grained address checking -- are
+    still done.  The downside of this is that you don't catch the
     uninitialised-value errors that Memcheck can find.</para>
 
-    <para>But the upside is significant: programs run about twice
-    as fast as they do on Memcheck, and a lot less memory is
-    used.  It still finds reads/writes of freed memory, memory
-    off the end of blocks and in other invalid places, bugs which
-    you really want to find before release!</para>
+    <para>But the upside is significant: programs run about twice as
+    fast as they do on Memcheck, and a lot less memory is used.  It
+    still finds reads/writes of freed memory, memory off the end of
+    blocks and in other invalid places, bugs which you really want to
+    find before release!</para>
 
-    <para>Because Addrcheck is lighter and faster than Memcheck,
-    you can run more programs for longer, and so you may be able
-    to cover more test scenarios.  Addrcheck was created because
-    one of us (Julian) wanted to be able to run a complete KDE
-    desktop session with checking.  As of early November 2002, we
-    have been able to run KDE-3.0.3 on a 1.7 GHz P4 with 512 MB
-    of memory, using Addrcheck.  Although the result is not
-    stellar, it's quite usable, and it seems plausible to run KDE
-    for long periods at a time like this, collecting up all the
-    addressing errors that appear.</para>
+    <para>Because Addrcheck is lighter and faster than Memcheck, you can
+    run more programs for longer, and so you may be able to cover more
+    test scenarios.  Addrcheck was created because one of us (Julian)
+    wanted to be able to run a complete KDE desktop session with
+    checking.  As of early November 2002, we have been able to run
+    KDE-3.0.3 on a 1.7 GHz P4 with 512 MB of memory, using Addrcheck.
+    Although the result is not stellar, it's quite usable, and it seems
+    plausible to run KDE for long periods at a time like this,
+    collecting up all the addressing errors that appear.</para>
 
     <para>NOTE: Addrcheck is not available in Valgrind 3.1.X.  We hope
-    to reinstate its functionality in later releases.  For now, use 
+    to reinstate its functionality in later releases.  For now, use
     Memcheck instead.</para>
    </listitem>
 
    <listitem>
     <para><command>Cachegrind</command> is a cache profiler.  It
-    performs detailed simulation of the I1, D1 and L2 caches in
-    your CPU and so can accurately pinpoint the sources of cache
-    misses in your code.  If you desire, it will show the number
-    of cache misses, memory references and instructions accruing
-    to each line of source code, with per-function, per-module
-    and whole-program summaries.  If you ask really nicely it
-    will even show counts for each individual machine
-    instruction.</para>
+    performs detailed simulation of the I1, D1 and L2 caches in your CPU
+    and so can accurately pinpoint the sources of cache misses in your
+    code.  If you desire, it will show the number of cache misses,
+    memory references and instructions accruing to each line of source
+    code, with per-function, per-module and whole-program summaries.  If
+    you ask really nicely it will even show counts for each individual
+    machine instruction.</para>
 
     <para>On x86 and AMD64, Cachegrind auto-detects your machine's cache
-    configuration using the
-    <computeroutput>CPUID</computeroutput> instruction, and so
-    needs no further configuration info, in most cases.</para>
+    configuration using the <computeroutput>CPUID</computeroutput>
+    instruction, and so needs no further configuration info, in most
+    cases.</para>
 
-    <para>Cachegrind is nicely complemented by Josef
-    Weidendorfer's amazing KCacheGrind visualisation tool 
+    <para>Cachegrind is nicely complemented by Josef Weidendorfer's
+    amazing KCacheGrind visualisation tool 
     (<ulink url="http://kcachegrind.sourceforge.net/cgi-bin/show.cgi/KcacheGrindIndex">http://kcachegrind.sourceforge.net</ulink>),
     a KDE application which presents these profiling results in a
     graphical and easier-to-understand form.</para>
    </listitem>
 
    <listitem>
-    <para><command>Helgrind</command> finds data races in
-    multithreaded programs.  Helgrind looks for memory locations
-    which are accessed by more than one (POSIX p-)thread, but for
-    which no consistently used (pthread_mutex_)lock can be found.
-    Such locations are indicative of missing synchronisation
-    between threads, and could cause hard-to-find
-    timing-dependent problems.</para>
+    <para><command>Helgrind</command> finds data races in multithreaded
+    programs.  Helgrind looks for memory locations which are accessed by
+    more than one (POSIX p-)thread, but for which no consistently used
+    (pthread_mutex_)lock can be found.  Such locations are indicative of
+    missing synchronisation between threads, and could cause
+    hard-to-find timing-dependent problems.</para>
 
-    <para>Helgrind ("Hell's Gate", in Norse mythology) implements
-    the so-called "Eraser" data-race-detection algorithm, along
-    with various refinements (thread-segment lifetimes) which
-    reduce the number of false errors it reports.  It is as yet
-    somewhat of an experimental tool, so your feedback is
-    especially welcomed here.</para>
+    <para>Helgrind ("Hell's Gate", in Norse mythology) implements the
+    so-called "Eraser" data-race-detection algorithm, along with various
+    refinements (thread-segment lifetimes) which reduce the number of
+    false errors it reports.  It is as yet somewhat of an experimental
+    tool, so your feedback is especially welcomed here.</para>
 
     <para>Helgrind has been hacked on extensively by Jeremy
     Fitzhardinge, and we have him to thank for getting it to a
     releasable state.</para>
 
-    <para>NOTE: Helgrind is, unfortunately, not available in Valgrind 3.1.X,
-    as a result of threading changes that happened in the 2.4.0 release.
-    We hope to reinstate its functionality in a future 3.2.0 release.</para>
+    <para>NOTE: Helgrind is, unfortunately, not available in Valgrind
+    3.1.X, as a result of threading changes that happened in the 2.4.0
+    release.  We hope to reinstate its functionality in a future 3.2.0
+    release.</para>
    </listitem>
 
 </orderedlist>
   
 
-<para>A couple of minor tools (<command>Lackey</command> 
-and <command>Nulgrind</command>) are
-also supplied.  These aren't particularly useful -- they exist to
-illustrate how to create simple tools and to help the valgrind
-developers in various ways.  Nulgrind is the null tool -- it adds 
-no instrumentation.  Lackey is a simple example tool 
-which counts instructions, memory accesses, and the number of
+<para>A couple of minor tools (<command>Lackey</command> and
+<command>Nulgrind</command>) are also supplied.  These aren't
+particularly useful -- they exist to illustrate how to create simple
+tools and to help the valgrind developers in various ways.  Nulgrind is
+the null tool -- it adds no instrumentation.  Lackey is a simple example
+tool which counts instructions, memory accesses, and the number of
 integer and floating point operations your program does.</para>
 
 <para>Valgrind is closely tied to details of the CPU and operating
 system, and to a lesser extent, the compiler and basic C libraries.
-Nonetheless, as of version 3.1.0 it supports several platforms: x86/Linux
-(mature), AMD64/Linux (maturing), and PPC32/Linux (immature but works well).
-Valgrind uses the standard Unix
+Nonetheless, as of version 3.1.0 it supports several platforms:
+x86/Linux (mature), AMD64/Linux (maturing), and PPC32/Linux (immature
+but works well).  Valgrind uses the standard Unix
 <computeroutput>./configure</computeroutput>,
 <computeroutput>make</computeroutput>, <computeroutput>make
-install</computeroutput> mechanism, and we have attempted to
-ensure that it works on machines with kernel 2.4 or 2.6 and glibc
+install</computeroutput> mechanism, and we have attempted to ensure that
+it works on machines with kernel 2.4 or 2.6 and glibc
 2.2.X--2.3.X.</para>
 
 <para>Valgrind is licensed under the <xref linkend="license.gpl"/>,
-version 2.  The <computeroutput>valgrind/*.h</computeroutput> headers that
-you may wish to include in your code (eg.
-<computeroutput>valgrind.h</computeroutput>,
-<computeroutput>memcheck.h</computeroutput>) are
-distributed under a BSD-style license, so you may include them in your code
-without worrying about license conflicts.  Some of the PThreads test cases,
-<computeroutput>pth_*.c</computeroutput>, are taken from
-"Pthreads Programming" by Bradford Nichols, Dick Buttlar &amp;
-Jacqueline Proulx Farrell, ISBN 1-56592-115-1, published by
-O'Reilly &amp; Associates, Inc.</para>
+version 2.  The <computeroutput>valgrind/*.h</computeroutput> headers
+that you may wish to include in your code (eg.
+<filename>valgrind.h</filename>, <filename>memcheck.h</filename>) are
+distributed under a BSD-style license, so you may include them in your
+code without worrying about license conflicts.  Some of the PThreads
+test cases, <filename>pth_*.c</filename>, are taken from "Pthreads
+Programming" by Bradford Nichols, Dick Buttlar &amp; Jacqueline Proulx
+Farrell, ISBN 1-56592-115-1, published by O'Reilly &amp; Associates,
+Inc.</para>
 
 </sect1>
 
@@ -185,26 +177,23 @@
 <sect1 id="manual-intro.navigation" xreflabel="How to navigate this manual">
 <title>How to navigate this manual</title>
 
-<para>The Valgrind distribution consists of the Valgrind core,
-upon which are built Valgrind tools, which do different kinds of
-debugging and profiling.  This manual is structured
-similarly.</para>
+<para>The Valgrind distribution consists of the Valgrind core, upon
+which are built Valgrind tools, which do different kinds of debugging
+and profiling.  This manual is structured similarly.</para>
 
-<para>First, we describe the Valgrind core, how to use it, and
-the flags it supports.  Then, each tool has its own chapter in
-this manual.  You only need to read the documentation for the
-core and for the tool(s) you actually use, although you may find
-it helpful to be at least a little bit familar with what all
-tools do.  If you're new to all this, you probably want to run
-the Memcheck tool.  If you want to write a new tool, read 
-<xref linkend="writing-tools"/>.</para>
+<para>First, we describe the Valgrind core, how to use it, and the flags
+it supports.  Then, each tool has its own chapter in this manual.  You
+only need to read the documentation for the core and for the tool(s) you
+actually use, although you may find it helpful to be at least a little
+bit familar with what all tools do.  If you're new to all this, you
+probably want to run the Memcheck tool.  If you want to write a new
+tool, read <xref linkend="writing-tools"/>.</para>
 
-<para>Be aware that the core understands some command line flags,
-and the tools have their own flags which they know about.  This
-means there is no central place describing all the flags that are
-accepted -- you have to read the flags documentation both for
-<xref linkend="manual-core"/> and for the tool you want to
-use.</para>
+<para>Be aware that the core understands some command line flags, and
+the tools have their own flags which they know about.  This means there
+is no central place describing all the flags that are accepted -- you
+have to read the flags documentation both for 
+<xref linkend="manual-core"/> and for the tool you want to use.</para>
 
 </sect1>
 
diff --git a/docs/xml/manual.xml b/docs/xml/manual.xml
index aa2f8c1..1599aed 100644
--- a/docs/xml/manual.xml
+++ b/docs/xml/manual.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0"?> <!-- -*- sgml -*- -->
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" 
 [ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
 
 
@@ -13,9 +13,9 @@
     <year>&vg-lifespan;</year>
     <holder><ulink url="&vg-developers;">Valgrind Developers</ulink></holder>
    </copyright>
-   <author>
-     <email><ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></email>
-   </author>
+   <legalnotice>
+     <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para>
+   </legalnotice>
 </bookinfo>
 
   <xi:include href="manual-intro.xml" parse="xml"  
diff --git a/docs/xml/quick-start-guide.xml b/docs/xml/quick-start-guide.xml
index d4daf27..771e063 100644
--- a/docs/xml/quick-start-guide.xml
+++ b/docs/xml/quick-start-guide.xml
@@ -12,9 +12,9 @@
     <year>&vg-lifespan;</year>
     <holder><ulink url="&vg-developers;">Valgrind Developers</ulink></holder>
   </copyright>
-  <author>
-    <email><ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></email>
-  </author>
+  <legalnotice>
+    <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para>
+  </legalnotice>
 </bookinfo>
 
 
@@ -25,27 +25,31 @@
 <sect1 id="quick-start.intro" xreflabel="Introduction">
 <title>Introduction</title>
 
-<para>The Valgrind distribution has multiple tools.  The most popular is the
-memory checking tool (called Memcheck) which can detect many common memory
-errors such as:</para>
+<para>The Valgrind distribution has multiple tools.  The most popular is
+the memory checking tool (called Memcheck) which can detect many common
+memory errors such as:</para>
 
 <itemizedlist>
- <listitem><para>touching memory you shouldn't (eg. overrunning heap block 
+  <listitem>
+    <para>touching memory you shouldn't (eg. overrunning heap block
     boundaries);</para>
- </listitem>
- <listitem><para>using values before they have been initialized;</para>
- </listitem>
- <listitem><para>incorrect freeing of memory, such as double-freeing heap
-  blocks;</para>
- </listitem>
- <listitem><para>memory leaks.</para>
- </listitem>
+  </listitem>
+  <listitem>
+    <para>using values before they have been initialized;</para>
+  </listitem>
+  <listitem>
+    <para>incorrect freeing of memory, such as double-freeing heap
+    blocks;</para>
+  </listitem>
+  <listitem>
+    <para>memory leaks.</para>
+  </listitem>
 </itemizedlist>
 
-<para>What follows is the minimum information you need to start detecting
-memory errors in your program with Memcheck.  Note that this guide applies
-to Valgrind version 2.4.0 and later;  some of the information is not quite
-right for earlier versions.</para>
+<para>What follows is the minimum information you need to start
+detecting memory errors in your program with Memcheck.  Note that this
+guide applies to Valgrind version 2.4.0 and later; some of the
+information is not quite right for earlier versions.</para>
 
 </sect1>
 
@@ -53,15 +57,17 @@
 <sect1 id="quick-start.prepare" xreflabel="Preparing your program">
 <title>Preparing your program</title>
 
-<para>Compile your program with <computeroutput>-g</computeroutput> to include
-debugging information so that Memcheck's error messages include exact line
-numbers.  Using <computeroutput>-O0</computeroutput> is also a good idea, if
-you can tolerate the slowdown.  With <computeroutput>-O1</computeroutput> 
-line numbers in error messages can be inaccurate, although generally speaking
-Memchecking code compiled at <computeroutput>-O1</computeroutput> works 
-fairly well.  Use of <computeroutput>-O2</computeroutput> and above is
-not recommended as Memcheck occasionally reports uninitialised-value
-errors which don't really exist.</para>
+<para>Compile your program with <option>-g</option> to include debugging
+information so that Memcheck's error messages include exact line
+numbers.  Using <computeroutput>-O0</computeroutput> is also a good
+idea, if you can tolerate the slowdown.  With
+<computeroutput>-O1</computeroutput> line numbers in error messages can
+be inaccurate, although generally speaking Memchecking code compiled at
+<computeroutput>-O1</computeroutput> works fairly well.  Use of
+<computeroutput>-O2</computeroutput> and above is not recommended as
+Memcheck occasionally reports uninitialised-value errors which don't
+really exist.</para>
+
 </sect1>
 
 
@@ -69,24 +75,20 @@
 <title>Running your program under Memcheck</title>
 
 <para>If you normally run your program like this:
-
-<programlisting>
-  myprog arg1 arg2
+<programlisting>    myprog arg1 arg2
 </programlisting>
 
 Use this command line:
-
-<programlisting>
-  valgrind --leak-check=yes myprog arg1 arg2
+<programlisting>    valgrind --leak-check=yes myprog arg1 arg2
 </programlisting>
 
-Memcheck is the default tool.  The
-<computeroutput>--leak-check</computeroutput> option turns on the detailed
-memory leak detector.</para>
+Memcheck is the default tool.  The <option>--leak-check</option> option
+turns on the detailed memory leak detector.</para>
 
-<para>Your program will run much slower (eg. 20 to 30 times) than normal,
-and use a lot more memory.  Memcheck will issue messages about memory errors
-and leaks that it detects.</para>
+<para>Your program will run much slower (eg. 20 to 30 times) than
+normal, and use a lot more memory.  Memcheck will issue messages about
+memory errors and leaks that it detects.</para>
+
 </sect1>
 
 
@@ -111,8 +113,8 @@
   }
 </programlisting>
 
-Most error messages look like the following, which describes problem 1, the
-heap block overrun:
+Most error messages look like the following, which describes problem 1,
+the heap block overrun:
 
 <programlisting>
   ==19182== Invalid write of size 4
@@ -127,44 +129,40 @@
 Things to notice:
 
 <itemizedlist>
- <listitem>
- <para>There is a lot of information in each error message;  read it
- carefully.</para> 
- </listitem>
-
- <listitem>
- <para>The 19182 is the process ID;  it's usually unimportant.</para>
- </listitem>
-
- <listitem>
- <para>The first line ("Invalid write...") tells you what kind of error it
- is.  Here, the program wrote to some memory it should not have due to a
- heap block overrun.</para>
- </listitem>
-
- <listitem>
- <para>Below the first line is a stack trace telling you where the problem
-   occurred.  Stack traces can get quite large, and be confusing, especially
-   if you are using the C++ STL.  Reading them from the bottom up can help.
-   If the stack trace is not big enough, use the
-   <computeroutput>--num-callers</computeroutput> option to make it
-   bigger.</para>
- </listitem>
-
- <listitem>
- <para>The code addresses (eg. 0x804838F) are usually unimportant, but
- occasionally crucial for tracking down weirder bugs.</para>
- </listitem>
-
- <listitem>
- <para>Some error messages have a second component which describes the memory
-   address involved.  This one shows that the written memory is just past
-   the end of a block allocated with malloc() on line 5 of example.c.</para>
- </listitem>
+  <listitem>
+   <para>There is a lot of information in each error message; read it
+   carefully.</para>
+  </listitem>
+  <listitem>
+    <para>The 19182 is the process ID;  it's usually unimportant.</para>
+  </listitem>
+  <listitem>
+   <para>The first line ("Invalid write...") tells you what kind of
+   error it is.  Here, the program wrote to some memory it should not
+   have due to a heap block overrun.</para>
+  </listitem>
+  <listitem>
+    <para>Below the first line is a stack trace telling you where the
+    problem occurred.  Stack traces can get quite large, and be
+    confusing, especially if you are using the C++ STL.  Reading them
+    from the bottom up can help.  If the stack trace is not big enough,
+    use the <option>--num-callers</option> option to make it
+    bigger.</para>
+  </listitem>
+  <listitem>
+   <para>The code addresses (eg. 0x804838F) are usually unimportant, but
+   occasionally crucial for tracking down weirder bugs.</para>
+  </listitem>
+  <listitem>
+    <para>Some error messages have a second component which describes
+    the memory address involved.  This one shows that the written memory
+    is just past the end of a block allocated with malloc() on line 5 of
+    example.c.</para>
+  </listitem>
 </itemizedlist>
 
-It's worth fixing errors in the order they are reported, as later
-errors can be caused by earlier errors.</para>
+It's worth fixing errors in the order they are reported, as later errors
+can be caused by earlier errors.</para>
 
 <para>Memory leak messages look like this:
 
@@ -176,25 +174,28 @@
 </programlisting>
 
 The stack trace tells you where the leaked memory was allocated.
-Memcheck cannot tell you why the memory leaked, unfortunately.  (Ignore the
-"vg_replace_malloc.c", that's an implementation detail.)</para>
+Memcheck cannot tell you why the memory leaked, unfortunately.  (Ignore
+the "vg_replace_malloc.c", that's an implementation detail.)</para>
 
-<para>There are several kinds of leaks;  the two most important categories are:
+<para>There are several kinds of leaks; the two most important
+categories are:
 
 <itemizedlist>
- <listitem><para>"definitely lost":  your program is leaking memory -- fix
- it!</para>
- </listitem>
-
- <listitem><para>"probably lost":  your program is leaking memory, unless
-   you're doing funny things with pointers (such as moving them to point to
-   the middle of a heap block).</para>
- </listitem>
+  <listitem>
+    <para>"definitely lost": your program is leaking memory -- fix
+    it!</para>
+  </listitem>
+  <listitem>
+    <para>"probably lost": your program is leaking memory, unless you're
+    doing funny things with pointers (such as moving them to point to
+    the middle of a heap block).</para>
+  </listitem>
 </itemizedlist>
 
 If you don't understand an error message, please consult 
-<xref linkend="mc-manual.errormsgs"/> in the <xref linkend="manual"/> which has
-examples of all the error messages Memcheck produces.</para>
+<xref linkend="mc-manual.errormsgs"/> in the <xref linkend="manual"/>
+which has examples of all the error messages Memcheck produces.</para>
+
 </sect1>
 
 
@@ -206,25 +207,28 @@
 <xref linkend="manual-core.suppress"/> in the <xref linkend="manual"/>).
 However, it is typically right 99% of the time, so you should be wary of
 ignoring its error messages.  After all, you wouldn't ignore warning
-messages produced by a compiler, right?  The suppression mechanism is also
-useful if Memcheck is reporting errors in library code that you cannot
-change;  the default suppression set hides a lot of these, but you may
-come across more.</para>
+messages produced by a compiler, right?  The suppression mechanism is
+also useful if Memcheck is reporting errors in library code that you
+cannot change; the default suppression set hides a lot of these, but you
+may come across more.</para>
 
-<para>Memcheck also cannot detect every memory error your program has.  For
-example, it can't detect if you overrun the bounds of an array that is
-allocated statically or on the stack.  But it should detect every error that
-could crash your program (eg. cause a segmentation fault).</para>
+<para>Memcheck also cannot detect every memory error your program has.
+For example, it can't detect if you overrun the bounds of an array that
+is allocated statically or on the stack.  But it should detect every
+error that could crash your program (eg. cause a segmentation
+fault).</para>
+
 </sect1>
 
 
 <sect1 id="quick-start.info" xreflabel="More Information">
 <title>More information</title>
 
-<para>Please consult the <xref linkend="FAQ"/> and the
-<xref linkend="manual"/>, which have much more information.  Note that the
-other tools in the Valgrind distribution can be invoked with the
-<computeroutput>--tool</computeroutput> option.</para>
+<para>Please consult the <xref linkend="FAQ"/> and the 
+<xref linkend="manual"/>, which have much more information.  Note that
+the other tools in the Valgrind distribution can be invoked with the
+<option>--tool</option> option.</para>
+
 </sect1>
 
 
diff --git a/docs/xml/tech-docs.xml b/docs/xml/tech-docs.xml
index 050db3d..825c8e1 100644
--- a/docs/xml/tech-docs.xml
+++ b/docs/xml/tech-docs.xml
@@ -5,17 +5,17 @@
 
 <book id="tech-docs" xreflabel="Valgrind Technical Documentation">
 
-  <bookinfo>
-    <title>Valgrind Technical Documentation</title>
-    <releaseinfo>&rel-type; &rel-version; &rel-date;</releaseinfo>
+<bookinfo>
+  <title>Valgrind Technical Documentation</title>
+  <releaseinfo>&rel-type; &rel-version; &rel-date;</releaseinfo>
   <copyright>
     <year>&vg-lifespan;</year>
     <holder><ulink url="&vg-developers;">Valgrind Developers</ulink></holder>
   </copyright>
-  <author>
-    <email><ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></email>
-  </author>
-  </bookinfo>
+  <legalnotice>
+    <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para>
+  </legalnotice>
+</bookinfo>
 
   <xi:include href="../../memcheck/docs/mc-tech-docs.xml" parse="xml"  
       xmlns:xi="http://www.w3.org/2001/XInclude" />
diff --git a/docs/xml/valgrind-manpage.xml b/docs/xml/valgrind-manpage.xml
new file mode 100644
index 0000000..4ea3ac0
--- /dev/null
+++ b/docs/xml/valgrind-manpage.xml
@@ -0,0 +1,255 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+          "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
+
+
+<refentry id="valgrind">
+
+<refmeta>
+  <refentrytitle>VALGRIND</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo>Release &rel-version;</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>valgrind</refname>
+  <refpurpose>a suite of tools for debugging and profiling programs</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+  <command>valgrind</command>
+  <arg>
+    <arg><replaceable>valgrind</replaceable></arg>
+    <arg><replaceable>options</replaceable></arg>
+  </arg>
+  <arg><replaceable>your-program</replaceable></arg>
+  <arg>
+    <arg><replaceable>your-program-options</replaceable></arg>
+  </arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsect1 id="description">
+<title>Description</title>
+
+<para><command>Valgrind</command> is a flexible program for debugging
+and profiling Linux executables.  It consists of a core, which provides
+a synthetic CPU in software, and a series of "tools", each of which is a
+debugging or profiling tool. The architecture is modular, so that new
+tools can be created easily and without disturbing the existing
+structure.</para>
+
+<para>This manual page covers only basic usage and options.  For more
+comprehensive information, please see the HTML documentation on your
+system: <filename>&vg-doc-path;</filename>, or online:
+<filename>&vg-bookset;</filename>.</para>
+
+</refsect1>
+
+
+<refsect1 id="invocation">
+<title>Invocation</title>
+
+<para><command>Valgrind</command> is typically invoked as follows:
+<literallayout>    valgrind program args</literallayout>
+
+This runs <command>program</command> (with arguments
+<command>args</command>) under Valgrind using the Memcheck tool.
+Memcheck performs a range of memory-checking functions, including
+detecting accesses to uninitialised memory, misuse of allocated memory
+(double frees, access after free, etc.) and detecting memory
+leaks.</para>
+
+<para>To use a different tool, use the <option>--tool</option> option:
+<literallayout>    valgrind --tool=toolname program args</literallayout></para>
+
+<para>The following tools are available:</para>
+
+<itemizedlist>
+
+  <listitem>
+    <para><option>cachegrind</option> is a cache simulator.  It can be
+    used to annotate every line of your program with the number of
+    instructions executed and cache misses incurred.</para>
+  </listitem>
+
+  <listitem>
+    <para><option>helgrind</option> spots potential race conditions in
+    your program.</para>
+  </listitem>
+
+  <listitem>
+    <para><option>lackey</option> is a sample tool that can be used as a
+    template for generating your own tools. After the program
+    terminates, it prints out some basic statistics about the program
+    execution.</para>
+  </listitem>
+
+  <listitem>
+    <para><option>massif</option> is a heap profiler.  It measures how
+    much heap memory your program uses.</para>
+  </listitem>
+
+  <listitem>
+    <para><option>memcheck</option> is a fine-grained memory checker.</para>
+  </listitem>
+
+  <listitem>
+    <para><option>none</option> performs no function - it simply runs
+    the program under Valgrind.  This is typically used for debugging
+    and benchmarking Valgrind.</para>
+  </listitem>
+
+</itemizedlist>
+
+</refsect1>
+
+
+
+<refsect1 id="basic-options">
+<title>Basic Options</title>
+
+<para>These options work with all tools.</para>
+
+<xi:include href="manual-core.xml" xpointer="basic.opts"
+            xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="error-related-options">
+<title>Error-Related Options</title>
+
+<para>These options are used by all tools that can report errors,
+e.g. Memcheck, but not Cachegrind.</para>
+
+<xi:include href="manual-core.xml" xpointer="error-related.opts"
+            xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="malloc-related-options">
+<title>malloc()-related Options</title>
+
+<para>For tools that use their own version of
+<function>malloc()</function> (e.g. Memcheck and Addrcheck), the
+following options apply.</para>
+
+<xi:include href="manual-core.xml" xpointer="malloc-related.opts"
+            xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="uncommon-options">
+<title>Uncommon Options</title>
+
+<para>These options apply to all tools, as they affect certain obscure
+workings of the Valgrind core.  Most people won't need to use
+these.</para>
+
+<xi:include href="manual-core.xml" xpointer="uncommon.opts"
+            xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="debugging-valgrind-options">
+<title>Debugging Valgrind Options</title>
+
+<para>There are also some options for debugging Valgrind itself.  You
+shouldn't need to use them in the normal run of things.  If you wish to
+see the list, use the <option>--help-debug</option> option.</para>
+
+</refsect1>
+
+
+
+<refsect1 id="memcheck-options">
+<title>Memcheck Options</title>
+
+<xi:include href="../../memcheck/docs/mc-manual.xml" xpointer="mc.opts"
+            xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="cachegrind-options">
+<title>Cachegrind Options</title>
+
+<xi:include href="../../cachegrind/docs/cg-manual.xml" xpointer="cg.opts.p1"
+            xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+<xi:include href="../../cachegrind/docs/cg-manual.xml" xpointer="cg.opts"
+            xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="massif-options">
+<title>Massif Options</title>
+
+<xi:include href="../../massif/docs/ms-manual.xml" xpointer="ms.opts"
+            xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="helgrind-options">
+<title>Helgrind Options</title>
+
+<xi:include href="../../helgrind/docs/hg-manual.xml" xpointer="hg.opts"
+            xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="lackey-options">
+<title>Lackey Options</title>
+
+<xi:include href="../../lackey/docs/lk-manual.xml" xpointer="lk.opts"
+            xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="see_also">
+<title>See Also</title>
+
+<para>
+<filename>&vg-doc-path;</filename>, 
+and/or 
+<filename>&vg-bookset;</filename>.
+</para>
+
+</refsect1>
+
+
+<refsect1 id="author">
+<title>Author</title>
+
+<para>This manpage has been written by Andres Roldan &lt;aroldan@debian.org&gt;
+for the Debian Project, but can be used for any other distribution.</para>
+
+<para>Updated, rearranged and expanded by Robert Walsh
+&lt;rjwalsh@durables.org&gt; for the 2.4.0 release, and by other
+Valgrind developers subsequently.</para>
+
+</refsect1>
+
+
+</refentry>
+
diff --git a/docs/xml/vg-entities.xml b/docs/xml/vg-entities.xml
index c8045d3..305c5dd 100644
--- a/docs/xml/vg-entities.xml
+++ b/docs/xml/vg-entities.xml
@@ -4,17 +4,20 @@
 <!ENTITY vg-vemail     "valgrind@valgrind.org">
 <!ENTITY vg-lifespan   "2000-2005">
 <!ENTITY vg-users-list "http://lists.sourceforge.net/lists/listinfo/valgrind-users">
-<!ENTITY vg-developers "http://www.valgrind.org/info/developers.html">
-<!ENTITY vg-svn-repo   "http://www.valgrind.org/downloads/repository.html">
-<!ENTITY vg-bookset    "http://www.valgrind.org/docs/manual/index.html">
-<!ENTITY vg-dist-docs  "http://www.valgrind.org/docs/manual/dist.html">
-
 
 <!-- valgrind release + version stuff -->
 <!ENTITY rel-type    "Release">
 <!ENTITY rel-version "3.1.0">
 <!ENTITY rel-date    "November 25 2005">
 
+<!-- where the docs are installed -->
+<!ENTITY vg-doc-path  "/usr/share/doc/valgrind/html/index.html">
+
 <!-- valgrind website links used in lots of places in the docs  -->
 <!-- kept in here 'cos everytime the website gets changed, it`s -->
 <!-- a real pain tracking the links down in the docs            -->
+<!ENTITY vg-developers "http://www.valgrind.org/info/developers.html">
+<!ENTITY vg-svn-repo   "http://www.valgrind.org/downloads/repository.html">
+<!ENTITY vg-bookset    "http://www.valgrind.org/docs/manual/index.html">
+<!ENTITY vg-dist-docs  "http://www.valgrind.org/docs/manual/dist.html">
+<!ENTITY vg-commentary "http://www.valgrind.org/docs/manual/manual-core.html#manual-core.comment">
diff --git a/docs/xml/writing-tools.xml b/docs/xml/writing-tools.xml
index 0c3068c..0ef1648 100644
--- a/docs/xml/writing-tools.xml
+++ b/docs/xml/writing-tools.xml
@@ -3,6 +3,7 @@
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
 
+
 <chapter id="writing-tools" xreflabel="Writing a New Valgrind Tool">
 <title>Writing a New Valgrind Tool</title>
 
@@ -279,18 +280,16 @@
 <sect2 id="writing-tools.howtoolswork" xreflabel="How tools work">
 <title>How tools work</title>
 
-<para>Tools must define various functions for instrumenting
-programs that are called by Valgrind's core. They are then linked
-against the coregrind library
-(<computeroutput>libcoregrind.a</computeroutput>) that valgrind
-provides as well as the VEX library
-(<computeroutput>libvex.a</computeroutput>) that also comes with
-valgrind and provides the JIT engine.</para>
+<para>Tools must define various functions for instrumenting programs
+that are called by Valgrind's core. They are then linked against the
+coregrind library (<filename>libcoregrind.a</filename>) that valgrind
+provides as well as the VEX library (<filename>libvex.a</filename>) that
+also comes with valgrind and provides the JIT engine.</para>
 
-<para>Each tool is linked as a statically linked program and placed
-in the valgrind library directory from where valgrind will load it
-automatically when the <computeroutput>--tool</computeroutput> option
-is used to select it.</para>
+<para>Each tool is linked as a statically linked program and placed in
+the valgrind library directory from where valgrind will load it
+automatically when the <option>--tool</option> option is used to select
+it.</para>
 
 </sect2>
 
@@ -298,11 +297,11 @@
 <sect2 id="writing-tools.gettingcode" xreflabel="Getting the code">
 <title>Getting the code</title>
 
-<para>To write your own tool, you'll need the Valgrind source code.
-A normal source distribution should do, although you might want to
-check out the latest code from the Subversion repository.  See the
-information about how to do so at 
-<ulink url="&vg-svn-repo;">the Valgrind website</ulink>.</para>
+<para>To write your own tool, you'll need the Valgrind source code.  A
+normal source distribution should do, although you might want to check
+out the latest code from the Subversion repository.  See the information
+about how to do so at <ulink url="&vg-svn-repo;">the Valgrind
+website</ulink>.</para>
 
 </sect2>
 
@@ -310,68 +309,59 @@
 <sect2 id="writing-tools.gettingstarted" xreflabel="Getting started">
 <title>Getting started</title>
 
-<para>Valgrind uses GNU <computeroutput>automake</computeroutput>
-and <computeroutput>autoconf</computeroutput> for the creation of
-Makefiles and configuration.  But don't worry, these instructions
-should be enough to get you started even if you know nothing
-about those tools.</para>
+<para>Valgrind uses GNU <computeroutput>automake</computeroutput> and
+<computeroutput>autoconf</computeroutput> for the creation of Makefiles
+and configuration.  But don't worry, these instructions should be enough
+to get you started even if you know nothing about those tools.</para>
 
 <para>In what follows, all filenames are relative to Valgrind's
 top-level directory <computeroutput>valgrind/</computeroutput>.</para>
 
 <orderedlist>
  <listitem>
-  <para>Choose a name for the tool, and an abbreviation that can
-  be used as a short prefix.  We'll use
-  <computeroutput>foobar</computeroutput> and
-  <computeroutput>fb</computeroutput> as an example.</para>
+  <para>Choose a name for the tool, and an abbreviation that can be used
+  as a short prefix.  We'll use <computeroutput>foobar</computeroutput>
+  and <computeroutput>fb</computeroutput> as an example.</para>
  </listitem>
 
  <listitem>
-  <para>Make a new directory
-  <computeroutput>foobar/</computeroutput> which will hold the
-  tool.</para>
+  <para>Make a new directory <computeroutput>foobar/</computeroutput>
+  which will hold the tool.</para>
  </listitem>
 
  <listitem>
-  <para>Copy <computeroutput>none/Makefile.am</computeroutput>
-  into <computeroutput>foobar/</computeroutput>.  Edit it by
-  replacing all occurrences of the string
-  <computeroutput>"none"</computeroutput> with
-  <computeroutput>"foobar"</computeroutput> and the one
-  occurrence of the string <computeroutput>"nl_"</computeroutput>
-  with <computeroutput>"fb_"</computeroutput>.  It might be worth
-  trying to understand this file, at least a little; you might
-  have to do more complicated things with it later on.  In
-  particular, the name of the
-  <computeroutput>foobar_SOURCES</computeroutput>
-  variable determines the name of the tool, which
-  determines what name must be passed to the
-  <computeroutput>--tool</computeroutput> option to use the
-  tool.</para>
+  <para>Copy <filename>none/Makefile.am</filename> into
+  <computeroutput>foobar/</computeroutput>.  Edit it by replacing all
+  occurrences of the string <computeroutput>"none"</computeroutput> with
+  <computeroutput>"foobar"</computeroutput> and the one occurrence of
+  the string <computeroutput>"nl_"</computeroutput> with
+  <computeroutput>"fb_"</computeroutput>.  It might be worth trying to
+  understand this file, at least a little; you might have to do more
+  complicated things with it later on.  In particular, the name of the
+  <computeroutput>foobar_SOURCES</computeroutput> variable determines
+  the name of the tool, which determines what name must be passed to the
+  <option>--tool</option> option to use the tool.</para>
  </listitem>
 
  <listitem>
   <para>Copy <filename>none/nl_main.c</filename> into
   <computeroutput>foobar/</computeroutput>, renaming it as
-  <filename>fb_main.c</filename>.  Edit it by changing the lines
-  in <computeroutput>pre_clo_init()</computeroutput> to
-  something appropriate for the tool.  These fields are used in
-  the startup message, except for
-  <computeroutput>bug_reports_to</computeroutput> which is used
-  if a tool assertion fails.</para>
+  <filename>fb_main.c</filename>.  Edit it by changing the lines in
+  <function>pre_clo_init()</function> to something appropriate for the
+  tool.  These fields are used in the startup message, except for
+  <computeroutput>bug_reports_to</computeroutput> which is used if a
+  tool assertion fails.</para>
  </listitem>
 
   <listitem>
-   <para>Edit <computeroutput>Makefile.am</computeroutput>,
-   adding the new directory
+   <para>Edit <filename>Makefile.am</filename>, adding the new directory
    <computeroutput>foobar</computeroutput> to the
    <computeroutput>SUBDIRS</computeroutput> variable.</para>
   </listitem>
 
   <listitem>
-   <para>Edit <computeroutput>configure.in</computeroutput>,
-   adding <computeroutput>foobar/Makefile</computeroutput> to the
+   <para>Edit <filename>configure.in</filename>, adding
+   <filename>foobar/Makefile</filename> to the
    <computeroutput>AC_OUTPUT</computeroutput> list.</para>
   </listitem>
 
@@ -382,8 +372,8 @@
   ./configure --prefix=`pwd`/inst
   make install]]></programlisting>
 
-   <para>It should automake, configure and compile without
-   errors, putting copies of the tool in
+   <para>It should automake, configure and compile without errors,
+   putting copies of the tool in
    <computeroutput>foobar/</computeroutput> and
    <computeroutput>inst/lib/valgrind/</computeroutput>.</para>
   </listitem>
@@ -412,13 +402,13 @@
 
 </orderedlist>
 
-<para>These steps don't have to be followed exactly - you can
-choose different names for your source files, and use a different
-<computeroutput>--prefix</computeroutput> for
+<para>These steps don't have to be followed exactly - you can choose
+different names for your source files, and use a different
+<option>--prefix</option> for
 <computeroutput>./configure</computeroutput>.</para>
 
-<para>Now that we've setup, built and tested the simplest
-possible tool, onto the interesting stuff...</para>
+<para>Now that we've setup, built and tested the simplest possible tool,
+onto the interesting stuff...</para>
 
 </sect2>
 
@@ -435,16 +425,15 @@
   fini()]]></programlisting>
 
 <para>Also, it must use the macro
-<computeroutput>VG_DETERMINE_INTERFACE_VERSION</computeroutput>
-exactly once in its source code.  If it doesn't, you will get a
-link error involving
-<computeroutput>VG_(tool_interface_version)</computeroutput>.
-This macro is used to ensure the core/tool interface used by the
-core and a plugged-in tool are binary compatible.</para>
+<computeroutput>VG_DETERMINE_INTERFACE_VERSION</computeroutput> exactly
+once in its source code.  If it doesn't, you will get a link error
+involving <computeroutput>VG_(tool_interface_version)</computeroutput>.
+This macro is used to ensure the core/tool interface used by the core
+and a plugged-in tool are binary compatible.</para>
 
-<para>In addition, if a tool wants to use some of the optional
-services provided by the core, it may have to define other
-functions and tell the code about them.</para>
+<para>In addition, if a tool wants to use some of the optional services
+provided by the core, it may have to define other functions and tell the
+code about them.</para>
 
 </sect2>
 
@@ -454,58 +443,52 @@
 <title>Initialisation</title>
 
 <para>Most of the initialisation should be done in
-<computeroutput>pre_clo_init()</computeroutput>.  Only use
-<computeroutput>post_clo_init()</computeroutput> if a tool
-provides command line options and must do some initialisation
-after option processing takes place
-(<computeroutput>"clo"</computeroutput> stands for "command line
+<function>pre_clo_init()</function>.  Only use
+<function>post_clo_init()</function> if a tool provides command line
+options and must do some initialisation after option processing takes
+place (<computeroutput>"clo"</computeroutput> stands for "command line
 options").</para>
 
-<para>First of all, various "details" need to be set for a tool,
-using the functions
-<computeroutput>VG_(details_*)()</computeroutput>.  Some are all
-compulsory, some aren't.  Some are used when constructing the
-startup message,
-<computeroutput>detail_bug_reports_to</computeroutput> is used if
-<computeroutput>VG_(tool_panic)()</computeroutput> is ever
-called, or a tool assertion fails.  Others have other uses.</para>
+<para>First of all, various "details" need to be set for a tool, using
+the functions <function>VG_(details_*)()</function>.  Some are all
+compulsory, some aren't.  Some are used when constructing the startup
+message, <computeroutput>detail_bug_reports_to</computeroutput> is used
+if <computeroutput>VG_(tool_panic)()</computeroutput> is ever called, or
+a tool assertion fails.  Others have other uses.</para>
 
-<para>Second, various "needs" can be set for a tool, using the
-functions <computeroutput>VG_(needs_*)()</computeroutput>.  They
-are mostly booleans, and can be left untouched (they default to
-<computeroutput>False</computeroutput>).  They determine whether
-a tool can do various things such as: record, report and suppress
-errors; process command line options; wrap system calls; record
-extra information about malloc'd blocks, etc.</para>
+<para>Second, various "needs" can be set for a tool, using the functions
+<function>VG_(needs_*)()</function>.  They are mostly booleans, and can
+be left untouched (they default to <varname>False</varname>).  They
+determine whether a tool can do various things such as: record, report
+and suppress errors; process command line options; wrap system calls;
+record extra information about malloc'd blocks, etc.</para>
 
-<para>For example, if a tool wants the core's help in recording
-and reporting errors, it must call
-<computeroutput>VG_(needs_tool_errors)</computeroutput> and provide
-definitions of eight functions for comparing errors, printing out
-errors, reading suppressions from a suppressions file, etc.
-While writing these functions requires some work, it's much less
-than doing error handling from scratch because the core is doing
-most of the work.  See the function
-<computeroutput>VG_(needs_tool_errors)</computeroutput> in
-<filename>include/pub_tool_tooliface.h</filename> for full details of all
-the needs.</para>
+<para>For example, if a tool wants the core's help in recording and
+reporting errors, it must call
+<function>VG_(needs_tool_errors)</function> and provide definitions of
+eight functions for comparing errors, printing out errors, reading
+suppressions from a suppressions file, etc.  While writing these
+functions requires some work, it's much less than doing error handling
+from scratch because the core is doing most of the work.  See the
+function <function>VG_(needs_tool_errors)</function> in
+<filename>include/pub_tool_tooliface.h</filename> for full details of
+all the needs.</para>
 
-<para>Third, the tool can indicate which events in core it wants
-to be notified about, using the functions
-<computeroutput>VG_(track_*)()</computeroutput>.  These include
-things such as blocks of memory being malloc'd, the stack pointer
-changing, a mutex being locked, etc.  If a tool wants to know
-about this, it should provide a pointer to a function, which will
-be called when that event happens.</para>
+<para>Third, the tool can indicate which events in core it wants to be
+notified about, using the functions <function>VG_(track_*)()</function>.
+These include things such as blocks of memory being malloc'd, the stack
+pointer changing, a mutex being locked, etc.  If a tool wants to know
+about this, it should provide a pointer to a function, which will be
+called when that event happens.</para>
 
-<para>For example, if the tool want to be notified when a new
-block of memory is malloc'd, it should call
-<computeroutput>VG_(track_new_mem_heap)()</computeroutput> with
-an appropriate function pointer, and the assigned function will
-be called each time this happens.</para>
+<para>For example, if the tool want to be notified when a new block of
+memory is malloc'd, it should call
+<function>VG_(track_new_mem_heap)()</function> with an appropriate
+function pointer, and the assigned function will be called each time
+this happens.</para>
 
-<para>More information about "details", "needs" and "trackable
-events" can be found in
+<para>More information about "details", "needs" and "trackable events"
+can be found in
 <filename>include/pub_tool_tooliface.h</filename>.</para>
 
 </sect2>
@@ -515,17 +498,16 @@
 <sect2 id="writing-tools.instr" xreflabel="Instrumentation">
 <title>Instrumentation</title>
 
-<para><computeroutput>instrument()</computeroutput> is the
-interesting one.  It allows you to instrument
-<emphasis>VEX IR</emphasis>, which is Valgrind's RISC-like
-intermediate language.  VEX IR is described in 
+<para><function>instrument()</function> is the interesting one.  It
+allows you to instrument <emphasis>VEX IR</emphasis>, which is
+Valgrind's RISC-like intermediate language.  VEX IR is described in
 <xref linkend="mc-tech-docs.ucode"/>.</para>
 
 <para>The easiest way to instrument VEX IR is to insert calls to C
 functions when interesting things happen.  See the tool "Lackey"
-(<filename>lackey/lk_main.c</filename>) for a simple example of
-this, or Cachegrind (<filename>cachegrind/cg_main.c</filename>)
-for a more complex example.</para>
+(<filename>lackey/lk_main.c</filename>) for a simple example of this, or
+Cachegrind (<filename>cachegrind/cg_main.c</filename>) for a more
+complex example.</para>
 
 </sect2>
 
@@ -534,9 +516,9 @@
 <sect2 id="writing-tools.fini" xreflabel="Finalisation">
 <title>Finalisation</title>
 
-<para>This is where you can present the final results, such as a
-summary of the information collected.  Any log files should be
-written out at this point.</para>
+<para>This is where you can present the final results, such as a summary
+of the information collected.  Any log files should be written out at
+this point.</para>
 
 </sect2>
 
@@ -545,36 +527,34 @@
 <sect2 id="writing-tools.otherinfo" xreflabel="Other Important Information">
 <title>Other Important Information</title>
 
-<para>Please note that the core/tool split infrastructure is
-quite complex and not brilliantly documented.  Here are some
-important points, but there are undoubtedly many others that I
-should note but haven't thought of.</para>
+<para>Please note that the core/tool split infrastructure is quite
+complex and not brilliantly documented.  Here are some important points,
+but there are undoubtedly many others that I should note but haven't
+thought of.</para>
 
-<para>The files <filename>include/pub_tool_*.h</filename> contain
-all the types, macros, functions, etc. that a tool should
-(hopefully) need, and are the only <filename>.h</filename> files
-a tool should need to
+<para>The files <filename>include/pub_tool_*.h</filename> contain all
+the types, macros, functions, etc. that a tool should (hopefully) need,
+and are the only <filename>.h</filename> files a tool should need to
 <computeroutput>#include</computeroutput>.</para>
 
-<para>In particular, you can't use anything from the
-C library (there are deep reasons for this, trust us).  Valgrind
-provides an implementation of a reasonable subset of the C
-library, details of which are in
-<filename>pub_tool_libc*.h</filename>.</para>
+<para>In particular, you can't use anything from the C library (there
+are deep reasons for this, trust us).  Valgrind provides an
+implementation of a reasonable subset of the C library, details of which
+are in <filename>pub_tool_libc*.h</filename>.</para>
 
-<para>Similarly, when writing a tool, you shouldn't need to look
-at any of the code in Valgrind's core.  Although it might be
-useful sometimes to help understand something.</para>
+<para>Similarly, when writing a tool, you shouldn't need to look at any
+of the code in Valgrind's core.  Although it might be useful sometimes
+to help understand something.</para>
 
 <para>The <filename>pub_tool_*.h</filename> files have a reasonable
-amount of documentation in it that should hopefully be enough to get
-you going.  But ultimately, the tools distributed (Memcheck,
-Addrcheck, Cachegrind, Lackey, etc.) are probably the best
-documentation of all, for the moment.</para>
+amount of documentation in it that should hopefully be enough to get you
+going.  But ultimately, the tools distributed (Memcheck, Addrcheck,
+Cachegrind, Lackey, etc.) are probably the best documentation of all,
+for the moment.</para>
 
 <para>Note that the <computeroutput>VG_</computeroutput> macro is used
-heavily.  This just prepends a longer string in front of names to
-avoid potential namespace clashes.</para>
+heavily.  This just prepends a longer string in front of names to avoid
+potential namespace clashes.</para>
 
 </sect2>
 
@@ -589,8 +569,9 @@
 <sect3 id="writing-tools.segfaults">
 <title>Segmentation Faults</title>
 
-<para>If you are getting segmentation faults in C functions used
-by your tool, the usual GDB command:</para>
+<para>If you are getting segmentation faults in C functions used by your
+tool, the usual GDB command:</para>
+
 <screen><![CDATA[
   gdb <prog> core]]></screen>
 <para>usually gives the location of the segmentation fault.</para>
@@ -601,49 +582,51 @@
 <sect3 id="writing-tools.debugfns">
 <title>Debugging C functions</title>
 
-<para>If you want to debug C functions used by your tool, you can 
+<para>If you want to debug C functions used by your tool, you can
 achieve this by following these steps:</para>
 <orderedlist>
- <listitem>
-  <para>Set <computeroutput>VALGRIND_LAUNCHER</computeroutput> to 
-   <computeroutput><![CDATA[<prefix>/bin/valgrind]]></computeroutput>:</para>
+  <listitem>
+    <para>Set <computeroutput>VALGRIND_LAUNCHER</computeroutput> to
+    <computeroutput><![CDATA[<prefix>/bin/valgrind]]></computeroutput>:</para>
 <programlisting>
   export VALGRIND_LAUNCHER=/usr/local/bin/valgrind</programlisting>
- </listitem>
+  </listitem>
 
- <listitem>
-  <para>Then run <computeroutput><![CDATA[ gdb <prefix>/lib/valgrind/<platform>/<tool>:]]></computeroutput></para>
+  <listitem>
+    <para>Then run <computeroutput><![CDATA[ gdb <prefix>/lib/valgrind/<platform>/<tool>:]]></computeroutput></para>
 <programlisting>
   gdb /usr/local/lib/valgrind/ppc32-linux/lackey</programlisting>
- </listitem>
+  </listitem>
 
- <listitem>
-  <para>Do <computeroutput>handle SIGSEGV SIGILL nostop noprint</computeroutput> in
-  GDB to prevent GDB from stopping on a SIGSEGV or SIGILL:</para>
+  <listitem>
+    <para>Do <computeroutput>handle SIGSEGV SIGILL nostop
+    noprint</computeroutput> in GDB to prevent GDB from stopping on a
+    SIGSEGV or SIGILL:</para>
 <programlisting>
   (gdb) handle SIGILL SIGSEGV nostop noprint</programlisting>
- </listitem>
+  </listitem>
 
- <listitem>
-  <para>Set any breakpoints you want and proceed as normal for GDB:</para>
+  <listitem>
+    <para>Set any breakpoints you want and proceed as normal for GDB:</para>
 <programlisting>
   (gdb) b vgPlain_do_exec</programlisting>
-  <para>The macro VG_(FUNC) is expanded to vgPlain_FUNC, so If you
-  want to set a breakpoint VG_(do_exec), you could do like this in GDB.</para>
- </listitem>
+    <para>The macro VG_(FUNC) is expanded to vgPlain_FUNC, so If you
+    want to set a breakpoint VG_(do_exec), you could do like this in
+    GDB.</para>
+  </listitem>
 
- <listitem>
-  <para>Run the tool with required options:</para>
+  <listitem>
+    <para>Run the tool with required options:</para>
 <programlisting>
   (gdb) run `pwd`</programlisting>
- </listitem>
+  </listitem>
 
 </orderedlist>
 
-<para>GDB may be able to give you useful information.  Note that
-by default most of the system is built with
-<computeroutput>-fomit-frame-pointer</computeroutput>, and you'll
-need to get rid of this to extract useful tracebacks from GDB.</para>
+<para>GDB may be able to give you useful information.  Note that by
+default most of the system is built with
+<option>-fomit-frame-pointer</option>, and you'll need to get rid of
+this to extract useful tracebacks from GDB.</para>
 
 </sect3>
 
@@ -651,11 +634,10 @@
 <sect3 id="writing-tools.ucode-probs">
 <title>UCode Instrumentation Problems</title>
 
-<para>If you are having problems with your VEX UIR instrumentation,
-it's likely that GDB won't be able to help at all.  In this case,
-Valgrind's <computeroutput>--trace-flags</computeroutput>
-option is invaluable for observing the results of
-instrumentation.</para>
+<para>If you are having problems with your VEX UIR instrumentation, it's
+likely that GDB won't be able to help at all.  In this case, Valgrind's
+<option>--trace-flags</option> option is invaluable for observing the
+results of instrumentation.</para>
 
 </sect3>
 
@@ -663,13 +645,13 @@
 <sect3 id="writing-tools.misc">
 <title>Miscellaneous</title>
 
-<para>If you just want to know whether a program point has been
-reached, using the <computeroutput>OINK</computeroutput> macro
-(in <filename>include/pub_tool_libcprint.h</filename>) can be easier
-than using GDB.</para>
+<para>If you just want to know whether a program point has been reached,
+using the <computeroutput>OINK</computeroutput> macro (in
+<filename>include/pub_tool_libcprint.h</filename>) can be easier than
+using GDB.</para>
 
-<para>The other debugging command line options can be useful too
-(run <computeroutput>valgrind --help-debug</computeroutput> for the
+<para>The other debugging command line options can be useful too (run
+<computeroutput>valgrind --help-debug</computeroutput> for the
 list).</para>
 
 </sect3>
@@ -689,30 +671,27 @@
 <sect2 id="writing-tools.suppressions" xreflabel="Suppressions">
 <title>Suppressions</title>
 
-<para>If your tool reports errors and you want to suppress some
-common ones, you can add suppressions to the suppression files.
-The relevant files are
-<computeroutput>valgrind/*.supp</computeroutput>; the final
-suppression file is aggregated from these files by combining the
-relevant <computeroutput>.supp</computeroutput> files depending
-on the versions of linux, X and glibc on a system.</para>
+<para>If your tool reports errors and you want to suppress some common
+ones, you can add suppressions to the suppression files.  The relevant
+files are <filename>valgrind/*.supp</filename>; the final suppression
+file is aggregated from these files by combining the relevant
+<filename>.supp</filename> files depending on the versions of linux, X
+and glibc on a system.</para>
 
 <para>Suppression types have the form
 <computeroutput>tool_name:suppression_name</computeroutput>.  The
-<computeroutput>tool_name</computeroutput> here is the name you
-specify for the tool during initialisation with
-<computeroutput>VG_(details_name)()</computeroutput>.</para>
+<computeroutput>tool_name</computeroutput> here is the name you specify
+for the tool during initialisation with
+<function>VG_(details_name)()</function>.</para>
 
 </sect2>
 
 
-<!--
 <sect2 id="writing-tools.docs" xreflabel="Documentation">
 <title>Documentation</title>
 
-<para>As of version &rel-version;, Valgrind documentation has
-been converted to XML. Why? 
-See <ulink url="http://www.ucc.ie/xml/">The XML FAQ</ulink>.
+<para>As of version 3.0.0, Valgrind documentation has been converted to
+XML. Why?  See <ulink url="http://www.ucc.ie/xml/">The XML FAQ</ulink>.
 </para>
 
 
@@ -743,186 +722,14 @@
 <computeroutput>valgrind/docs/lib/</computeroutput>. You
 shouldn't need to modify these in any way.</para>
 
-<para><command>Catalogs:</command> Assuming that you have the
-various tools listed above installed, you will probably need to
-modify
-<computeroutput>valgrind/docs/lib/vg-catalog.xml</computeroutput>
-so that the parser can find your DocBook installation. Catalogs
-provide a mapping from generic addresses to specific local
-directories on a given machine.  Just add another
-<computeroutput>group</computeroutput> to this file, reflecting
-your local installation.</para>
-
-</sect3>
-
-
-<sect3 id="writing-tools.writing" xreflabel="Writing the Documentation">
-<title>Writing the Documentation</title>
-
-<para>If you aren't confident using XML, or you have problems
-with the toolchain, then write your documentation in text format,
-email it to
-<computeroutput>&vg-vemail;</computeroutput>, and
-someone will convert it to XML for you.  Otherwise, follow these
-steps (using <computeroutput>foobar</computeroutput> as the
-example tool name again):</para>
-
-<orderedlist>
-
-  <listitem>
-   <para>Make a directory
-  <computeroutput>valgrind/foobar/docs/</computeroutput>.</para>
- </listitem>
-
- <listitem>
-  <para>Copy the xml tool documentation template file 
-  <computeroutput>valgrind/docs/xml/tool-template.xml</computeroutput>
-  to <computeroutput>foobar/docs/</computeroutput>, and rename it
-  to
-  <computeroutput>foobar/docs/fb-manual.xml</computeroutput>.</para>
-  <para><command>Note</command>: there is a *really stupid* tetex
-  bug with underscores in filenames, so don't use '_'.</para>
- </listitem>
-
- <listitem>
-  <para>Write the documentation.  There are some helpful bits and
-  pieces on using xml markup in
-  <filename>valgrind/docs/xml/xml_help.txt</filename>.</para>
- </listitem>
-
- <listitem>
-  <para>Validate <computeroutput>foobar/docs/fb-manual.xml</computeroutput>
-  using the shell script
-  <filename>valgrind/docs/lib/xmlproc.sh</filename>.</para>
-<screen><![CDATA[
-% cd valgrind/docs/lib/
-% ./xmlproc.sh -valid ../../foobar/docs/fb-manual.xml
-]]></screen>
-
-   <para>If you have linked to other documents in the Valgrind
-   Documentation Set, you will get errors of the form:</para>
-
-<screen><![CDATA[
-fb-manual.xml:1632: element xref: validity error : 
-        IDREF attribute linkend references an unknown ID "mc-tech-docs"
-]]></screen>
-
-   <para>Ignore (only) these - they will disappear when
-   <filename>fb-manual.xml</filename> is integrated into the
-   Set.</para>
-
-  <para>Because the xml toolchain is fragile, it is important to
-  ensure that <computeroutput>fb-manual.xml</computeroutput> won't
-  break the documentation set build.  Note that just because an
-  xml file happily transforms to html does not necessarily mean
-  the same holds true for pdf/ps.</para>
- </listitem>
-
- <listitem>
-  <para>You can (re-)generate <filename>fb-manual.html</filename>
-  while you are writing <filename>fb-manual.xml</filename> to help
-  you see how it's looking.  The generated file
-  <filename>fb-manual.html</filename> will be output in
-  <computeroutput>foobar/docs/</computeroutput>.</para>
-
-<screen><![CDATA[
-% ./xmlproc.sh -html ../../foobar/docs/fb-manual.xml
-]]></screen>
- </listitem>
-
- <listitem>
-  <para>When you have finished, generate html, pdf and ps output
-  to check all is well:</para>
-
-<screen><![CDATA[
-% cp ../../foobar/fb-manual.xml .
-% ./xmlproc.sh -test fb-manual.xml
-]]></screen>
-
-   <para>Check the output files (<filename>index.html,
-   fb-manual.pdf, fb-manual.ps</filename>) in
-   <computeroutput>/lib/test/</computeroutput> with the relevant
-   viewers.  When you are happy and have finished tinkering with
-   <computeroutput>fb-manual.xml</computeroutput>:</para>
-
-<screen><![CDATA[
-% ./xmlproc.sh -clean fb-manual.xml
-]]></screen>
-</listitem>
-
- <listitem>
-  <para>In order for your documentation to be included in the
-  User Manual, the relevant entries must be made in
-  <filename>/valgrind/docs/xml/vg-bookset.xml</filename> in this
-  format (hopefully, it should be pretty obvious):</para>
-
-<programlisting><![CDATA[
-<!ENTITY fb-manual   SYSTEM "../../foobar/docs/fb-manual.xml">
-... ...
-&fb-manual;
-]]></programlisting>
-
-  <para>Send a patch for this to
-  <computeroutput>&vg-vemail;</computeroutput>.</para>
-
-  <para>To achieve true anality, try for a full doc-set build:</para>
-<screen><![CDATA[
-% cd valgrind/docs/
-% make all
-]]></screen>
- </listitem>
-
-</orderedlist>
-
-</sect3>
-
-</sect2>
--->
-<sect2 id="writing-tools.docs" xreflabel="Documentation">
-<title>Documentation</title>
-
-<para>As of version &rel-version;, Valgrind documentation has
-been converted to XML. Why? 
-See <ulink url="http://www.ucc.ie/xml/">The XML FAQ</ulink>.
-</para>
-
-
-<sect3 id="writing-tools.xml" xreflabel="The XML Toolchain">
-<title>The XML Toolchain</title>
-
-<para>If you are feeling conscientious and want to write some
-documentation for your tool, please use XML.  The Valgrind
-Docs use the following toolchain and versions:</para>
-
-<programlisting>
- xmllint:   using libxml version 20607
- xsltproc:  using libxml 20607, libxslt 10102 and libexslt 802
- pdfxmltex: pdfTeX (Web2C 7.4.5) 3.14159-1.10b
- pdftops:   version 3.00
- DocBook:   version 4.2
-</programlisting>
-
-<para><command>Latency:</command> you should note that latency is
-a big problem: DocBook is constantly being updated, but the tools
-tend to lag behind somewhat.  It is important that the versions
-get on with each other, so if you decide to upgrade something,
-then you need to ascertain whether things still work nicely -
-this *cannot* be assumed.</para>
-
-<para><command>Stylesheets:</command> The Valgrind docs use
-various custom stylesheet layers, all of which are in
-<computeroutput>valgrind/docs/lib/</computeroutput>. You
-shouldn't need to modify these in any way.</para>
-
-<para><command>Catalogs:</command> Assuming that you have the
-various tools listed above installed, you will probably need to
-modify
-<computeroutput>valgrind/docs/lib/vg-catalog.xml</computeroutput>
-so that the parser can find your DocBook installation. Catalogs
-provide a mapping from generic addresses to specific local
-directories on a given machine.  Just add another
-<computeroutput>group</computeroutput> to this file, reflecting
-your local installation.</para>
+<para><command>Catalogs:</command> Catalogs provide a mapping from
+generic addresses to specific local directories on a given machine.
+Most recent Linux distributions have adopted a common place for storing
+catalogs (<filename>/etc/xml/</filename>).  Assuming that you have the
+various tools listed above installed, you probably won't need to modify
+your catalogs.  But if you do, then just add another
+<computeroutput>group</computeroutput> to this file, reflecting your
+local installation.</para>
 
 </sect3>
 
@@ -937,34 +744,34 @@
 
   <listitem>
    <para>Make a directory
-  <computeroutput>valgrind/foobar/docs/</computeroutput>.</para>
- </listitem>
+   <computeroutput>valgrind/foobar/docs/</computeroutput>.</para>
+  </listitem>
 
- <listitem>
-  <para>Copy the XML documentation file for the tool Nulgrind from
-  <computeroutput>valgrind/none/docs/nl-manual.xml</computeroutput>
-  to <computeroutput>foobar/docs/</computeroutput>, and rename it
-  to
-  <computeroutput>foobar/docs/fb-manual.xml</computeroutput>.</para>
-  <para><command>Note</command>: there is a *really stupid* tetex
-  bug with underscores in filenames, so don't use '_'.</para>
- </listitem>
+  <listitem>
+    <para>Copy the XML documentation file for the tool Nulgrind from
+    <filename>valgrind/none/docs/nl-manual.xml</filename> to
+    <computeroutput>foobar/docs/</computeroutput>, and rename it to
+    <filename>foobar/docs/fb-manual.xml</filename>.</para>
 
- <listitem>
-  <para>Write the documentation. There are some helpful bits and
-  pieces on using xml markup in
-  <filename>valgrind/docs/xml/xml_help.txt</filename>.</para>
- </listitem>
+    <para><command>Note</command>: there is a *really stupid* tetex bug
+    with underscores in filenames, so don't use '_'.</para>
+  </listitem>
 
- <listitem>
-  <para>Include it in the User Manual by adding the relevant entry must
-  be added to <filename>valgrind/docs/xml/manual.xml</filename>.  Copy
-  and edit an existing entry.</para>
- </listitem>
+  <listitem>
+    <para>Write the documentation. There are some helpful bits and
+    pieces on using xml markup in
+    <filename>valgrind/docs/xml/xml_help.txt</filename>.</para>
+  </listitem>
 
- <listitem>
-  <para>Validate <computeroutput>foobar/docs/fb-manual.xml</computeroutput>
-  using the following command from within <filename>valgrind/docs/</filename>:
+  <listitem>
+    <para>Include it in the User Manual by adding the relevant entry to
+    <filename>valgrind/docs/xml/manual.xml</filename>.  Copy and edit an
+    existing entry.</para>
+  </listitem>
+
+  <listitem>
+    <para>Validate <filename>foobar/docs/fb-manual.xml</filename> using
+    the following command from within <filename>valgrind/docs/</filename>:
   </para>
 <screen><![CDATA[
 % make valid
@@ -977,41 +784,37 @@
 attribute base of element chapter
 ]]></screen>
 
-  <para>Ignore (only) these -- they're not important.</para>
+   <para>Ignore (only) these -- they're not important.</para>
 
-  <para>Because the xml toolchain is fragile, it is important to
-  ensure that <filename>fb-manual.xml</filename> won't
-  break the documentation set build.  Note that just because an
-  xml file happily transforms to html does not necessarily mean
-  the same holds true for pdf/ps.</para>
- </listitem>
+   <para>Because the xml toolchain is fragile, it is important to ensure
+   that <filename>fb-manual.xml</filename> won't break the documentation
+   set build.  Note that just because an xml file happily transforms to
+   html does not necessarily mean the same holds true for pdf/ps.</para>
+  </listitem>
 
- <listitem>
-  <para>You can (re-)generate the HTML docs
-  while you are writing <filename>fb-manual.xml</filename> to help
-  you see how it's looking.  The generated files end up in
-  <filename>valgrind/docs/html/</filename>.  Use the following
-  command, within <filename>valgrind/docs/</filename>:</para>
-
+  <listitem>
+    <para>You can (re-)generate the HTML docs while you are writing
+    <filename>fb-manual.xml</filename> to help you see how it's looking.
+    The generated files end up in
+    <filename>valgrind/docs/html/</filename>.  Use the following
+    command, within <filename>valgrind/docs/</filename>:</para>
 <screen><![CDATA[
 % make html-docs
 ]]></screen>
- </listitem>
+  </listitem>
 
- <listitem>
-  <para>When you have finished, also generate pdf and ps output
-  to check all is well, from within <filename>valgrind/docs/</filename>:
+  <listitem>
+    <para>When you have finished, also generate pdf and ps output to
+    check all is well, from within <filename>valgrind/docs/</filename>:
   </para>
-
 <screen><![CDATA[
 % make print-docs
 ]]></screen>
 
-   <para>Check the output <filename>.pdf</filename> and
-   <filename>.ps</filename> files in
-   <computeroutput>valgrind/docs/print/</computeroutput>. 
-   </para>
-</listitem>
+    <para>Check the output <filename>.pdf</filename> and
+    <filename>.ps</filename> files in
+    <computeroutput>valgrind/docs/print/</computeroutput>.</para>
+  </listitem>
 
 </orderedlist>
 
@@ -1023,52 +826,50 @@
 <sect2 id="writing-tools.regtests" xreflabel="Regression Tests">
 <title>Regression Tests</title>
 
-<para>Valgrind has some support for regression tests.  If you
-want to write regression tests for your tool:</para>
+<para>Valgrind has some support for regression tests.  If you want to
+write regression tests for your tool:</para>
 
 <orderedlist>
- <listitem>
-  <para>Make a directory
-  <computeroutput>foobar/tests/</computeroutput>.  Make sure the name
-  of the directory is <computeroutput>tests/</computeroutput> as the
-  build system assumes that any tests for the tool will be in a
-  directory by that name.</para>
- </listitem>
+  <listitem>
+    <para>Make a directory
+    <computeroutput>foobar/tests/</computeroutput>.  Make sure the name
+    of the directory is <computeroutput>tests/</computeroutput> as the
+    build system assumes that any tests for the tool will be in a
+    directory by that name.</para>
+  </listitem>
 
- <listitem>
-  <para>Edit <computeroutput>configure.in</computeroutput>,
-  adding <computeroutput>foobar/tests/Makefile</computeroutput>
-  to the <computeroutput>AC_OUTPUT</computeroutput> list.</para>
- </listitem>
+  <listitem>
+    <para>Edit <filename>configure.in</filename>, adding
+    <filename>foobar/tests/Makefile</filename> to the
+    <computeroutput>AC_OUTPUT</computeroutput> list.</para>
+  </listitem>
 
- <listitem>
-  <para>Write
-  <computeroutput>foobar/tests/Makefile.am</computeroutput>.  Use
-  <computeroutput>memcheck/tests/Makefile.am</computeroutput> as
-  an example.</para>
- </listitem>
+  <listitem>
+    <para>Write <filename>foobar/tests/Makefile.am</filename>.  Use
+    <filename>memcheck/tests/Makefile.am</filename> as an
+    example.</para>
+  </listitem>
 
- <listitem>
-  <para>Write the tests, <computeroutput>.vgtest</computeroutput>
-  test description files,
-  <computeroutput>.stdout.exp</computeroutput> and
-  <computeroutput>.stderr.exp</computeroutput> expected output
-  files.  (Note that Valgrind's output goes to stderr.)  Some
-  details on writing and running tests are given in the comments
-  at the top of the testing script
-  <computeroutput>tests/vg_regtest</computeroutput>.</para>
- </listitem>
+  <listitem>
+    <para>Write the tests, <computeroutput>.vgtest</computeroutput> test
+    description files, <computeroutput>.stdout.exp</computeroutput> and
+    <computeroutput>.stderr.exp</computeroutput> expected output files.
+    (Note that Valgrind's output goes to stderr.)  Some details on
+    writing and running tests are given in the comments at the top of
+    the testing script
+    <computeroutput>tests/vg_regtest</computeroutput>.</para>
+  </listitem>
 
- <listitem>
-  <para>Write a filter for stderr results
-  <computeroutput>foobar/tests/filter_stderr</computeroutput>.
-  It can call the existing filters in
-  <computeroutput>tests/</computeroutput>.  See
-  <computeroutput>memcheck/tests/filter_stderr</computeroutput>
-  for an example; in particular note the
-  <computeroutput>$dir</computeroutput> trick that ensures the
-  filter works correctly from any directory.</para>
- </listitem>
+  <listitem>
+    <para>Write a filter for stderr results
+    <computeroutput>foobar/tests/filter_stderr</computeroutput>.  It can
+    call the existing filters in
+    <computeroutput>tests/</computeroutput>.  See
+    <computeroutput>memcheck/tests/filter_stderr</computeroutput> for an
+    example; in particular note the
+    <computeroutput>$dir</computeroutput> trick that ensures the filter
+    works correctly from any directory.</para>
+  </listitem>
 
 </orderedlist>
 
@@ -1079,27 +880,26 @@
 <sect2 id="writing-tools.profiling" xreflabel="Profiling">
 <title>Profiling</title>
 
-<para>Nb: as of 25-Mar-2005, the profiling is broken, and has been
-for a long time...</para>
+<para>Nb: as of 25-Mar-2005, the profiling is broken, and has been for a
+long time...</para>
 
 <para>To do simple tick-based profiling of a tool, include the
 line:</para>
 <programlisting><![CDATA[
   #include "vg_profile.c"]]></programlisting>
-<para>in the tool somewhere, and rebuild (you may have to
-<computeroutput>make clean</computeroutput> first).  Then run
-Valgrind with the <computeroutput>--profile=yes</computeroutput>
-option.</para>
 
-<para>The profiler is stack-based; you can register a profiling
-event with
-<computeroutput>VG_(register_profile_event)()</computeroutput>
-and then use the <computeroutput>VGP_PUSHCC</computeroutput> and
-<computeroutput>VGP_POPCC</computeroutput> macros to record time
-spent doing certain things.  New profiling event numbers must not
-overlap with the core profiling event numbers.  See
-<filename>include/pub_tool_profile.h</filename> for details and
-Memcheck for an example.</para>
+<para>in the tool somewhere, and rebuild (you may have to
+<computeroutput>make clean</computeroutput> first).  Then run Valgrind
+with the <option>--profile=yes</option> option.</para>
+
+<para>The profiler is stack-based; you can register a profiling event
+with <function>VG_(register_profile_event)()</function> and then use the
+<computeroutput>VGP_PUSHCC</computeroutput> and
+<computeroutput>VGP_POPCC</computeroutput> macros to record time spent
+doing certain things.  New profiling event numbers must not overlap with
+the core profiling event numbers.  See
+<filename>include/pub_tool_profile.h</filename> for details and Memcheck
+for an example.</para>
 
 </sect2>
 
@@ -1109,11 +909,10 @@
 <title>Other Makefile Hackery</title>
 
 <para>If you add any directories under
-<computeroutput>valgrind/foobar/</computeroutput>, you will need
-to add an appropriate <filename>Makefile.am</filename> to it, and
-add a corresponding entry to the
-<computeroutput>AC_OUTPUT</computeroutput> list in
-<filename>valgrind/configure.in</filename>.</para>
+<computeroutput>valgrind/foobar/</computeroutput>, you will need to add
+an appropriate <filename>Makefile.am</filename> to it, and add a
+corresponding entry to the <computeroutput>AC_OUTPUT</computeroutput>
+list in <filename>valgrind/configure.in</filename>.</para>
 
 <para>If you add any scripts to your tool (see Cachegrind for an
 example) you need to add them to the
@@ -1127,26 +926,24 @@
 <sect2 id="writing-tools.ifacever" xreflabel="Core/tool Interface Versions">
 <title>Core/tool Interface Versions</title>
 
-<para>In order to allow for the core/tool interface to evolve
-over time, Valgrind uses a basic interface versioning system.
-All a tool has to do is use the
-<computeroutput>VG_DETERMINE_INTERFACE_VERSION</computeroutput>
-macro exactly once in its code.  If not, a link error will occur
-when the tool is built.</para>
+<para>In order to allow for the core/tool interface to evolve over time,
+Valgrind uses a basic interface versioning system.  All a tool has to do
+is use the
+<computeroutput>VG_DETERMINE_INTERFACE_VERSION</computeroutput> macro
+exactly once in its code.  If not, a link error will occur when the tool
+is built.</para>
 
-<para>The interface version number has the form X.Y.  Changes in
-Y indicate binary compatible changes.  Changes in X indicate
-binary incompatible changes.  If the core and tool has the same
-major version number X they should work together.  If X doesn't
-match, Valgrind will abort execution with an explanation of the
-problem.</para>
+<para>The interface version number has the form X.Y.  Changes in Y
+indicate binary compatible changes.  Changes in X indicate binary
+incompatible changes.  If the core and tool has the same major version
+number X they should work together.  If X doesn't match, Valgrind will
+abort execution with an explanation of the problem.</para>
 
-<para>This approach was chosen so that if the interface changes
-in the future, old tools won't work and the reason will be
-clearly explained, instead of possibly crashing mysteriously.  We
-have attempted to minimise the potential for binary incompatible
-changes by means such as minimising the use of naked structs in
-the interface.</para>
+<para>This approach was chosen so that if the interface changes in the
+future, old tools won't work and the reason will be clearly explained,
+instead of possibly crashing mysteriously.  We have attempted to
+minimise the potential for binary incompatible changes by means such as
+minimising the use of naked structs in the interface.</para>
 
 </sect2>
 
@@ -1160,45 +957,44 @@
 <para>This whole core/tool business is under active development,
 although it's slowly maturing.</para>
 
-<para>The first consequence of this is that the core/tool
-interface will continue to change in the future; we have no
-intention of freezing it and then regretting the inevitable
-stupidities.  Hopefully most of the future changes will be to add
-new features, hooks, functions, etc, rather than to change old
-ones, which should cause a minimum of trouble for existing tools,
-and we've put some effort into future-proofing the interface to
-avoid binary incompatibility.  But we can't guarantee anything.
-The versioning system should catch any incompatibilities.  Just
-something to be aware of.</para>
+<para>The first consequence of this is that the core/tool interface will
+continue to change in the future; we have no intention of freezing it
+and then regretting the inevitable stupidities.  Hopefully most of the
+future changes will be to add new features, hooks, functions, etc,
+rather than to change old ones, which should cause a minimum of trouble
+for existing tools, and we've put some effort into future-proofing the
+interface to avoid binary incompatibility.  But we can't guarantee
+anything.  The versioning system should catch any incompatibilities.
+Just something to be aware of.</para>
 
-<para>The second consequence of this is that we'd love to hear
-your feedback about it:</para>
+<para>The second consequence of this is that we'd love to hear your
+feedback about it:</para>
 
 <itemizedlist>
- <listitem>
-  <para>If you love it or hate it</para>
- </listitem>
- <listitem>
-  <para>If you find bugs</para>
- </listitem>
- <listitem>
-  <para>If you write a tool</para>
- </listitem>
- <listitem>
-  <para>If you have suggestions for new features, needs,
-  trackable events, functions</para>
- </listitem>
- <listitem>
-  <para>If you have suggestions for making tools easier to
-  write</para>
- </listitem>
- <listitem>
-  <para>If you have suggestions for improving this
-  documentation</para>
- </listitem>
- <listitem>
-  <para>If you don't understand something</para>
- </listitem>
+  <listitem>
+    <para>If you love it or hate it</para>
+  </listitem>
+  <listitem>
+    <para>If you find bugs</para>
+  </listitem>
+  <listitem>
+    <para>If you write a tool</para>
+  </listitem>
+  <listitem>
+    <para>If you have suggestions for new features, needs, trackable
+    events, functions</para>
+  </listitem>
+  <listitem>
+    <para>If you have suggestions for making tools easier to
+    write</para>
+  </listitem>
+  <listitem>
+    <para>If you have suggestions for improving this
+    documentation</para>
+  </listitem>
+  <listitem>
+    <para>If you don't understand something</para>
+  </listitem>
 </itemizedlist>
 
 <para>or anything else!</para>
diff --git a/docs/xml/xml_help.txt b/docs/xml/xml_help.txt
index 41d5ed7..ae71a6f 100644
--- a/docs/xml/xml_help.txt
+++ b/docs/xml/xml_help.txt
@@ -27,7 +27,7 @@
 Important: inside <screen> and <programlisting> blocks, do NOT
 use 'html entities' in your markup, eg. '&lt;' If you *do* use
 them, they will be output verbatim, which is not what you want.
-
+Instead, wrap the content with CDATA tags (see below).
 
 ----------------------------------------------
 
@@ -83,6 +83,8 @@
  </listitem>
 </itemizedlist>
 
+<para>and this is some more text after the list.</para>
+
 
 ----------------------------------------------
 To achieve this:
@@ -116,12 +118,12 @@
 
 ----------------------------------------------
 To achieve this:
-<p>It uses the Eraser algorithm described in:<br />
-<br />
-  Eraser: A Dynamic Data Race Detector for Multithreaded Programs<br />
-  Stefan Savage, Michael Burrows, Patrick Sobalvarro and Thomas Anderson<br />
-  ACM Transactions on Computer Systems, 15(4):391-411<br />
-  November 1997.<br />
+<p>It uses the Eraser algorithm described in:<br/>
+<br/>
+  Eraser: A Dynamic Data Race Detector for Multithreaded Programs<br/>
+  Stefan Savage, Michael Burrows, Patrick Sobalvarro and Thomas Anderson<br/>
+  ACM Transactions on Computer Systems, 15(4):391-411<br/>
+  November 1997.<br/>
 </p>
 
 Do this:
@@ -171,4 +173,4 @@
 
 ----------------------------------------------
 
-Any other helpful hints?  Please tell us.
+Any other helpful hints?  Please add to this.