fixed up the introduction

svn path=/trunk/; revision=38

1 files changed, 74 insertions, 88 deletions

diff --git a/doc/introduction.docbook b/doc/introduction.docbook
index 8b85ee5..028d5ce 100644
--- a/doc/introduction.docbook
+++ b/doc/introduction.docbook
@@ -5,81 +5,72 @@
 <title>Motivation</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.
+To make software as portable as possible, GNU developers created the autoconf
+package, which 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.
+However, as software grew more complex, the need arose for a simpler method of
+writing makefiles was added to autoconf: automake. 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 (PIC), 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.
+Unfortunately, given the complexity and 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, let alone
+write, and led to problems and errors in code.
 </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).
+Because of these issues, Gentoo Linux has always had to deal with packages that
+were prepared with broken versions of libtool. Some problems were caused by
+non-portable syntaxes, others by unsafe permissions on temporary files, or
+because libtool didn't support some targets present and supported in Gentoo
+(such as uclibc), or because we want to bend the rules to better suit our needs
+(Gentoo/FreeBSD for example).
 </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.
+To avoid having to patch each and every package with a similar patch to fix
+libtool misbehaviors, the libtool.eclass and elibtoolize functions were created.
+The eclass uses patches present in the ELT-patches directory and tries them one
+by one to fix libtool.
 </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".
+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
+behavior go live directly on all the ebuilds at the same time, so there's no
+proper 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, ...).
+Even though the eclass was created with libtool in mind, there are many use
+cases that could be handled in a similar way, because there are classes of
+packages that suffer from a common problem that can be fixed with a simple
+similar patch. (KDE packages, proper GNU packages, GNOME packages, etc.)
 </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.
+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 arises or a new patch has to
+be added, someone has to first learn about the inner workings of the eclass.
 </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.
+To fix these issues, the autoepatch project was created with the objective to
+provide a simpler implementation for an elibtoolize workalike program,
+disengaged from eclasses and the Portage tree, that could be run from inside
+Portage itself, so that ebuilds don't need to be aware of its presence.
 </para>
 
 </sect1>
@@ -88,55 +79,50 @@ presence anymore.
 <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.
+There are many ways to accomplish the same result. Why create a standalone
+package that would require a new ebuild, a tarball, and so on? This approach is
+probably the best compromise between the weight of maintainership and the
+ability to make 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).
+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. Also, 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. Additionally,the 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. Finally,
+there's no security because neither the eclasses nor the patches are signed or
+signable at this time.
 </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.
+Another option would be to ship the logic code with either a standalone package
+or with Portage and then ship the patches with the rsync tree, but this leaves
+us with the security issue 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.
+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"). Furthermore, 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. Moreover, 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 determined by
+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.
+Probably the worst drawback is that there needs to be a standalone repository
+containing both the logic and the patches, but this can be considered an
+advantage as that allows us to branch it when moving to a stable target.
 </para>
 
 </sect1>