More goodies; change syntax highlighting mode within quotes for ebuilds.

git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/devmanual/trunk@5 176d3534-300d-0410-8db8-84e73ed771c3

12 files changed, 1246 insertions, 71 deletions

diff --git a/devbook.xsl b/devbook.xsl
index f30096b..c415e02 100644
--- a/devbook.xsl
+++ b/devbook.xsl
@@ -23,18 +23,22 @@
 <xsl:variable name="commentChar">#</xsl:variable>
   <xsl:template name="highlight-subtokenate">
     <xsl:param name="data"/>
+    <xsl:param name="nokeywords"/>
+
     <xsl:choose>
       <!-- Tokenate variables in the form ${...} -->
       <xsl:when test="contains($data, '${')">
         <!-- Tokenate anything before it... -->
         <xsl:call-template name="highlight-subtokenate">
           <xsl:with-param name="data" select="substring-before($data, $variable-start)"/>
+          <xsl:with-param name="nokeywords" select="$nokeywords"/>
         </xsl:call-template>
         <xsl:variable name="data-slack" select="substring-after($data, $variable-start)"/>
         <xsl:variable name="variable-name" select="substring-before($data-slack, $variable-end)"/>
         <span class="Identifier">${<xsl:value-of select="$variable-name"/>}</span>
         <xsl:call-template name="highlight-subtokenate">
           <xsl:with-param name="data" select="substring-after($data, $variable-end)"/>
+          <xsl:with-param name="nokeywords" select="$nokeywords"/>
         </xsl:call-template>
       </xsl:when>
 
@@ -48,48 +52,27 @@
 	</xsl:call-template>
       </xsl:when>
 
-      <xsl:when test="substring($data, string-length($data)) = ')'">
+      <xsl:when test="substring($data, string-length($data)) = ')' and not(contains($data, '('))">
         <xsl:call-template name="highlight-subtokenate">
           <xsl:with-param name="data" select="substring($data, 1, string-length($data)-1)"/>
         </xsl:call-template>
         <span class="PreProc">)</span>
       </xsl:when>
 
-      <!-- This must go before the other quote matchers -->
-      <xsl:when test="$data = '&quot;'">
-	<span class="Statement">&quot;</span>
-      </xsl:when>
-
-      <xsl:when test="substring($data, 1, 1) = '&quot;' and substring($data, string-length($data)) = '&quot;'">
-	<span class="Statement">&quot;</span>
-	<xsl:call-template name="highlight-subtokenate">
-          <xsl:with-param name="data" select="substring($data, 2, string-length($data)-2)"/>
-        </xsl:call-template>
-	<span class="Statement">&quot;</span>
-      </xsl:when>
-
-      <xsl:when test="substring($data, 1, 1) = '&quot;'">
-	<span class="Statement">&quot;</span>
-        <xsl:call-template name="highlight-subtokenate">
-          <xsl:with-param name="data" select="substring($data, 2)"/>
-        </xsl:call-template>
+      <xsl:when test="substring($data, 1, 1) = $qvariable-start">
+	<span class="Identifier">$<xsl:value-of select="substring($data, 2)"/></span>
       </xsl:when>
 
-      <xsl:when test="substring($data, string-length($data)) = '&quot;'">
-        <xsl:call-template name="highlight-subtokenate">
-          <xsl:with-param name="data" select="substring($data, 0, string-length($data))"/>
-        </xsl:call-template>
-	<span class="Statement">&quot;</span>
+      <xsl:when test="$nokeywords">
+        <xsl:value-of select="$data"/>
       </xsl:when>
 
-      <xsl:when test="substring($data, 1, 1) = $qvariable-start">
-	<span class="Identifier">$<xsl:value-of select="substring($data, 2)"/></span>
-      </xsl:when>
       <!-- Functioney highlighing -->
-
       <!-- sh grammar -->
       <xsl:when test="$data = ';' or $data = 'if' or $data = 'then' or $data = 'fi' or $data = '-ge' or $data = '-lt' or $data = '-le' or
-                      $data = '-gt' or $data = 'elif' or $data = 'else' or $data = 'eval' or $data = 'unset'">
+                      $data = '-gt' or $data = 'elif' or $data = 'else' or $data = 'eval' or $data = 'unset' or $data = 'sed' or
+                      $data = 'rm' or $data = 'cat' or $data = '[[' or $data = ']]' or $data = 'while' or $data = 'do' or $data = 'read' or
+                      $data = 'done' or $data = 'make' or $data = 'echo' or $data = 'cd'">
 	<span class="Statement"><xsl:value-of select="$data"/></span>
       </xsl:when>
 
@@ -105,7 +88,7 @@
 		      $data = 'prepallstrip' or $data = 'has' or $data = 'unpack' or $data = 'dopython' or $data = 'dosed' or $data = 'into' or
 		      $data = 'doinitd' or $data = 'doconfd' or $data = 'doenvd' or $data = 'dojar' or $data = 'domo' or $data = 'dodir' or
 		      $data = 'ebegin' or $data = 'eend' or $data = 'newconfd' or $data = 'newdoc' or $data = 'newenvd' or $data = 'newinitd' or
-		      $data = 'newlib$dataa' or $data = 'newlib$dataso' or $data = 'hasq' or $data = 'hasv' or $data = 'useq' or $data = 'usev'">
+		      $data = 'newlib.a' or $data = 'newlib.so' or $data = 'hasq' or $data = 'hasv' or $data = 'useq' or $data = 'usev'">
 	<span class="Statement"><xsl:value-of select="$data"/></span>
       </xsl:when>
 
@@ -331,24 +314,40 @@
     <xsl:param name="data"/>
 
     <!-- Only tokenize spaces, this way we preserve tabs. -->
-    <xsl:variable name="tokenizedData" select="str:tokenize_plasmaroo($data, ' ')"/>
+    <xsl:variable name="tokenizedData" select="str:tokenize_plasmaroo($data, '&quot; ')"/>
 
     <!-- Scan for comments. If a comment is found then this is a positional
          index that is non-zero that refers to the last node that is not
          a comment. -->
-    <xsl:variable name="commentSeeker" select="count(str:tokenize_plasmaroo(substring-before($data, $commentChar)))"/>
+    <xsl:variable name="commentSeeker" select="count(str:tokenize_plasmaroo(substring-before($data, concat(' ', $commentChar))))"/>
 
+    <!-- Scan for quotes... -->
     <xsl:for-each select="exslt:node-set($tokenizedData)">
     <xsl:variable name="myPos" select="position()"/>
+    <xsl:variable name="quotePos" select="count(../*[@delimiter='&quot;' and position() &lt; $myPos])"/>
+    
     <xsl:choose>
       <!-- See if we should be processing comments by now; we need to test for
 	   two possible cases:	* commentSeeker != 0 (so we have a comment), or,
 				* the first token is a "#" -->
-      <xsl:when test="($commentSeeker != 0 and position() > $commentSeeker) or substring(../*[position()=1], 1, 1) = $commentChar
-                      or . = $commentChar">
+      <xsl:when test="($commentSeeker != 0 and position() > $commentSeeker) or substring(../*[position()=1], 1, 1) = $commentChar or
+                      . = $commentChar">
         <span class="Comment"><xsl:value-of select="."/></span>
       </xsl:when>
 
+      <!-- Highlight a quote -->
+      <xsl:when test=". = '&quot;'">
+	<span class="Statement">&quot;</span>
+      </xsl:when>
+
+      <!-- If we're inside quotes stop here -->
+      <xsl:when test="$quotePos mod 2 != 0">
+        <xsl:call-template name="highlight-subtokenate">
+          <xsl:with-param name="data"><xsl:value-of select="."/></xsl:with-param>
+          <xsl:with-param name="nokeywords">True</xsl:with-param>
+        </xsl:call-template>
+      </xsl:when>
+
       <!-- Highlight functions;
 		@token_regexp = [^\w]+()
 		@pos = 1 -->
@@ -370,7 +369,7 @@
 	<span class="PreProc"><xsl:value-of select="."/></span>
       </xsl:when>
 
-      <xsl:when test=". = '||' or . = '&amp;&amp;'">
+      <xsl:when test=". = '||' or . = '&amp;&amp;' or . = '|'">
 	<span class="Statement"><xsl:value-of select="."/></span>
       </xsl:when>
 
@@ -418,6 +417,55 @@
   <pre><xsl:apply-templates/></pre>
   </xsl:template>
 
+  <!-- Tables -->
+  <!-- From the Gentoo GuideXML Stylesheet -->
+  <xsl:template match="table">
+  <table><xsl:apply-templates/></table>
+  </xsl:template>
+
+  <xsl:template match="tr">
+  <tr><xsl:apply-templates/></tr>
+  </xsl:template>
+
+  <xsl:template match="tcolumn">
+  <col width="{@width}"/>
+  </xsl:template>
+
+  <!-- Table Item -->
+  <xsl:template match="ti">
+    <td class="tableinfo">
+      <xsl:if test="@colspan">
+	<xsl:attribute name="colspan"><xsl:value-of select="@colspan"/></xsl:attribute>
+      </xsl:if>
+      <xsl:if test="@rowspan">
+	<xsl:attribute name="rowspan"><xsl:value-of select="@rowspan"/></xsl:attribute>
+      </xsl:if>
+      <xsl:apply-templates/>
+    </td>
+  </xsl:template>
+
+  <!-- Table Heading -->
+  <xsl:template match="th">
+    <td class="infohead">
+      <xsl:if test="@colspan">
+	<xsl:attribute name="colspan"><xsl:value-of select="@colspan"/></xsl:attribute>
+	<!-- Center only when item spans several columns as
+             centering all <th> might disrupt some pages.
+             We might want to use a plain html <th> tag later.
+             Tip: to center a single-cell title, use <th colspan="1">
+	  -->
+	<xsl:attribute name="style">text-align:center</xsl:attribute>
+      </xsl:if>
+      <xsl:if test="@rowspan">
+	<xsl:attribute name="rowspan"><xsl:value-of select="@rowspan"/></xsl:attribute>
+      </xsl:if>
+      <b>
+	<xsl:apply-templates/>
+      </b>
+    </td>
+  </xsl:template>
+  <!-- End Table Jojo -->
+
   <!-- FIXME: Handle lang=... -->
   <xsl:template match="codesample">
       <pre><span class="Constant">
@@ -519,6 +567,36 @@
     <code class="docutils literal"><span class="pre"><xsl:apply-templates/></span></code>
   </xsl:template>
 
+  <!-- TOC Tree -->
+  <xsl:template match="contentsTree" name="contentsTree">
+    <xsl:param name="depth" select="0"/>
+    <xsl:param name="maxdepth">
+      <xsl:choose>
+	<xsl:when test="@maxdepth"><xsl:value-of select="@maxdepth"/></xsl:when>
+	<xsl:otherwise>0</xsl:otherwise>
+      </xsl:choose>
+    </xsl:param>
+    <xsl:param name="path" select="/guide/@self"/>
+    <xsl:param name="path_rel"/>
+
+    <xsl:variable name="doc_self" select="concat($path, 'text.xml')"/>
+    <xsl:if test="count(document($doc_self)/guide/include) &gt; 0 and ($depth &lt; $maxdepth or $maxdepth = '0')">
+    <ul>
+    <xsl:for-each select="document($doc_self)/guide/include">
+      <li>
+	<a class="reference" href="{concat($path_rel, @href, 'index.html')}"><xsl:value-of select="document(concat($path, @href, 'text.xml'))/guide/chapter[1]/title"/></a>
+	<xsl:call-template name="contentsTree">
+	  <xsl:with-param name="depth" select="$depth + 1"/>
+	  <xsl:with-param name="maxdepth" select="$maxdepth"/>
+	  <xsl:with-param name="path" select="concat($path, @href)"/>
+	  <xsl:with-param name="path_rel" select="concat($path_rel, @href)"/>
+	</xsl:call-template>
+      </li>
+    </xsl:for-each>
+    </ul>
+    </xsl:if>
+  </xsl:template>
+
   <xsl:template match="/">
     <html lang="en-GB" xml:lang="en-GB" xmlns="http://www.w3.org/1999/xhtml">
     <head>
@@ -667,35 +745,6 @@
     </xsl:choose>
   </xsl:template>
 
-  <xsl:template match="contentsTree" name="contentsTree">
-    <xsl:param name="depth" select="0"/>
-    <xsl:param name="maxdepth">
-      <xsl:choose>
-	<xsl:when test="@maxdepth"><xsl:value-of select="@maxdepth"/></xsl:when>
-	<xsl:otherwise>0</xsl:otherwise>
-      </xsl:choose>
-    </xsl:param>
-    <xsl:param name="path" select="/guide/@self"/>
-    <xsl:param name="path_rel"/>
-
-    <xsl:variable name="doc_self" select="concat($path, 'text.xml')"/>
-    <xsl:if test="count(document($doc_self)/guide/include) &gt; 0 and ($depth &lt; $maxdepth or $maxdepth = '0')">
-    <ul>
-    <xsl:for-each select="document($doc_self)/guide/include">
-      <li>
-	<a class="reference" href="{concat($path_rel, @href, 'index.html')}"><xsl:value-of select="document(concat($path, @href, 'text.xml'))/guide/chapter[1]/title"/></a>
-	<xsl:call-template name="contentsTree">
-	  <xsl:with-param name="depth" select="$depth + 1"/>
-	  <xsl:with-param name="maxdepth" select="$maxdepth"/>
-	  <xsl:with-param name="path" select="concat($path, @href)"/>
-	  <xsl:with-param name="path_rel" select="concat($path_rel, @href)"/>
-	</xsl:call-template>
-      </li>
-    </xsl:for-each>
-    </ul>
-    </xsl:if>
-  </xsl:template>
-
   <xsl:template name="getLastNode">
     <!-- This function recurses forward down nodes stopping at the very last include... -->
     <xsl:param name="root"/>
diff --git a/ebuild-writing/error-handling/text.xml b/ebuild-writing/error-handling/text.xml
new file mode 100644
index 0000000..7931311
--- /dev/null
+++ b/ebuild-writing/error-handling/text.xml
@@ -0,0 +1,134 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/error-handling/">
+<chapter>
+<title>Error Handling</title>
+
+<section>
+<title>Importance of Error Handling</title>
+<body>
+
+<p>
+Decent error handling is important because:
+</p>
+
+<ul>
+  <li>
+  Errors must be detected <e>before</e> portage tries to install a broken or
+  incomplete package onto the live filesystem. If build failures aren't caught,
+  a working package could be unmerged and replaced with nothing.
+  </li>
+  <li>
+  When receiving bug reports, it is a lot easier to figure out what went wrong
+  if you know exactly which call caused the error, rather than just knowing
+  that, say, something somewhere in <c>src_compile</c> broke.
+  </li>
+  <li>
+  Good error handling and notification can help cut down on the number of bug
+  reports received for a package.
+  </li>
+</ul>
+
+</body>
+</section>
+
+<section>
+<title>The <c>die</c> Function</title>
+<body>
+
+<p>
+The <c>die</c> function should be used to indicate a fatal error and abort the
+build. Its parameters should be the message to display.
+</p>
+
+<p>
+Although <c>die</c> will work with no parameters, a short message should always be
+provided to ease error identification. This is especially important when a
+function can die in multiple places.
+</p>
+
+<p>
+Some portage-provided functions will automatically die upon failure. Others will
+not. It is safe to omit the <c>|| die</c> after a call to <c>epatch</c>, but not
+<c>econf</c> or <c>emake</c>.
+</p>
+
+<p>
+Sometimes displaying additional error information beforehand can be useful. Use
+<c>eerror</c> to do this. See `Messages`_.
+</p>
+
+</body>
+</section>
+
+<section>
+<title><c>die</c> and Subshells</title>
+<body>
+
+<warning>
+<c>die</c> <b>will not work in a subshell</b>.
+</warning>
+
+<p>
+The following code will not work as expected, since the <c>die</c> is inside a
+subshell:
+</p>
+
+<codesample lang="ebuild">
+[[ -f foorc ]] &amp;&amp; ( update_foorc || die "Couldn't update foorc!" )
+</codesample>
+
+<p>
+The correct way to rewrite this is to use an <c>if</c> block:
+</p>
+
+<codesample lang="ebuild">
+if [[ -f foorc ]] ; then
+    update_foorc || die "Couldn't update foorc!"
+fi
+</codesample>
+
+<p>
+When using pipes, a subshell is introduced, so the following is unsafe:
+</p>
+
+<codesample lang="ebuild">
+cat list | while read file ; do epatch ${file} ; done
+</codesample>
+
+<p>
+Using input redirection (see `Abuse of cat`_) avoids this problem:
+</p>
+
+<codesample lang="ebuild">
+while read file ; do epatch ${file} ; done &lt; list
+</codesample>
+
+</body>
+</section>
+
+<section>
+<title>The <c>assert</c> Function and <c>$PIPESTATUS</c></title>
+<body>
+
+<p>
+When using pipes, simple conditionals and tests upon <c>$?</c> will not correctly
+detect errors occurring in anything except the final command in the chain. To get
+around this, <c>bash</c> provides the <c>$PIPESTATUS</c> variable, and portage
+provides the <c>assert</c> function to check this variable.
+</p>
+
+<codesample lang="ebuild">
+bunzip2 ${DISTDIR}/${VIM_RUNTIME_SNAP} | tar xf
+assert
+</codesample>
+
+<p>
+If you need the gory details of <c>$PIPESTATUS</c>, see the bash manpage. Most of the
+time, <c>assert</c> is enough.
+</p>
+
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/file-format/text.xml b/ebuild-writing/file-format/text.xml
new file mode 100644
index 0000000..499a60c
--- /dev/null
+++ b/ebuild-writing/file-format/text.xml
@@ -0,0 +1,150 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/file-format/">
+<chapter>
+<title>Ebuild File Format</title>
+
+<body>
+<p>
+An ebuild is a <c>bash</c> script which is executed within a special environment.
+Files should be simple text files with a <c>.ebuild</c> extension.
+</p>
+</body>
+
+<section>
+<title>File Naming Rules</title>
+<body>
+
+<p>
+An ebuild should be named in the form <c>name-version.ebuild</c>.
+</p>
+
+<p>
+The name section should contain only lowercase non-accented letters, the digits
+0-9, hyphens, underscores and plus characters. Uppercase characters are strongly
+discouraged, but technically valid.
+</p>
+
+<note>
+This is the same as `IEEE1003.1-2004-3.276`_, with the addition of the plus
+character to keep GTK+ and friends happy.
+</note>
+
+<p>
+The version section is more complicated. It consists of one or more numbers
+separated by full stop (or period, or dot, or decimal point) characters (eg
+<c>1.2.3</c>, <c>20050108</c>). The final number may have a single letter following it
+(e.g. <c>1.2b</c>). This letter should not be used to indicate 'beta' status --
+portage treats <c>1.2b</c> as being a later version than <c>1.2</c> or <c>1.2a</c>.
+</p>
+
+<p>
+There can be a suffix to version indicating the kind of release. In the following table,
+what portage considers to be the 'lowest' version comes first.
+</p>
+
+<table>
+  <tr>
+    <th>Suffix</th>
+    <th>Meaning</th>
+  </tr>
+  <tr>
+    <ti><c>_alpha</c></ti>
+    <ti>Alpha release (earliest)</ti>
+  </tr>
+  <tr>
+    <ti><c>_beta</c></ti>
+    <ti>Beta release</ti>
+  </tr>
+  <tr>
+    <ti><c>_pre</c></ti>
+    <ti>Pre release</ti>
+  </tr>
+  <tr>
+    <ti><c>_rc</c></ti>
+    <ti>Release candidate</ti>
+  </tr>
+  <tr>
+    <ti>(no suffix)</ti>
+    <ti>Normal release</ti>
+  </tr>
+  <tr>
+    <ti>_p</ti>
+    <ti>Patch level</ti>
+  </tr>
+</table>
+
+<p>
+Any of these suffixes may be followed by a non-zero positive integer.
+</p>
+
+<p>
+Finally, version may have a Gentoo revision number in the form <c>-r1</c>. The initial
+Gentoo version should have no revision suffix, the first revision should be
+<c>-r1</c>, the second <c>-r2</c> and so on. See `Ebuild Revisions`_.
+</p>
+
+<p>
+Overall, this gives us a filename like <c>libfoo-1.2.5b_pre5-r2.ebuild</c>.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Ebuild Header</title>
+<body>
+
+<p>
+All ebuilds committed to the tree should have a three line header immediately at
+the start indicating copyright. This must be an exact copy of the contents of
+<c>$(portageq portdir)/header.txt</c>. Ensure that the <c>$Header: $</c> line is not
+modified manually -- CVS will handle this line specially.
+</p>
+
+<codesample lang="ebuild">
+# Copyright 1999-2006 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
+</codesample>
+
+</body>
+</section>
+
+<section>
+<title>Indenting and Whitespace</title>
+<body>
+
+<p>
+Indenting in ebuilds must be done with tabs, one tab per indent
+level. Each tab represents four spaces. Tabs should only be used for
+indenting, never inside strings.
+</p>
+
+<p>
+Avoid trailing whitespace: repoman will warn you about this if your
+ebuild contains trailing or leading whitespace (whitespace instead of
+tabs for indentation) when you commit.
+</p>
+
+<p>
+Where possible, try to keep lines no wider than 80 positions. A
+'position' is generally the same as a character -- tabs are four
+positions wide, and multibyte characters are just one position wide.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Character Set</title>
+<body>
+<p>
+All ebuilds (and eclasses, metadata files and ChangeLogs) must use the
+UTF-8 character set. See `GLEP 31`_ for details, and `glep31check`_
+for an easy way of checking for validity.
+</p>
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/messages/text.xml b/ebuild-writing/messages/text.xml
new file mode 100644
index 0000000..bcb002e
--- /dev/null
+++ b/ebuild-writing/messages/text.xml
@@ -0,0 +1,149 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/users-and-groups/">
+<chapter>
+<title>Messages</title>
+
+<body>
+<p>
+Sometimes it is necessary to display messages for the user. This can be for
+errors, post-install help messages, pre-install warnings or simply to notify the
+user of what's going on. It is considered good form to display a message
+before any particularly long and silent task is carried out, for example (and it
+also helps cut down on bogus "compiling foo froze!" bugs).
+</p>
+
+<note>
+It is a policy violation to use any of these functions to display a line
+of characters (a banner header). The use of colours and special leading
+characters provided by these functions is sufficient to make a message stand
+out.
+</note>
+
+<p>
+In all cases, assume that the user's terminal is no wider than 79 columns, and
+that the <c>einfo</c>, <c>ewarn</c> and <c>eerror</c> functions will occupy 4 columns
+with their fancy leading markers.
+</p>
+
+</body>
+
+<section>
+<title>Information Messages</title>
+<body>
+
+<p>
+There are a number of functions available to assist here. The `echo` bash
+internal is the simplest -- it simply displays its parameters as a message.
+</p>
+
+<p>
+The <c>einfo</c> function can be used to display an informational message which is
+meant to 'stand out'. On a colour terminal, the message provided will be
+prefixed with a green asterisk.
+</p>
+
+<codesample lang="ebuild">
+pkg_postinst() {
+    einfo "You will need to set up your /etc/foo/foo.conf file before"
+    einfo "running foo for the first time. For details, please see the"
+    einfo "foo.conf(5) manual page."
+}
+</codesample>
+
+</body>
+</section>
+
+<section>
+<title>Warning Messages</title>
+<body>
+
+<p>
+The <c>ewarn</c> function is similar, but displays a yellow asterisk. This should be
+used for warning messages rather than information.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Error Messages</title>
+<body>
+
+<p>
+The <c>eerror</c> function displays a red star, and is used for displaying error
+messages. It should almost always be followed by a <c>die</c> call. This function
+is mainly used for displaying additional error details before bailing out.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Important Messages</title>
+<body>
+
+<p>
+For <e>really</e> important messages, <c>eutils.eclass</c> provides <c>ebeep</c> and
+<c>epause</c>. The former will beep a number of times, and the latter will pause
+for several seconds to allow the user to read any messages. Both can be disabled
+by the user -- you must <b>not</b> attempt to override the user's preference in
+this. <c>ebeep</c> takes an optional parameter specifying how many times to beep.
+<c>epause</c> takes an optional parameter (which <b>must</b> be an exact whole number)
+specifying for how long it should sleep.
+</p>
+
+<p>
+Do not abuse these functions -- better to save them for when things really are
+important.
+</p>
+
+<p>
+See `Message Functions Reference`_ for a full list of functions.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Good and Bad Messages</title>
+<body>
+
+<p>
+Here is an example of a bad message:
+</p>
+
+<codesample lang="ebuild">
+i=10
+while ((i--)) ; do
+    ewarn "PLEASE UPDATE TO YOUR PACKAGE TO USE linux-info.eclass"
+done
+</codesample>
+
+<ul>
+  <li>Displaying the same message repeatedly is excessive.</li>
+  <li>The uppercase is excessive.</li>
+  <li>The bad English looks unprofessional.</li>
+  <li>
+  The message will only confuse the end user and will not help them work out
+  whether they have a problem and how to solve it if they do.
+  </li>
+</ul>
+
+<p>
+It would be better written as:
+</p>
+
+<codesample lang="ebuild">
+ewarn "The 'frozbinate' function provided by eutils.eclass is deprecated"
+ewarn "in favour of frozbinate.eclass, but this package has not been"
+ewarn "updated yet. If this is a package from the main tree, please check"
+ewarn "http://bugs.gentoo.org/ and file a bug if there is not one already."
+ewarn "If this is your own package, please read the comments in the"
+ewarn "frozbinate eclass for instructions on how to convert."
+</codesample>
+
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/text.xml b/ebuild-writing/text.xml
index 41bb84b..ace7fa2 100644
--- a/ebuild-writing/text.xml
+++ b/ebuild-writing/text.xml
@@ -9,6 +9,21 @@ This section covers some general concepts with which you should be familiar when
 writing ebuilds or working with the portage tree.
 </p>
 </body>
+
+<section>
+<title>Contents</title>
+<body>
+<contentsTree/>
+</body>
+</section>
+
 </chapter>
+<include href="file-format/"/>
+<include href="use-conditional-code/"/>
+<include href="error-handling/"/>
+<include href="users-and-groups/"/>
+<include href="messages/"/>
+<include href="variables/"/>
+<include href="using-eclasses/"/>
 <include href="ebuild-functions/"/>
 </guide>
diff --git a/ebuild-writing/use-conditional-code/text.xml b/ebuild-writing/use-conditional-code/text.xml
new file mode 100644
index 0000000..84fc490
--- /dev/null
+++ b/ebuild-writing/use-conditional-code/text.xml
@@ -0,0 +1,62 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/use-conditional-code/">
+<chapter>
+<title>USE Flag Conditional Code</title>
+
+<body>
+<p>
+Often a particular block of code must only be executed if a given USE flag is
+set (or unset). For large blocks, <c>if use foo</c> is best, or for inverse tests
+either <c>if ! use foo</c> or <c>if use !foo</c> can be used (the former is more
+common and is recommended for readability). For single-statement conditions, the
+<c>use foo &amp;&amp; blah</c> (or <c>use foo || blah</c> for negatives) form is often more
+readable.
+</p>
+
+<p>
+The <c>if [ "`use foo`" ]</c> and <c>if [ -n "`use foo`" ]</c> forms which are
+occasionally seen in older code must <b>not</b> be used.
+</p>
+
+<note>
+<c>die</c> will not work as expected within a subshell, so code in the
+form <c>use foo &amp;&amp; ( blah ; blah )</c> should be avoided in favour of a proper if
+statement. See `die and Subshells`_.
+</note>
+
+<codesample lang="ebuild">
+    # USE conditional blocks...
+    if use livecd ; then
+        # remove some extra files for a small livecd install
+        rm -fr ${vimfiles}/{compiler,doc,ftplugin,indent}
+    fi
+
+    # Inverse USE conditional blocks...
+    if ! use cscope ; then
+        # the --disable-cscope configure arg doesn't quite work properly,
+        # so sed it out of feature.h if we're not USEing cscope.
+        sed -i -e '/# define FEAT_CSCOPE/d' src/feature.h || die "couldn't disable cscope"
+    fi
+
+    # USE conditional statements...
+    use ssl &amp;&amp; epatch ${FILESDIR}/${P}-ssl.patch
+    use sparc &amp;&amp; filter-flags -fomit-frame-pointer
+
+    # Inverse USE conditional statements...
+    use ncurses || epatch ${FILESDIR}/${P}-no-ncurses.patch
+</codesample>
+
+<p>
+For echoing content based upon a USE flag, there is often a better helper
+function available.
+</p>
+
+<p>
+You must not rely upon <c>use</c> producing an output -- this no longer happens.
+If you really need output displayed, use the <c>usev</c> function. The
+<c>useq</c> function is available for explicitly requesting no output.
+</p>
+</body>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml
new file mode 100644
index 0000000..7dc774b
--- /dev/null
+++ b/ebuild-writing/users-and-groups/text.xml
@@ -0,0 +1,90 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/users-and-groups/">
+<chapter>
+<title>Users and Groups</title>
+
+<body>
+<p>
+If your ebuild requires a user or group to be added for a daemon, for example,
+this should be performed via the functions available in <c>eutils.eclass</c>.
+Regardless of whether you are adding a group or a user, this should be performed
+in the <c>pkg_setup</c> function and <b>not</b> somewhere else: pkg_setup is sandbox-safe,
+is called before the compile process so a build that requires the user to exist will
+have it, and is also called for both binary and source packages.
+</p>
+</body>
+
+<section>
+<title>Adding Groups</title>
+<body>
+
+<p>
+To add a group, use the <c>enewgroup</c> function:
+</p>
+
+<pre>
+enewgroup &lt;name&gt; [uid]
+</pre>
+
+<p>
+By default the next available group ID is selected. To set a specfic group ID,
+pass it an extra argument to <c>enewgroup</c>.
+</p>
+
+<note>
+Group IDs should rarely be hardcoded. If this is the case, you should
+probably check first on gentoo-dev.
+</note>
+
+</body>
+</section>
+
+<section>
+<title>Adding Users</title>
+<body>
+
+<p>
+To add a user, use the <c>enewuser</c> function:
+</p>
+
+<pre>
+enewuser &lt;user&gt; [uid] [shell] [homedir] [groups] [params]
+</pre>
+
+<p>
+By default, both <c>enewuser</c> and <c>enewgroup</c> allocate the next available user
+ID or group ID to the new user or group - if not, you explicitly have to specify
+one.
+</p>
+
+<p>
+Arguments for <c>enewuser</c> must be passed in the order as shown above: if you do
+not want to specify a fixed user ID however but do want to set a specific shell,
+for example, use <c>-1</c> for the <c>uid</c> parameter. The same applies for any other
+parameter where you want to keep the default setting.
+</p>
+
+<p>
+Groups for the <c>groups</c> argument should be separated by a comma (<c>,</c>) and
+wrapped correctly, for example:
+</p>
+
+<pre>
+enewuser frozd -1 -1 -1 "backup,frozd"
+</pre>
+
+<p>
+Finally, any data left over for the <c>params</c> argument is passed directly to
+useradd.
+</p>
+
+<note>
+User IDs should rarely be hardcoded. If this is the case, you should
+probably check first on gentoo-dev.
+</note>
+
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/using-eclasses/text.xml b/ebuild-writing/using-eclasses/text.xml
new file mode 100644
index 0000000..171d967
--- /dev/null
+++ b/ebuild-writing/using-eclasses/text.xml
@@ -0,0 +1,98 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/using-eclasses/">
+<chapter>
+<title>Using Eclasses</title>
+
+<body>
+<p>
+An eclass is a collection (library) of functions or functionality that is shared
+between packages. See `Eclass Writing Guide`_ for the full story on what
+eclasses can do, how they work and how to write them, and `Eclass Reference`_
+for documentation on various commonly used eclasses. This section only explains
+how to use an eclass which has already been written.
+</p>
+</body>
+
+<section>
+<title>The <c>inherit</c> Function</title>
+<body>
+
+<p>
+To use an eclass, it must be 'inherited'. This is done via the <c>inherit</c>
+function, which is provided by <c>ebuild.sh</c>. The <c>inherit</c> statement must
+come at the top of the ebuild, *before* any functions. Conditional inherits are
+illegal (except where the inheritance criteria are cache-constant -- see `The
+Portage Cache`_).
+</p>
+
+<p>
+After inheriting an eclass, its provided functions can be used as normal. Here's
+<c>devtodo-0.1.18-r2.ebuild</c>, which uses three eclasses:
+</p>
+
+<codesample lang="ebuild">
+# Copyright 1999-2005 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
+
+inherit eutils bash-completion flag-o-matic
+
+DESCRIPTION="A nice command line todo list for developers"
+HOMEPAGE="http://swapoff.org/DevTodo"
+SRC_URI="http://swapoff.org/files/${PN}/${P}.tar.gz"
+
+LICENSE="GPL-2"
+SLOT="0"
+KEYWORDS="alpha amd64 arm hppa ia64 mips ppc s390 sparc x86 ppc64"
+IUSE=""
+
+RDEPEND=">=sys-libs/ncurses-5.2
+    >=sys-libs/readline-4.1"
+DEPEND="${RDEPEND}"
+
+src_unpack() {
+    unpack ${A}
+    cd ${S}
+    epatch ${FILESDIR}/${P}-gentoo.diff
+}
+
+src_compile() {
+    einfo "Running autoreconf"
+    autoreconf -f -i || die "autoreconf failed"
+    replace-flags -O? -O1
+    econf --sysconfdir=/etc/devtodo || die "econf failed"
+    emake || die "emake failed"
+}
+
+src_install() {
+    make DESTDIR=${D} install || die "make install failed"
+    dodoc AUTHORS ChangeLog QuickStart README TODO doc/scripts.sh \
+    doc/scripts.tcsh doc/todorc.example contrib/tdrec || die "dodoc failed"
+    dobashcompletion ${FILESDIR}/${PN}.bash-completion ${PN}
+}
+
+pkg_postinst() {
+    echo
+    einfo "Because of a conflict with app-misc/tdl, the tdl symbolic link"
+    einfo "and manual page have been removed."
+    bash-completion_pkg_postinst
+}
+</codesample>
+
+<p>
+Note the <c>inherit</c> immediately after the header.
+</p>
+
+<p>
+The <c>eutils</c> eclass (see `eutils.eclass Reference`_) is needed to get the
+<c>epatch</c> function.  The <c>flag-o-matic</c> eclass (see `flag-o-matic.eclass
+Reference`_) is needed for <c>replace-flags</c>, and the <c>bash-completion</c> eclass
+(`bash-completion.eclass Reference`_) is used to handle the bash completion file
+via <c>dobashcompletion</c> and <c>bash-completion_pkg_postinst</c>.
+</p>
+
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
new file mode 100644
index 0000000..d6f5aec
--- /dev/null
+++ b/ebuild-writing/variables/text.xml
@@ -0,0 +1,424 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/variables/">
+<chapter>
+<title>Variables</title>
+
+<body>
+<p>
+There are a number of special variables which must be set in ebuilds, and many
+more which can optionally be specified. There are also some predefined variables
+which are of use throughout the ebuild.
+</p>
+</body>
+
+<section>
+<title>Predefined Read-Only Variables</title>
+<body>
+
+<p>
+The following variables are defined for you. You must not attempt to set
+them.
+</p>
+
+<table>
+  <tr>
+    <th>Variable</th>
+    <th>Purpose</th>
+  </tr>
+  <tr>
+    <ti><c>P</c></ti>
+    <ti>Package name and version (excluding revision, if any), for example <c>vim-6.3</c>.</ti>
+  </tr>
+  <tr>
+    <ti><c>PN</c></ti>
+    <ti>Package name, for example <c>vim</c>.</ti>
+  </tr>
+  <tr>
+    <ti><c>PV</c></ti>
+    <ti>Package version (excluding revision, if any), for example <c>6.3</c>.</ti>
+  </tr>
+  <tr>
+    <ti><c>PR</c></ti>
+    <ti>Package revision, or <c>r0</c> if no revision exists.</ti>
+  </tr>
+  <tr>
+    <ti><c>PVR</c></ti>
+    <ti>Package version and revision, for example <c>6.3-r0</c>, <c>6.3-r1</c>.</ti>
+  </tr>
+  <tr>
+    <ti><c>PF</c></ti>
+    <ti>Package name, version and revision, for example <c>vim-6.3-r1</c>.</ti>
+  </tr>
+  <tr>
+    <ti><c>A</c></ti>
+    <ti>
+      All the source files for the package (excluding those
+      which are not available because of <c>USE</c> flags).
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>CATEGORY</c></ti>
+    <ti>Package's category, for example <c>app-editors</c>.</ti>
+  </tr>
+  <tr>
+    <ti><c>FILESDIR</c></ti>
+    <ti>
+      Path to the ebuild's <c>files/</c> directory, commonly used
+      for small patches and files. Value:
+      <c>"${PORTDIR}/${CATEGORY}/${PN}/files"</c>.
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>WORKDIR</c></ti>
+    <ti>
+      Path to the ebuild's root build directory. Value:
+      <c>"${PORTAGE_TMPDIR}/portage/${PF}/work"</c>.
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>T</c></ti>
+    <ti>
+       Path to a temporary directory which may be used by the
+       ebuild. Value: <c>"${PORTAGE_TMPDIR}/portage/${PF}/temp"</c>.
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>D</c></ti>
+    <ti>
+      Path to the temporary install directory. Value:
+      <c>"${PORTAGE_TMPDIR}/portage/${PF}/image"</c>.
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>ROOT</c></ti>
+    <ti>
+      Path to the root directory. When not using <c>${D}</c>,
+      always prepend <c>${ROOT}</c> to the path.
+    </ti>
+  </tr>
+</table>
+
+</body>
+</section>
+
+<section>
+<title>Required Variables</title>
+<body>
+
+<p>
+The following variables must be defined by every ebuild.
+</p>
+
+<table>
+  <tr>
+    <th>Variable</th>
+    <th>Purpose</th>
+  </tr>
+  <tr>
+    <ti><c>DESCRIPTION</c></ti>
+    <ti>
+    A short (less than 80 characters) description of the
+    package's purpose.
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>SRC_URI</c></ti>
+    <ti>
+    A list of source URIs for the package. Can contain
+    <c>USE</c>-conditional parts, see `SRC_URI`_.
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>HOMEPAGE</c></ti>
+    <ti>Package's homepage</ti>
+  </tr>
+  <tr>
+    <ti><c>KEYWORDS</c></ti>
+    <ti>See `KEYWORDS`_ and `Keywording`_.</ti>
+  </tr>
+  <tr>
+    <ti><c>SLOT</c></ti>
+    <ti>The package's <c>SLOT</c>. See `SLOT`_.</ti>
+  </tr>
+  <tr>
+    <ti><c>LICENSE</c></ti>
+    <ti>
+    The package's license, corresponding exactly (including
+    case) to a file in <c>licenses/</c>. See `LICENSE`_.
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>IUSE</c></ti>
+    <ti>
+    A list of all <c>USE</c> flags (excluding arch and auto
+    expand flags) used within the ebuild. See `IUSE`_.
+    </ti>
+  </tr>
+</table>
+
+</body>
+</section>
+
+<section>
+<title>Optional Variables</title>
+<body>
+
+<p>
+Specifying the following variables is optional:
+</p>
+
+<table>
+  <tr>
+    <th>Variable</th>
+    <th>Purpose</th>
+  </tr>
+  <tr>
+    <ti><c>S</c></ti>
+    <ti>
+    Path to the temporary build directory, used by
+    <c>src_compile</c> and <c>src_install</c>. Default:
+    <c>"${WORKDIR}/${P}"</c>. Ebuilds should <b>not</b> provide a
+    value for this ebuild if it is the default.
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>DEPEND</c></ti>
+    <ti>
+    A list of the package's build dependencies.  See
+    `Dependencies`_.
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>RDEPEND</c></ti>
+    <ti>
+    A list of the package's runtime dependencies. See
+    `Dependencies`_.
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>PDEPEND</c></ti>
+    <ti>
+    A list of packages to be installed after the package
+    is merged. Should only be used where <c>RDEPEND</c> is not
+    possible. See `Dependencies`_.
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>RESTRICT</c></ti>
+    <ti>
+    A space-delimited list of portage features to restrict.
+    Valid values are <c>nostrip</c>, <c>nomirror</c>, <c>nouserpriv</c>
+    and <c>fetch</c>. See `ebuild-5`_ for details.
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>PROVIDE</c></ti>
+    <ti>
+    Any virtuals provided by this package, for example
+    <c>"virtual/editor virtual/emacs"</c>.
+    </ti>
+  </tr>
+</table>
+
+</body>
+</section>
+
+<section>
+<title>SLOT</title>
+<body>
+
+<p>
+When slots are not needed, use <c>SLOT="0"</c>. Do <b>not</b> use <c>SLOT=""</c>, as
+this will disable slotting for this package.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>KEYWORDS</title>
+<body>
+
+<p>
+The only valid construct involving a <c>*</c> inside <c>KEYWORDS</c> is a <c>-*</c>. Do
+<b>not</b> use <c>KEYWORDS="*"</c> or <c>KEYWORDS="~*"</c>.
+</p>
+
+<p>
+See `Keywording`_ for how to handle this variable.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>SRC_URI</title>
+
+<subsection>
+<title>Conditional Sources</title>
+<body>
+
+<p>
+Conditional source files based upon USE flags are allowed using the usual
+<c>flag? ( )</c> syntax. This is often useful for arch-specific code or for binary
+packages -- downloading sparc binaries on ppc would be a waste of bandwidth.
+</p>
+
+<codesample lang="ebuild">
+SRC_URI="http://example.com/files/${P}-core.tar.bz2
+    x86?   ( http://example.com/files/${P}/${P}-sse-asm.tar.bz2 )
+    ppc?   ( http://example.com/files/${P}/${P}-vmx-asm.tar.bz2 )
+    sparc? ( http://example.com/files/${P}/${P}-vis-asm.tar.bz2 )
+    doc?   ( http://example.com/files/${P}/${P}-docs.tar.bz2 )"
+</codesample>
+
+<p>
+When creating digests it may be necessary to have <e>all</e> SRC_URI components
+downloaded. If you have <c>FEATURES="cvs"</c> set, portage should get this right,
+although you may end up downloading more than necessary.
+</p>
+
+<p>
+If a <c>USE_EXPAND</c> variable is used to control whether certain optional
+components are installed, the correct thing to do if the variable is unset is
+generally to install <e>all</e> available components.
+</p>
+
+<codesample lang="ebuild">
+SRC_URI="http://example.com/files/${P}-core.tar.bz2
+        examplecards_foo?  ( http://example.com/files/${P}-foo.tar.bz2 )
+        examplecards_bar?  ( http://example.com/files/${P}-bar.tar.bz2 )
+        examplecards_baz?  ( http://example.com/files/${P}-baz.tar.bz2 )
+        !examplecards_foo? ( !examplecards_bar? ( !examplecards_baz? (
+            http://example.com/files/${P}-foo.tar.bz2
+            http://example.com/files/${P}-bar.tar.bz2
+            http://example.com/files/${P}-baz.tar.bz2 ) ) )"
+</codesample>
+
+</body>
+</subsection>
+</section>
+
+<section>
+<title>IUSE</title>
+<body>
+
+<p>
+Note that the <c>IUSE</c> variable is cumulative, so there is no need to specify
+USE flags used only within inherited eclasses within the ebuild's IUSE. Also
+note that it's really really broken in portage versions before 2.0.51.
+</p>
+
+<p>
+Arch USE flags (<c>sparc</c>, <c>mips</c>, <c>x86-fbsd</c> and so on) should not be
+listed. Neither should auto-expand flags (<c>linguas_en</c> and so on).
+</p>
+
+</body>
+</section>
+
+<section>
+<title>LICENSE</title>
+<body>
+
+<p>
+It is possible to specify multiple <c>LICENSE</c> entries, and entries which only
+apply if a particular <c>USE</c> flag is set. The format is the same as for
+<c>DEPEND</c>. See `GLEP 23`_ for details.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Version Formatting Issues</title>
+<body>
+
+<p>
+Often upstream's tarball versioning format doesn't quite follow Gentoo
+conventions. Differences in how underscores and hyphens are used are
+particularly common. For example, what Gentoo calls <c>foo-1.2.3b</c> may be
+expecting a tarball named <c>foo-1.2-3b.tar.bz2</c>. Rather than hard coding version
+numbers, it is preferable to make a <c>MY_PV</c> variable and use that. The easy
+way to do this, which should be used unless you are sure you know what you are
+doing, is to use the <c>versionator</c> eclass:
+</p>
+
+<codesample lang="ebuild">
+inherit versionator
+MY_PV=$(replace_version_separator 2 '-')
+</codesample>
+
+<p>
+This code has the advantage that it will carry on working even if upstream
+switches to a format like <c>foo-1.3-4.5.tar.bz2</c> (yes, this really happens).
+</p>
+
+<p>
+It is also possible to use bash substitution to achieve the same effect (this is
+how versionator works internally), but this is complicated, error prone and hard
+to read.
+</p>
+
+<p>
+Some ebuilds use calls to <c>sed</c>, <c>awk</c> and / or <c>cut</c> to do this. This
+must <e>not</e> be done for any new code, and should be fixed to use either
+versionator or bash substitution where possible. Global scope non-bash code is
+highly discouraged.
+</p>
+
+<p>
+The <c>versionator</c> eclass can also be used to extract particular components
+from a version string. See `versionator.eclass-5`_ and the eclass source code
+for further documentation and examples. A brief summary of the functions
+follows.
+</p>
+
+<table>
+  <tr>
+    <th>Function</th>
+    <th>Purpose</th>
+  </tr>
+  <tr>
+    <ti><c>get_all_version_components</c></ti>
+    <ti>Split up a version string into its component parts.</ti>
+  </tr>
+  <tr>
+    <ti><c>get_version_components</c></ti>
+    <ti>Get important version components, excluding '.', '-' and '_'.</ti>
+  </tr>
+  <tr>
+    <ti><c>get_major_version</c></ti>
+    <ti>Get the major version.</ti>
+  </tr>
+  <tr>
+    <ti><c>get_version_component_range</c></ti>
+    <ti>Extract a range of subparts from a version string.</ti>
+  </tr>
+  <tr>
+    <ti><c>get_after_major_version</c></ti>
+    <ti>Get everything after the major version.</ti>
+  </tr>
+  <tr>
+    <ti><c>replace_version_separator</c></ti>
+    <ti>Replace a particular version separator.</ti>
+  </tr>
+  <tr>
+    <ti><c>replace_all_version_separators</c></ti>
+    <ti>Replace all version separators.</ti>
+  </tr>
+  <tr>
+    <ti><c>delete_version_separator</c></ti>
+    <ti>Delete a version separator.</ti>
+  </tr>
+  <tr>
+    <ti><c>delete_all_version_separators</c></ti>
+    <ti>Delete all version separators.</ti>
+  </tr>
+</table>
+
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/general-concepts/pic/text.xml b/general-concepts/pic/text.xml
index 2472e5f..bc847dd 100644
--- a/general-concepts/pic/text.xml
+++ b/general-concepts/pic/text.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <guide self="general-concepts/pic/">
 <chapter>
-<title>Linguas</title>
+<title>Position Independent Code</title>
 
 <body>
 <todo>
diff --git a/general-concepts/text.xml b/general-concepts/text.xml
index bc35736..02a7c09 100644
--- a/general-concepts/text.xml
+++ b/general-concepts/text.xml
@@ -9,6 +9,14 @@ This section covers some general concepts with which you should be familiar when
 writing ebuilds or working with the portage tree.
 </p>
 </body>
+
+<section>
+<title>Contents</title>
+<body>
+<contentsTree/>
+</body>
+</section>
+
 </chapter>
 
 <include href="autotools/"/>
@@ -17,6 +25,7 @@ writing ebuilds or working with the portage tree.
 <include href="linguas/"/>
 <include href="mirrors/"/>
 <include href="overlay/"/>
+<include href="pic/"/>
 <include href="portage-cache/"/>
 <include href="privileges/"/>
 <include href="sandbox/"/>
diff --git a/str.tokenize.function.xsl b/str.tokenize.function.xsl
index b7dc5eb..a5f8589 100644
--- a/str.tokenize.function.xsl
+++ b/str.tokenize.function.xsl
@@ -33,7 +33,6 @@
             <xsl:call-template name="str:_tokenize-delimiters">

               <xsl:with-param name="string" select="$string" />

               <xsl:with-param name="delimiters" select="$delimiters" />

-              <xsl:with-param name="scope" select="0" />

             </xsl:call-template>

           </xsl:otherwise>

         </xsl:choose>

@@ -56,7 +55,6 @@
 <xsl:template name="str:_tokenize-delimiters">

   <xsl:param name="string"/>

   <xsl:param name="delimiters"/>

-  <xsl:param name="scope" select="1"/>

   <xsl:variable name="delimiter" select="substring($delimiters, 1, 1)" />

   <xsl:choose>

     <xsl:when test="not($delimiter)">

@@ -70,13 +68,10 @@
         </xsl:call-template>

         <xsl:value-of select="$delimiter"/>

       </xsl:if>

-      <xsl:if test="$scope = 0">

-        <delimiter><xsl:value-of select="$delimiter"/></delimiter>

-      </xsl:if>

+      <delimiter><xsl:attribute name="delimiter"><xsl:value-of select="$delimiter"/></xsl:attribute><xsl:value-of select="$delimiter"/></delimiter>

       <xsl:call-template name="str:_tokenize-delimiters">

         <xsl:with-param name="string" select="substring-after($string, $delimiter)"/>

         <xsl:with-param name="delimiters" select="$delimiters"/>

-        <xsl:with-param name="scope" select="$scope"/>

       </xsl:call-template>

     </xsl:when>

     <xsl:otherwise>