The valgrind manpage is now auto-generated directly from the
*.xml docs. No more groffly/nroffly editing.
How cool is docbook ?
git-svn-id: svn://svn.valgrind.org/valgrind/trunk@5276 a5019735-40e9-0310-863c-91ae7b9d1cf9
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 &
-Jacqueline Proulx Farrell, ISBN 1-56592-115-1, published by
-O'Reilly & 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 & Jacqueline Proulx
+Farrell, ISBN 1-56592-115-1, published by O'Reilly & 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>