Due to package upgrades (docbook, passivetex), removed some
bug-patches and created some new ones in the stylesheets.
Also tweaked some files to structure the xml properly.
The FAQ and the Quick-Start are now 'articles' inside a book-wrapper,
which is as it should be.
FAQ.xml
- due to various passivetex bug fixes, the faq is now a properly
structured xml qandaset document
quick-start-guide.xml:
manual.xml
- Fixed some passivetex-workaround kludges:
legalnotice -> author
manual-core.xml:
For readability, added '<command>' to varlistentry items
since passivetex (sigh) will no longer indent the para text.
index.xml:
- loads of white-space readability tweaks here and there.
tech-docs.xml
dist-docs.xml
manual.xml
- additional entries to <bookinfo> for compatability with
the rest of the docs.
/docs/Makefile.am
- added stuff to use the new vg-faq2txt.xsl stylesheet
/docs/lib/Makefile.am
- updated to reflect current contents of /docs/lib/
- removed refs to vg-html-single as is never ever used
/docs/lib/vg-fo.xsl
- massively updated to reflect losing old bugs and gaining new ones
/docs/lib/vg-common.xsl
- deleted as only contained two lines common to html and fo,
so not worth the bother of hauling around
/docs/lib/vg-html-chunk.xsl
- added what was in vg-common.xsl
/docs/lib/line-wrap.xsl
/docs/lib/faq2text.xsl
- two new stylesheet files for transforming FAQ.xml to FAQ.txt
git-svn-id: svn://svn.valgrind.org/valgrind/trunk@5234 a5019735-40e9-0310-863c-91ae7b9d1cf9
diff --git a/docs/xml/FAQ.xml b/docs/xml/FAQ.xml
index 6ab229f..dd486a6 100644
--- a/docs/xml/FAQ.xml
+++ b/docs/xml/FAQ.xml
@@ -7,28 +7,34 @@
<bookinfo>
<title>Valgrind FAQ</title>
- <subtitle>Valgrind Frequently Asked Questions</subtitle>
<releaseinfo>&rel-type; &rel-version; &rel-date;</releaseinfo>
- <copyright>
- <year>&vg-lifespan;</year>
- <holder><ulink url="&vg-developers;">Valgrind Developers</ulink></holder>
- </copyright>
- <legalnotice>
- <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para>
- </legalnotice>
+ <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>
-<sect1 id="faq.background" xreflabel="Background">
+<article>
+<title>Valgrind Frequently Asked Questions</title>
+
+
+<!-- FAQ starts here -->
+<qandaset>
+
+
+<!-- Background -->
+<qandadiv id="faq.background" xreflabel="Background">
<title>Background</title>
-<qandaset id="qset.background">
-
<qandaentry id="faq.pronounce">
- <question>
+ <question id="q-pronounce">
<para>How do you pronounce "Valgrind"?</para>
</question>
- <answer>
+ <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>
@@ -38,10 +44,10 @@
</qandaentry>
<qandaentry id="faq.whence">
- <question>
+ <question id="q-whence">
<para>Where does the name "Valgrind" come from?</para>
</question>
- <answer>
+ <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
@@ -60,27 +66,24 @@
</answer>
</qandaentry>
-</qandaset>
-
-</sect1>
+</qandadiv>
-<sect1 id="faq.installing"
- xreflabel="Compiling, installing and configuring">
+
+<!-- Compiling, Installing and Configuring -->
+<qandadiv id="faq.installing" xreflabel="Compiling, installing and configuring">
<title>Compiling, installing and configuring</title>
-<qandaset id="qset.installing">
<qandaentry id="faq.make_dies">
- <question>
+ <question id="q-make_dies">
<para>When I trying building Valgrind, 'make' dies partway with
- an assertion failure, something like this:
+ an assertion failure, something like this:</para>
<screen>
% make: expand.c:489: allocated_variable_append:
Assertion 'current_variable_set_list->next != 0' failed.
</screen>
- </para>
</question>
- <answer>
+ <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
@@ -90,48 +93,43 @@
</answer>
</qandaentry>
-</qandaset>
-</sect1>
+</qandadiv>
-<sect1 id="faq.abort"
- xreflabel="Valgrind aborts unexpectedly">
+<!-- Valgrind aborts unexpectedly -->
+<qandadiv id="faq.abort" xreflabel="Valgrind aborts unexpectedly">
<title>Valgrind aborts unexpectedly</title>
-<qandaset id="qset.abort">
<qandaentry id="faq.exit_errors">
- <question>
+ <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>
- <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 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>
</qandaentry>
<qandaentry id="faq.bugdeath">
- <question>
+ <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>
-
+<screen>% valgrind: vg_malloc2.c:442 (bszW_to_pszW): Assertion 'pszW >= 0' failed.</screen>
</question>
- <answer>
+ <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
@@ -143,15 +141,12 @@
</qandaentry>
<qandaentry id="faq.msgdeath">
- <question>
+ <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>
-
+<screen>% disInstr: unhandled instruction bytes: 0x66 0xF 0x2E 0x5</screen>
</question>
- <answer>
+ <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
@@ -170,54 +165,51 @@
</qandaentry>
<qandaentry id="faq.java">
- <question>
+ <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>
+ just-in-time compiler) under Valgrind but something went wrong.
+ Does Valgrind handle such programs?</para>
</question>
- <answer>
+ <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>
+ 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>
+ 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>
+ 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>
+ <computeroutput>--smc-check=all</computeroutput>, please file a bug
+ report and hopefully we'll be able to fix the problem.</para>
</answer>
</qandaentry>
-</qandaset>
-</sect1>
+</qandadiv>
-<sect1 id="faq.unexpected"
- xreflabel="Valgrind behaves unexpectedly">
+<!-- Valgrind behaves unexpectedly -->
+<qandadiv id="faq.unexpected" xreflabel="Valgrind behaves unexpectedly">
<title>Valgrind behaves unexpectedly</title>
-<qandaset id="qset.unexpected">
<qandaentry id="faq.reports">
- <question>
+ <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>
+ <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
@@ -276,11 +268,11 @@
<qandaentry id="faq.unhelpful">
- <question>
+ <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>
+ <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
@@ -359,36 +351,35 @@
</qandaentry>
<qandaentry id="faq.aliases">
- <question>
+ <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>
+ <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>
-</qandaset>
-</sect1>
+</qandadiv>
-<sect1 id="faq.notfound" xreflabel="Memcheck doesn't find my bug">
+
+<!-- Memcheck doesn't find my bug -->
+<qandadiv id="faq.notfound" xreflabel="Memcheck doesn't find my bug">
<title>Memcheck doesn't find my bug</title>
-<qandaset id="qset.notfound">
<qandaentry id="faq.hiddenbug">
- <question>
+ <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>
+ <answer id="a-hiddenbug">
<para>There are two possible causes of this.</para>
<para>First, by default, Valgrind only traces the top-level process.
@@ -428,7 +419,7 @@
<qandaentry id="faq.overruns">
- <question>
+ <question id="q-overruns">
<para>Why doesn't Memcheck find the array overruns in this program?</para>
<programlisting>
int static[5];
@@ -444,7 +435,7 @@
}
</programlisting>
</question>
- <answer>
+ <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
@@ -452,22 +443,20 @@
</answer>
</qandaentry>
-
-</qandaset>
-</sect1>
+</qandadiv>
-<sect1 id="faq.misc"
- xreflabel="Miscellaneous">
+
+<!-- Miscellaneous -->
+<qandadiv id="faq.misc" xreflabel="Miscellaneous">
<title>Miscellaneous</title>
-<qandaset id="qset.misc">
<qandaentry id="faq.writesupp">
- <question>
+ <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>
+ <answer id="a-writesupp">
<para>Yes! Use the
<computeroutput>--gen-suppressions=yes</computeroutput> feature
to spit out suppressions automatically for you. You can then
@@ -483,12 +472,12 @@
<qandaentry id="faq.deflost">
- <question>
+ <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>
+ <answer id="a-deflost">
<para>The details are in the Memcheck section of the user manual.</para>
<para>In short:</para>
@@ -515,79 +504,85 @@
suppression files. You can ignore suppressed errors.</para>
</listitem>
</itemizedlist>
- </answer>
+ </answer>
</qandaentry>
+</qandadiv>
+
+
+<!-- Further Assistance -->
+<qandadiv id="faq.help" xreflabel="How To Get Further Assistance">
+<title>How To Get Further Assistance</title>
+
+<qandaentry id="e-help">
+
+ <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
+ <ulink url="http://www.valgrind.org/docs/manual.html">Valgrind
+ Documentation</ulink>.</para>
+
+ <para>Read the <ulink url="http://www.valgrind.org/docs/dist.html">Distribution Documents</ulink>.</para>
+
+ <para><ulink url="http://search.gmane.org">Search</ulink> the
+ <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>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>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>
+</answer>
+
+</qandaentry>
+</qandadiv>
+
+
+<!-- FAQ ends here -->
</qandaset>
-</sect1>
+
<!-- template
-<sect1 id="faq."
- xreflabel="xx">
-<title>xx</title>
-<qandaset id="qset.">
+<qandadiv id="faq.installing" xreflabel="Installing">
+<title>Installing</title>
-<qandaentry id="faq.deflost">
- <question>
+<qandaentry id="faq.problem">
+ <question id="q-problem">
<para></para>
</question>
- <answer>
+ <answer id="a-problem">
<para></para>
</answer>
</qandaentry>
-</qandaset>
-</sect1>
+</qandadiv>
-->
-
-
-<sect1 id="faq.help" xreflabel="How To Get Further Assistance">
-<title>How To Get Further Assistance</title>
-
-
-<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 Manual(s):
-<ulink url="http://www.valgrind.org/docs/">Valgrind
-Documentation</ulink>.</para>
-
-<para>Read the <ulink url="http://www.valgrind.org/docs/">Distribution Documents</ulink>.</para>
-
-<para><ulink url="http://search.gmane.org">Search</ulink> the
-<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>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>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>
-
-</sect1>
-
+</article>
</book>