More documentation fixes.

1 files changed, 14 insertions, 10 deletions

diff --git a/deheader.xml b/deheader.xml
index ffb3acf..60a2b79 100644
--- a/deheader.xml
+++ b/deheader.xml
@@ -37,8 +37,12 @@ report on which #includes can be omitted from them; also, what
 standard inclusions may be required for portability. The test, for
 each foo.c or foo.cc or foo.cpp, is simply whether 'rm foo.o; make
 foo.o' returns a zero status (but the build command may be
-overridden). Optionally, with the <option>-r</option> switch, the
-unneeded headers are removed from the sourcefiles.</para>
+overridden).</para>
+
+<para>Optionally, with the <option>-r</option> switch, the
+unneeded headers are removed from the sourcefiles.  Don't use
+this option unless you have your sourcefiles safely under version
+control and can revert!</para>
 
 <para>If a sourcefile argument is a directory, the report is generated
 on all source files beneath it.  Subdirectories beginning with a dot
@@ -80,9 +84,10 @@ see the output from the make and compilation commands.</para>
 
 <para>The last line of the output will be a statistical summary.</para>
 
-<para>Running deheader will leave a lot of binaries in your directory that 
-were compiled in ways possibly not invoked by your normal build process.
-Running "make clean" afterwards is strongly recommended.</para> 
+<para>Running deheader will leave a lot of binaries in your directory
+that were compiled in ways possibly not invoked by your normal build
+process.  Running "make clean" afterwards (or the equivalent under
+whatever build system you are using) is strongly recommended.</para>
 </refsect1>
 
 <refsect1 id='options'><title>OPTIONS</title>
@@ -135,11 +140,11 @@ Takes a Python regular expression.</para>
 
 <refsect1 id='bugs'><title>BUGS</title>
 
-<para>Test-compiling after running with <option>-r</option> will
+<para>Rarely, test-compiling after running with <option>-r</option> will
 sometimes show that this tool removed some headers that are actually
-required for your build. This happens because
+required for your build. This can happen because
 <command>deheader</command> doesn't know about all the strange things
-your build system gets up to, and the problem of analyzing it to
+your build system gets up to, and the problem of analyzing your build to
 understand them would be Turing-complete.  Simply revert the altered
 files and continue.</para>
 
@@ -154,14 +159,13 @@ spot. <command>deheader</command> has an internal table of rules that
 heads off the most common problems by suppressing deletion of headers
 that are required for portability, but your mileage may vary.</para>
 
-<para>Sufficiently perverse C++ can silently invalidate the simple
+<para>Sufficiently perverse C++ can silently invalidate the brute-force
 algorithm this tool uses. Example: if an overloaded function has
 different overloads from two different files, removing one may expose
 the other, changing runtime semantics without a compile-time warning.
 Similarly, removing a later file containing a template specialization
 may lead to undefined behavior from a template defined in an earlier
 file. Use this with caution near such features, and test carefully.</para>
-
 </refsect1>
 
 <refsect1 id='author'><title>AUTHOR</title>