Overhauled the docs. Removed all the HTML files, put in XML files as
converted by Donna. Hooked it into the build system so they are only
built when specifically asked for, and when doing "make dist".
They're not perfect; in particular, there are the following problems:
- The plain-text FAQ should be built from FAQ.xml, but this is not
currently done. (The text FAQ has been left in for now.)
- The PS/PDF building doesn't work -- it fails with an incomprehensible
error message which I haven't yet deciphered.
Nonetheless, I'm putting it in so others can see it.
git-svn-id: svn://svn.valgrind.org/valgrind/trunk@3153 a5019735-40e9-0310-863c-91ae7b9d1cf9
diff --git a/docs/xml/manual-intro.xml b/docs/xml/manual-intro.xml
new file mode 100644
index 0000000..844774b
--- /dev/null
+++ b/docs/xml/manual-intro.xml
@@ -0,0 +1,199 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id="manual-intro" xreflabel="Introduction">
+<title>Introduction</title>
+
+<sect1 id="manual-intro.overview" xreflabel="An Overview of Valgrind">
+<title>An Overview of Valgrind</title>
+
+<para>Valgrind is a flexible system for debugging and profiling
+Linux-x86 executables. The system consists of a core, which
+provides a synthetic x86 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
+summary, these are:</para>
+
+<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>
+
+ <itemizedlist>
+ <listitem>
+ <para>Use of uninitialised memory</para>
+ </listitem>
+ <listitem>
+ <para>Reading/writing memory after it has been
+ free'd</para>
+ </listitem>
+ <listitem>
+ <para>Reading/writing off the end of malloc'd
+ blocks</para>
+ </listitem>
+ <listitem>
+ <para>Reading/writing inappropriate areas on the
+ stack</para>
+ </listitem>
+ <listitem>
+ <para>Memory leaks -- where pointers to malloc'd
+ blocks are lost forever</para>
+ </listitem>
+ <listitem>
+ <para>Mismatched use of malloc/new/new [] vs
+ free/delete/delete []</para>
+ </listitem>
+ <listitem>
+ <para>Overlapping <computeroutput>src</computeroutput> and
+ <computeroutput>dst</computeroutput> pointers in
+ <computeroutput>memcpy()</computeroutput> and related
+ functions</para></listitem> <listitem><para>Some misuses of
+ the POSIX pthreads API</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>
+ </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
+ 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>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>
+ </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 x86
+ instruction.</para>
+
+ <para>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>
+
+ <para>Cachegrind is nicely complemented by Josef
+ Weidendorfer's amazing KCacheGrind visualisation tool
+ (<ulink url="http://kcachegrind.sourceforge.net">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>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>
+ </listitem>
+
+</orderedlist>
+
+
+<para>A number of minor tools (<command>Corecheck</command>,
+<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.</para>
+
+<para>Valgrind is closely tied to details of the CPU, operating
+system and to a less extent, compiler and basic C libraries. This
+makes it difficult to make it portable, so we have chosen at the
+outset to concentrate on what we believe to be a widely used
+platform: Linux on x86s. 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.2 or 2.4 and glibc
+2.1.X, 2.2.X or 2.3.1. This should cover the vast majority of
+modern Linux installations. Note that glibc-2.3.2+, with the
+NPTL (Native Posix Threads Library) package won't work. We hope
+to be able to fix this, but it won't be easy.</para>
+
+<para>Valgrind is licensed under the <xref linkend="license.gpl"/>,
+version 2. 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>
+
+</sect1>
+
+
+<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>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>
+
+</sect1>
+
+</chapter>