path: root/doc
diff options
Diffstat (limited to 'doc')
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 id="whitespaces">
+<title>Whitespaces handling and safety</title>
+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.
+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).
+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>
+ 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>
<sect1 id="prefixsupport">
<title>Alternative prefixes support</title>