Add a chapter on the reasons why a standalone package was chosen instead of other solutions, and start one about the way autoepatch works.

svn path=/trunk/; revision=24

4 files changed, 154 insertions, 0 deletions

diff --git a/doc/howitworks.docbook b/doc/howitworks.docbook
new file mode 100644
index 0000000..773423e
--- /dev/null
+++ b/doc/howitworks.docbook
@@ -0,0 +1,85 @@
+<chapter id="howitworks">
+<title>How it works</title>
+
+<para>
+In this chapter, we'll try to explain how autoepatch works, and how to
+extend it to patch and fix new problems. The reason to provide a
+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>	
+
+<sect1 id="concepts">
+<title>Concepts</title>
+
+<para>
+There aren't many concepts to describe on autoepatch because it is,
+basically, a simple set of scripts. The definitions that will be given
+here are not even proper "concepts" but this section is intented to
+clear up the terminology used, so that there can't be misunderstanding
+in the next sections and chapters.
+</para>
+
+<variablelist>
+  <varlistentry>
+    <term>patchset</term>
+    <listitem>
+
+    <para>
+    With this term, the documentation will refer to a set of scripts
+    and actual patches, the base element handled by autoepatch itself.
+    Despite the name used seem to limit a patchset to just patches,
+    it's well possible that a patchset has no actual ".patch" file,
+    and instead consist of a single shell script that describes the
+    changes to apply to targets.
+    </para>
+
+    <para>
+    The patchsets can be found in the repository inside the patches
+    directory, or for the installed copy in
+    /usr/share/autoepatch/patches
+      <footnote><para>
+      For alternative prefixes support, see <xref
+      linkend="prefixsupport" />.
+      </para></footnote>
+    </para>
+
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>target</term>
+    <listitem>
+    
+    <para>
+    Under this name we consider a file, or a directory, on which the
+    patchset applies. When the target is a directory, ad the patchset
+    contains actual patches, the paths inside the patches should refer
+    to the direct name of the files starting from the target directory
+    (-p0 option to gpatch); when the target is a file instead, the
+    patch will apply directly over the file. When instead the patchset
+    consist of a function (or a series of functions), the target is
+    passed as parameter, whichever the type it is.
+    </para>
+
+    <para>
+    For more informations about target, look at <xref
+    linkend="writingpatchsets" />.
+    </para>
+    
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="prefixsupport">
+<title>Alternative prefixes support</title>
+
+<para>
+</para>
+
+</sect1>
+
+</chapter>
diff --git a/doc/index.docbook b/doc/index.docbook
index 2793590..dd774dd 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -2,6 +2,9 @@
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   "/usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd" [
  <!ENTITY intro SYSTEM "introduction.docbook">
+ <!ENTITY standalone SYSTEM "standalone.docbook">
+ <!ENTITY howitworks SYSTEM "howitworks.docbook">
+ <!ENTITY writing SYSTEM "writing.docbook">
 ]>
 
 <book>
@@ -11,5 +14,8 @@
 </bookinfo>
 
 &intro;
+&standalone;
+&howitworks;
+&writing;
 
 </book>
diff --git a/doc/standalone.docbook b/doc/standalone.docbook
new file mode 100644
index 0000000..3c8925a
--- /dev/null
+++ b/doc/standalone.docbook
@@ -0,0 +1,56 @@
+<chapter id="standalone">
+<title>Reasoning for a standalone package</title>
+
+<para>
+There are many ways to accomplish the same result. Why the choice was
+done toward a standalone package, that would require a new ebuild, and
+a tarball, and so on? There are a series of reasons why this approach
+is probably the best compromise between the weight of maintainership
+and the ability to do changes without involving all the users at once.
+</para>
+
+<para>
+The current method, of storing both the logic code and the patches on
+the same CVS module used for the portage tree, and thus on the RSync
+servers, is obviously flawed: the eclass has to know the PORTDIR path,
+there's no way to overlay the patches if one has to be changed for
+some reason; the code applies to all users at the same time, as the
+eclass is not versioned for stable and testing branches; the size of
+patches and logic code is restricted, because the size of the CVS tree
+is a main concern, as it already increases with the increase of the
+number of packages available; there's no security because neither the
+eclasses nor the patches are signed or signable (at the current time
+at least).
+</para>
+
+<para>
+Another option would be to ship the logic code with either a
+standalone package or portage and then ship the patches with the RSync
+tree, but this leaves us with the security issue (although it might be
+possible to find a solution to this), and with the size constraints
+that we have with the current solution. Even if it would be possible
+to just recode the logic to allow a separation between testing and
+stable packages, it would be difficult to tell from an emerge --info
+output what the user is using for a given package.
+</para>
+
+<para>
+By using a separate standalone package it is possible to avoid limits
+on the size of both the logic and the patches (that would be on their
+own archive, which could just have a "reasonable size"), it is
+possible to sign the ebuild in the tree, and thus the digest for the
+tarball would be signed too, covering the security issue; there can be
+different versions of the tarball, with different patches, that can
+have different visibility depending on keywords and masked state, and
+it can be easily told by an emerge --info which version of the package
+is used once the profiles are instructed to.
+</para>
+
+<para>
+Probably the worst drawback is that there's the need of a standalone
+repository to contain the logic and the patches, but also this can be
+considered an advantage as that allows us to branch it when moving to
+a stable target.
+</para>
+
+</chapter>
diff --git a/doc/writing.docbook b/doc/writing.docbook
new file mode 100644
index 0000000..96790fb
--- /dev/null
+++ b/doc/writing.docbook
@@ -0,0 +1,7 @@
+<chapter id="writingpatchsets">
+<title>Writing Patchsets</title>
+
+<para>
+</para>
+
+</chapter>