Commit the first draft for the documentation, only introduction for now.

svn path=/trunk/; revision=22

2 files changed, 97 insertions, 0 deletions

diff --git a/doc/index.docbook b/doc/index.docbook
new file mode 100644
index 0000000..2793590
--- /dev/null
+++ b/doc/index.docbook
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!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">
+]>
+
+<book>
+
+<bookinfo>
+  <title>autoepatch documentation</title>
+</bookinfo>
+
+&intro;
+
+</book>
diff --git a/doc/introduction.docbook b/doc/introduction.docbook
new file mode 100644
index 0000000..fe95d84
--- /dev/null
+++ b/doc/introduction.docbook
@@ -0,0 +1,82 @@
+<chapter>
+<title>Introduction</title>
+
+<para>
+To make the software as portable as possible, back in the days, GNU
+created the autoconf package, that allowed them to discover the
+features of the compiler and of the C library they were building, so
+they could build the same code over different operating systems and
+platforms.
+</para>
+
+<para>
+When the complexity of the software started to arise, to autoconf it
+was added a software to make simpler writing the makefiles, too, which
+is automake. But one of the most complex problems was writing shared
+libraries (or rather shared objects are they are called in UNIX
+world), because the rules for those might change a lot between
+operating systems and compilers: position independent code, shared
+object names, compiler switches and so on. To resolve this issue, GNU
+libtool was created.
+</para>
+
+<para>
+Unfortunately considered the complexity and the variety of the rules,
+GNU libtool ended up being a very complex piece of software, and to
+make it worse, it had to be written in a portable sh subset, which can
+be difficult to read, not only to write, and then problems and errors
+in code aroused, obviously.
+</para>
+
+<para>
+For this reason, Gentoo Linux had always to cope with many problems
+that were caused by software whose package was prepared with a broken
+version of GNU libtool... some problems were caused by simple
+non-portable syntaxes, others by unsafe permissions on temporary
+files, or because libtool didn't support some targets present and
+supported in Gentoo (like uClibc), or again because we want to
+bend the default rules to suit our needs better (for Gentoo/FreeBSD
+for instance).
+</para>
+
+<para>
+To avoid having to patch all and every package with a similar patch to
+fix libtool misbehavious, libtool.eclass and elibtoolize functions
+were created. This eclass uses the patches present in the ELT-patches
+directory, trying them one by one, to fix libtool for what we need.
+</para>
+
+<para>
+Unfortunately there are issues with this design: we're bound to the
+portage tree for the patchsets, there's a logical size limit because
+we're using the Portage Tree itself as a patch repository, and the
+changes to patches and behaviour go live directly on all the ebuilds
+at the same time, so there's no prope way to get a patch in "testing".
+</para>
+
+<para>
+And even if the eclass was created thinking about libtool, there are
+many use cases that could be handled in a similar way, because there
+are classes of packages that simply suffer from a common problem that
+can be fixed with a simple similar patch (KDE packages, proper GNU
+packages, GNOME packages, ...).
+</para>
+
+<para>
+Beside the technical issues, there are also a few maintainership
+issues, as the libtool eclass is pretty complex, and there is no
+maintainer currently appointed to take care of it; this means that if a
+problem arise or a new patch has to be added, someone has to try to
+get a clue about the eclass to start with.
+</para>
+
+<para>
+To fix these issue and to improve the points where there's space to
+improve, the autoepatch project started, with the objective to provide
+a simpler implementation for an elibtoolize workalike program,
+disengaged from eclasses and the portage tree, that could be hooked up
+inside Portage itself, so that ebuilds haven't to be aware of its
+presence anymore.
+</para>
+
+</chapter>