Transform more chapters still.

6 files changed, 163 insertions, 1 deletions

diff --git a/chunk.toc b/chunk.toc
index d73d37f..c52b13a 100644
--- a/chunk.toc
+++ b/chunk.toc
@@ -8,6 +8,10 @@
     <d:tocentry linkend="general-concepts.config-protect"><?dbhtml filename="general-concepts/config-protect/index.html"?></d:tocentry>
     <d:tocentry linkend="general-concepts.cvs-to-rsync"><?dbhtml filename="general-concepts/cvs-to-rsync/index.html"?></d:tocentry>
     <d:tocentry linkend="general-concepts.dependencies"><?dbhtml filename="general-concepts/dependencies/index.html"?></d:tocentry>
+    <d:tocentry linkend="general-concepts.manifest"><?dbhtml filename="general-concepts/manifest/index.html"?></d:tocentry>
+    <d:tocentry linkend="general-concepts.ebuild-revisions"><?dbhtml filename="general-concepts/ebuild-revisions/index.html"?></d:tocentry>
+    <d:tocentry linkend="general-concepts.emerge-and-ebuild"><?dbhtml filename="general-concepts/emerge-and-ebuild/index.html"?></d:tocentry>
+    <d:tocentry linkend="general-concepts.features"><?dbhtml filename="general-concepts/features/index.html"?></d:tocentry>
     </d:tocentry>
   </d:tocentry>
 </toc>
diff --git a/content/general-concepts.xmli b/content/general-concepts.xmli
index 169f0e3..23ccf5d 100644
--- a/content/general-concepts.xmli
+++ b/content/general-concepts.xmli
@@ -17,5 +17,10 @@
   <xi:include parse="xml" href="general-concepts/config-protect.xmli" />
   <xi:include parse="xml" href="general-concepts/cvs-to-rsync.xmli" />
   <xi:include parse="xml" href="general-concepts/dependencies.xmli" />
+  <xi:include parse="xml" href="general-concepts/manifest.xmli" />
+  <!-- <xi:include parse="xml" href="general-concepts/distributed-building.xmli" /> -->
+  <xi:include parse="xml" href="general-concepts/ebuild-revisions.xmli" />
+  <xi:include parse="xml" href="general-concepts/emerge-and-ebuild.xmli" />
+  <xi:include parse="xml" href="general-concepts/features.xmli" />
 
-</part>
\ No newline at end of file
+</part>
diff --git a/content/general-concepts/ebuild-revisions.xmli b/content/general-concepts/ebuild-revisions.xmli
new file mode 100644
index 0000000..1c23f9d
--- /dev/null
+++ b/content/general-concepts/ebuild-revisions.xmli
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+	 xmlns:xl="http://www.w3.org/1999/xlink"
+	 xmlns:xi="http://www.w3.org/2001/XInclude"
+	 xml:id="general-concepts.ebuild-revisions">
+  <title>Ebuild Revisions</title>
+
+  <para>
+    Ebuilds may have a Gentoo revision number associated with them. This is a <filename>-rX</filename> suffix, where
+    <literal>X</literal> is an integer — see <xref linkend="ebuild-writing.file-format.file-naming-rules"/>. This
+    component must only be used for Gentoo changes, not upstream releases. By default, <filename>-r0</filename> is
+    implied.
+  </para>
+
+  <para>
+    Ebuilds should have their <filename>-rX</filename> incremented whenever a change is made which will make a
+    substantial difference to what gets installed by the package — by substantial, we generally mean "something for
+    which many users would want to upgrade". This is usually for bugfixes.
+  </para>
+
+  <para>
+    Simple compile fixes do <emphasis>not</emphasis> warrant a revision bump; this is because they do
+    not affect the installed package for users who already managed to compile it.
+    Small documentation fixes are also usually not grounds for a new revision.
+  </para>
+
+  <para>
+    When doing a revision bump, the usual rules about dropping to <literal>~arch</literal> apply.
+    See <xref linkend="keywording.keywording-on-upgrades"/>.
+  </para>
+</chapter>
diff --git a/content/general-concepts/emerge-and-ebuild.xmli b/content/general-concepts/emerge-and-ebuild.xmli
new file mode 100644
index 0000000..3acd215
--- /dev/null
+++ b/content/general-concepts/emerge-and-ebuild.xmli
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+	 xmlns:xl="http://www.w3.org/1999/xlink"
+	 xmlns:xi="http://www.w3.org/2001/XInclude"
+	 xml:id="general-concepts.emerge-and-ebuild">
+
+  <title>Emerge and Ebuild Relationships</title>
+
+  <figure>
+    <title>
+      How <command>emerge</command>, <command>ebuild</command> and <filename>foo.ebuild</filename> interact
+    </title>
+
+    <mediaobject>
+      <imageobject>
+	<imagedata fileref="/images/emerge-end-ebuild-diagram.png"
+		   align="center" />
+      </imageobject>
+    </mediaobject>
+  </figure>
+
+  <para>
+    The <command>emerge</command> program is a high level wrapper for <filename>ebuild.sh</filename> that handles
+    dependency tracking, safe installs and uninstalls and so on. <command>emerge</command> calls
+    <filename>ebuild.sh</filename> during the build process, which in turn handles the ebuild file and any eclasses. The
+    <literal>${D}</literal> to <literal>${ROOT}</literal> install is handled by <command>emerge</command>.
+  </para>
+
+  <!-- TODO http://dev.gentoo.org/~g2boojum/portage.html -->
+</chapter>
+
diff --git a/content/general-concepts/features.xmli b/content/general-concepts/features.xmli
new file mode 100644
index 0000000..22a01ea
--- /dev/null
+++ b/content/general-concepts/features.xmli
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+	 xmlns:xl="http://www.w3.org/1999/xlink"
+	 xmlns:xi="http://www.w3.org/2001/XInclude"
+	 xml:id="general-concepts.features">
+  <title><varname>FEATURES</varname></title>
+
+
+  <para>
+    The <varname>FEATURES</varname> variable specifies options which affect how Portage operates
+    and how packages are compiled. It is <emphasis>not</emphasis> used for settings which have a
+    substantial effect upon the resulting generated package.
+  </para>
+
+  <table>
+    <title>
+      Relevant <varname>FEATURES</varname> For Developers
+    </title>
+
+    <tgroup cols="2">
+      <thead>
+	<row>
+	  <entry>Feature</entry>
+	  <entry>Explanation</entry>
+	</row>
+      </thead>
+
+      <tbody>
+	<row>
+	  <entry><literal>collision-protect</literal></entry>
+	  <entry>
+	    Raise an error if an installing package attempts to overwrite a file which
+	    is provided by a different package.
+	  </entry>
+	</row>
+	<row>
+	  <entry><literal>noauto</literal></entry>
+	  <entry>When utilizing <command>ebuild</command>, only run the function requested.</entry>
+	</row>
+	<row>
+	  <entry><literal>sandbox</literal></entry>
+	  <entry>Enable the sandbox.</entry>
+	</row>
+	<row>
+	  <entry><literal>sign</literal></entry>
+	  <entry>GPG sign <filename>Manifest</filename> files.</entry>
+	</row>
+	<row>
+	  <entry><literal>strict</literal></entry>
+	  <entry>
+	    Do some extra checks for potentially dangerous situations (eg missing
+	    <filename>Manifest</filename> files).
+	  </entry>
+	</row>
+	<row>
+	  <entry><literal>test</literal></entry>
+	  <entry>Enable the <function>src_test</function> phase.</entry>
+	</row>
+	<row>
+	  <entry><literal>userpriv</literal></entry>
+	  <entry>Drop to non-root privileges for certain phases.</entry>
+	</row>
+	<row>
+	  <entry><literal>usersandbox</literal></entry>
+	  <entry>Enables the sandbox even when running non-privileged.</entry>
+	</row>
+      </tbody>
+    </tgroup>
+  </table>
+</chapter>
diff --git a/content/general-concepts/manifest.xmli b/content/general-concepts/manifest.xmli
new file mode 100644
index 0000000..e6d0bd3
--- /dev/null
+++ b/content/general-concepts/manifest.xmli
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+	 xmlns:xl="http://www.w3.org/1999/xlink"
+	 xmlns:xi="http://www.w3.org/2001/XInclude"
+	 xml:id="general-concepts.manifest">
+
+  <title><filename>Manifest</filename></title>
+
+  <para>
+    In the tree, every package has a <filename>Manifest</filename> file. This file lives in the same directory as the
+    ebuilds for the package. The <filename>Manifest</filename> file contains digests (currently MD5, RMD160 and SHA256)
+    and file size data for every file in the directory and any subdirectories. This is used to verify integrity. The
+    <filename>Manifest</filename> may also be digitally signed.
+  </para>
+
+  <para>
+    To generate the <filename>Manifest</filename>, use <command>ebuild foo.ebuild manifest</command>. When committing,
+    the <filename>Manifest</filename> file must be regenerated to handle any CVS keyword expansion changes —
+    <command>repoman</command> will do this automatically.
+  </para>
+</chapter>