Make standalone just a subsection of Introduction.

svn path=/trunk/; revision=28

3 files changed, 62 insertions, 58 deletions

diff --git a/doc/index.docbook b/doc/index.docbook
index dd774dd..76602f0 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -2,7 +2,6 @@
 <!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">
 ]>
@@ -14,7 +13,6 @@
 </bookinfo>
 
 &intro;
-&standalone;
 &howitworks;
 &writing;
 
diff --git a/doc/introduction.docbook b/doc/introduction.docbook
index 865f071..8b85ee5 100644
--- a/doc/introduction.docbook
+++ b/doc/introduction.docbook
@@ -1,6 +1,9 @@
 <chapter id="introduction">
 <title>Introduction</title>
 
+<sect1 id="motivation">
+<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
@@ -79,4 +82,63 @@ inside Portage itself, so that ebuilds haven't to be aware of its
 presence anymore.
 </para>
 
+</sect1>
+
+<sect1 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>
+
+</sect1>
+
 </chapter>
diff --git a/doc/standalone.docbook b/doc/standalone.docbook
deleted file mode 100644
index 3c8925a..0000000
--- a/doc/standalone.docbook
+++ /dev/null
@@ -1,56 +0,0 @@
-<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>