Add some documentation about whitespaces in autoepatch.

svn path=/trunk/; revision=29

1 files changed, 40 insertions, 0 deletions

diff --git a/doc/howitworks.docbook b/doc/howitworks.docbook
index abb25fb..4472531 100644
--- a/doc/howitworks.docbook
+++ b/doc/howitworks.docbook
@@ -144,6 +144,46 @@ in the next sections and chapters.
 
 </sect1>
 
+<sect1 id="whitespaces">
+<title>Whitespaces handling and safety</title>
+
+<para>
+While there are currently some limitations in ebuilds and in Portage
+code that disallow using paths with spaces for important directories
+like the merge root, the temporary directory and the portage tree
+directory, autoepatch was supposed not to break even if all of them had
+all kind of special characters. Unfortunately this is not always
+possible, because of limitations in the tools and the language used.
+</para>
+
+<para>
+The biggest limitation is provided by bash itself: variables cannot
+contain the NULL character, which means that the targets cannot be
+passed with the output of find -print0 or grep -Z, so the targets
+have to be separated by the \n sequence (new line).
+</para>
+
+<para>
+To try minimising the possibility of problems during piping throught
+different commands (find, grep and so on), it is suggested to use the
+option <emphasis>find $dir -exec cmd {} +</emphasis> rather than using
+-print and xargs (this also avoids one process spawn), and if you need
+to pass the result of grep -l, also add the --null parameter.
+</para>
+
+<warning>
+  <para>
+  For reasons far from our understanding, FreeBSD people decided to
+  use the -Z option to GNU grep to support running grep over
+  gzip-compressed files. For compatibility and portability, rather
+  than using the -Z option, you should use the --null option in
+  autoepatch patchsets, which would behave consistently on both Linux
+  and non-Linux systems.
+  </para>
+</warning>
+
+</sect1>
+
 <sect1 id="prefixsupport">
 <title>Alternative prefixes support</title>