Add a section about requirements

svn path=/trunk/; revision=26

1 files changed, 63 insertions, 1 deletions

diff --git a/doc/howitworks.docbook b/doc/howitworks.docbook
index cc1477a..c4f3123 100644
--- a/doc/howitworks.docbook
+++ b/doc/howitworks.docbook
@@ -8,7 +8,69 @@ throughout documentation about this is to make the maintainership of
 autoepatch simpler, so that if the developers currently involved in
 its writing would not be available, newcomers won't have to read all
 the code to find how it actually works.
-</para>	
+</para>
+
+<sect1 id="requirements">
+<title>Requirements</title>
+
+<para>
+Being a package that is going to be in the system set, and used by
+every user as a Portage component, autoepatch needs to have the
+minimum impact over the dependencies of that set. For this reason, the
+script is a bash script. As the targets for Gentoo software are less
+wide than the general GNU or Open Source targets, there's no need to
+use a portable subset of sh (as we already consider bash present), and
+it can depend on a few GNU tools, or at least tools that can support
+an acceptable subset of GNU parameters.
+</para>
+
+<para>
+First of all, as most of the patchsets are expected to be actual patch
+files, the patch(1) command is supposed to be coming from GNU
+project. While FreeBSD uses Larry Wall's patch(1) command, that
+supports most of the options that GNU patch supports, there are some
+tricky behaviours on fuzzyness of patches. If patch(1) is not a
+GNU-compatible implementation, you can provide a GNU patch command
+named <emphasis>gpatch</emphasis> that will be prioritised over the
+normal patch(1).
+</para>
+
+<para>
+Another command on which behaviour the script relies more than just a
+bit is find(1). Considering the frequency of execution of the script
+itself, and thus of the targetting logic, the script tries to reduce
+as much as possible the processes spawn, so instead of using xargs(1)
+command to transform the find(1) output to input arguments to other
+commands, autoepatch relies on find(1) to support the <emphasis>-exec
+cmd {} +</emphasis> syntax.
+</para>
+
+<para>
+Luckily not only GNU findutils, but also FreeBSD, Darwin and NetBSD find(1)
+implementations support that syntax. OpenBSD on the other hand does
+not, so to allow autoepatch to work on that operating system, a
+special handling for the find command was written: by replacing the
+string <emphasis>@findcmd@</emphasis> with the path, or the name, of a
+compatible find implementation (most likely GNU find), you can tell
+autoepatch to run an alternative command.
+</para>
+
+<para>
+As there is often the need to get a temporary file, either for log or
+debugging purposes, or to store intermediate results, the mktemp
+utility is also required. Unfortunately, the mktemp utility found on
+most Linux implementations (Gentoo Linux included) comes from
+debianutils package, and has a syntax incompatible with the original
+BSD mktemp utility. As the autoepatch script does not get the USERLAND
+variable from Portage, and tries to be entirely transparent to that
+matter, the choice between the two implementations is done at runtime
+by checking the outcome of calling <emphasis>mktemp -V</emphasis>; on
+Debian implementation, this reports the version of the command itself,
+while it simply fails on BSD implementation. The emktemp wrapper is
+picked up from eutils.eclass.
+</para>
+
+</sect1>
 
 <sect1 id="concepts">
 <title>Concepts</title>