Start documenting the functions in the patchset's script.

svn path=/trunk/; revision=32

1 files changed, 57 insertions, 0 deletions

diff --git a/doc/writing.docbook b/doc/writing.docbook
index f33b293..70e09d9 100644
--- a/doc/writing.docbook
+++ b/doc/writing.docbook
@@ -19,6 +19,63 @@ the files to patch, what kind of patchset it is, and whether to fail
 or not if the patching is not completed as intended.
 </para>
 
+<para>
+To facilitate writing new patchsets, the names of the functions that
+are defined into the patchset's script are standardised, so that the
+parameters they get and the result they echo out can be relied upon
+and used by autoepatch safely.
+</para>
+
+<variablelist>
+  <varlistentry>
+    <term>patch_targets</term>
+    <listitem>
+
+    <para>
+    This function is the basis to start writing a new patchset, it is
+    used to identify where the patches are gonna be applied. The
+    results are simply returned on the standard output, one per
+    line. This function is supposed to check if the patch should or
+    should not be applied over a file or a directory, by grepping, if
+    needed, for key phrases that would show if the patch is needed or
+    not.
+    </para>
+
+    <para>
+    This function is not supposed to check for the applicability of
+    the patch on the current system. The reason for this is that it's
+    way simpler to test all patchsets every time, so that if errors
+    are added to the patchset, they can be fixed immediately.
+    </para>
+
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>patch_required</term>
+    <listitem>
+
+    <para>
+    This function is called in the case the patchset failed to apply
+    entirely; it is supposed to return 0 (truth value) if the patch is
+    important, and autoepatch has to fail if it's not applied (and
+    thus stop the merge process), or 1 (untruth value) if the patch is
+    optional and/or it's not of first important for the current setup.
+    </para>
+
+    <para>
+    The reason to have this function is that some patches might be only
+    needed on some targets (for instance Gentoo/FreeBSD, or uClibc or
+    Darwin systems), or only in some situations (newer autotools,
+    newer glibc or linux-headers), and for the rest of the cases, it's
+    just an assurance and a testing purpose to apply the patch on
+    every use. So the failure on autoepatch, when a patchset fails to
+    apply, is entirely decided by the value returned by this function.
+    </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
 </sect1>
 
 </chapter>