aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTim Yamin <plasmaroo@gentoo.org>2006-02-21 00:26:13 +0000
committerTim Yamin <plasmaroo@gentoo.org>2006-02-21 00:26:13 +0000
commitde5d23641714ccf460d18f2d127341da616c8503 (patch)
treeb4d17fd3e23a633f17855eaef68328666ded45f5
parentAdd "General Concepts"::"Licenses"; change <include> behaviour to *not* have ... (diff)
downloaddevmanual-de5d23641714ccf460d18f2d127341da616c8503.tar.gz
devmanual-de5d23641714ccf460d18f2d127341da616c8503.tar.bz2
devmanual-de5d23641714ccf460d18f2d127341da616c8503.zip
More updates. Update the stylesheet adding a few new elements and more sh
highlighting grammar. git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/devmanual/trunk@4 176d3534-300d-0410-8db8-84e73ed771c3
-rw-r--r--devbook.xsl68
-rw-r--r--general-concepts/linguas/text.xml13
-rw-r--r--general-concepts/mirrors/diagram.pngbin0 -> 31779 bytes
-rw-r--r--general-concepts/mirrors/diagram.svg521
-rw-r--r--general-concepts/mirrors/text.xml89
-rw-r--r--general-concepts/overlay/text.xml52
-rw-r--r--general-concepts/pic/text.xml13
-rw-r--r--general-concepts/portage-cache/text.xml79
-rw-r--r--general-concepts/privileges/text.xml15
-rw-r--r--general-concepts/sandbox/text.xml30
-rw-r--r--general-concepts/slotting/text.xml52
-rw-r--r--general-concepts/text.xml10
-rw-r--r--general-concepts/tree/text.xml185
-rw-r--r--general-concepts/use-flags/text.xml230
-rw-r--r--general-concepts/user-environment/text.xml88
15 files changed, 1434 insertions, 11 deletions
diff --git a/devbook.xsl b/devbook.xsl
index 886ea50..f30096b 100644
--- a/devbook.xsl
+++ b/devbook.xsl
@@ -13,6 +13,7 @@
</xsl:text>
</xsl:variable>
+<xsl:variable name="qvariable-start">$</xsl:variable>
<xsl:variable name="variable-start">${</xsl:variable>
<xsl:variable name="variable-end">}</xsl:variable>
@@ -48,7 +49,10 @@
</xsl:when>
<xsl:when test="substring($data, string-length($data)) = ')'">
- <xsl:value-of select="substring($data, 1, string-length($data)-1)"/><span class="PreProc">)</span>
+ <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 -->
@@ -66,15 +70,29 @@
<xsl:when test="substring($data, 1, 1) = '&quot;'">
<span class="Statement">&quot;</span>
- <xsl:value-of select="substring($data, 2)"/>
+ <xsl:call-template name="highlight-subtokenate">
+ <xsl:with-param name="data" select="substring($data, 2)"/>
+ </xsl:call-template>
</xsl:when>
<xsl:when test="substring($data, string-length($data)) = '&quot;'">
- <xsl:value-of select="substring($data, 0, string-length($data))"/>
+ <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>
+ <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'">
+ <span class="Statement"><xsl:value-of select="$data"/></span>
+ </xsl:when>
+
<!-- Default keywords -->
<xsl:when test="$data = 'use' or $data = 'has_version' or $data = 'best_version' or $data = 'use_with' or $data = 'use_enable' or
$data = 'check_KV' or $data = 'keepdir' or $data = 'econf' or $data = 'die' or $data = 'einstall' or $data = 'einfo' or
@@ -304,7 +322,7 @@
<!-- No match return -->
<xsl:otherwise>
- <highlight-nomatch-sub><xsl:value-of select="$data"/></highlight-nomatch-sub>
+ <xsl:value-of select="$data"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
@@ -326,7 +344,8 @@
<!-- 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">
+ <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>
@@ -347,7 +366,7 @@
</xsl:call-template>
</xsl:when>
- <xsl:when test=". = '{' or . = '}' or . = '\' or . = '(' or . = '#'">
+ <xsl:when test=". = '{' or . = '}' or . = '\' or . = '('">
<span class="PreProc"><xsl:value-of select="."/></span>
</xsl:when>
@@ -367,20 +386,20 @@
</xsl:template>
<xsl:template match="chapter">
- <h1><xsl:value-of select="title"/></h1>
+ <h1><xsl:apply-templates select="title"/></h1>
<xsl:apply-templates select="(body|section)"/>
</xsl:template>
<xsl:template match="section">
<div class="section">
- <h2><xsl:value-of select="title"/></h2>
+ <h2><xsl:apply-templates select="title"/></h2>
<xsl:apply-templates select="(body|subsection)"/>
</div>
</xsl:template>
<xsl:template match="subsection">
<div class="section">
- <h3><xsl:value-of select="title"/></h3>
+ <h3><xsl:apply-templates select="title"/></h3>
<xsl:apply-templates select="(body|subsection)"/>
</div>
</xsl:template>
@@ -395,6 +414,10 @@
</p>
</xsl:template>
+ <xsl:template match="pre">
+ <pre><xsl:apply-templates/></pre>
+ </xsl:template>
+
<!-- FIXME: Handle lang=... -->
<xsl:template match="codesample">
<pre><span class="Constant">
@@ -421,6 +444,7 @@
</div>
</xsl:template>
+ <!-- Lists -->
<xsl:template match="li">
<li><xsl:apply-templates/></li>
</xsl:template>
@@ -433,6 +457,28 @@
<ul><xsl:apply-templates/></ul>
</xsl:template>
+ <!-- Definition Lists -->
+ <xsl:template match="dl">
+ <dl><xsl:apply-templates/></dl>
+ </xsl:template>
+
+ <xsl:template match="dt">
+ <dt><xsl:apply-templates/></dt>
+ </xsl:template>
+
+ <xsl:template match="dd">
+ <dd>
+ <xsl:for-each select="p">
+ <xsl:choose>
+ <xsl:when test="count(../p) = 1"><xsl:apply-templates/></xsl:when>
+ <xsl:when test="position() = 1"><p class="first"><xsl:apply-templates/></p></xsl:when>
+ <xsl:when test="position() = last()"><p class="last"><xsl:apply-templates/></p></xsl:when>
+ <xsl:otherwise><p><xsl:apply-templates/></p></xsl:otherwise>
+ </xsl:choose>
+ </xsl:for-each>
+ </dd>
+ </xsl:template>
+
<xsl:template match="important">
<div class="important">
<p class="first admonition-title">Important</p>
@@ -476,7 +522,7 @@
<xsl:template match="/">
<html lang="en-GB" xml:lang="en-GB" xmlns="http://www.w3.org/1999/xhtml">
<head>
- <title>Gentoo Development Guide</title>
+ <title>Gentoo Development Guide: <xsl:value-of select="/guide/chapter[1]/title"/></title>
<link rel="stylesheet" href="http://dev.gentoo.org/~plasmaroo/devmanual/styles/devmanual.css" type="text/css" />
</head>
<body>
@@ -501,7 +547,7 @@
<xsl:apply-templates/>
</div>
- <div class="navtop" style="text-align: center;">
+ <div class="navbottom" style="text-align: center;">
<table style="border-top: 1px dashed #330066; margin-left: auto; margin-right: auto;
width: 100%;">
diff --git a/general-concepts/linguas/text.xml b/general-concepts/linguas/text.xml
new file mode 100644
index 0000000..d44a879
--- /dev/null
+++ b/general-concepts/linguas/text.xml
@@ -0,0 +1,13 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/linguas/">
+<chapter>
+<title>Linguas</title>
+
+<body>
+<todo>
+Write this. From vapier: "used to specify languages users wish to have support for. USE=nls covers generally natural language support, but LINGUAS covers specific languages (see the games-rpg/nwn for example). the variable is expanded for USE access in ebuilds. LINGUAS=de would automatically add 'linguas_de' to USE." We also need strip-linguas examples.
+</todo>
+</body>
+
+</chapter>
+</guide>
diff --git a/general-concepts/mirrors/diagram.png b/general-concepts/mirrors/diagram.png
new file mode 100644
index 0000000..ede32ea
--- /dev/null
+++ b/general-concepts/mirrors/diagram.png
Binary files differ
diff --git a/general-concepts/mirrors/diagram.svg b/general-concepts/mirrors/diagram.svg
new file mode 100644
index 0000000..0af1f1c
--- /dev/null
+++ b/general-concepts/mirrors/diagram.svg
@@ -0,0 +1,521 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://web.resource.org/cc/"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ sodipodi:docbase="/home/plasmaroo"
+ sodipodi:docname="diagram.svg"
+ inkscape:version="0.41"
+ sodipodi:version="0.32"
+ version="1.0"
+ x="0.0000000"
+ y="0.0000000"
+ width="700.00000px"
+ height="250.00000px"
+ viewBox="0 0 700 250"
+ id="svg1546">
+ <metadata
+ id="metadata71">
+ <rdf:RDF
+ id="RDF73">
+ <cc:Work
+ id="Work75"
+ rdf:about="">
+ <dc:format
+ id="format77">image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage"
+ id="type79" />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <sodipodi:namedview
+ inkscape:current-layer="svg1546"
+ inkscape:window-y="264"
+ inkscape:window-x="164"
+ inkscape:cy="81.156529"
+ inkscape:cx="343.48587"
+ inkscape:zoom="0.97294509"
+ inkscape:window-height="541"
+ inkscape:window-width="968"
+ inkscape:pageshadow="2"
+ inkscape:pageopacity="1.0000000"
+ borderopacity="1.0"
+ bordercolor="#666666"
+ pagecolor="#eeeeee"
+ id="base" />
+ <defs
+ id="defs1680" />
+ <desc
+ id="desc1548">CVS to RSYNC Propagation</desc>
+ <rect
+ y="0.24284256"
+ x="-2.0556145"
+ height="260.03522"
+ width="710.21484"
+ id="rect1360"
+ style="fill:#eeeeee;fill-opacity:1.0000000;fill-rule:evenodd;stroke:none;stroke-width:1.0000000px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="10.000000"
+ y="110.00000"
+ style="fill:#ffcccc;stroke:#000000;stroke-width:2.0000000"
+ id="rect1551" />
+ <text
+ x="50"
+ y="130"
+ style="text-anchor:middle"
+ id="text1553">Developers</text>
+ <line
+ id="line1555"
+ stroke="black"
+ stroke-width="2"
+ y2="125.00000"
+ x2="130.00000"
+ y1="125.00000"
+ x1="90.000000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1557"
+ stroke="black"
+ stroke-width="2"
+ y2="120.00000"
+ x2="122.00000"
+ y1="125.00000"
+ x1="130.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1559"
+ stroke="black"
+ stroke-width="2"
+ y2="130.00000"
+ x2="122.00000"
+ y1="125.00000"
+ x1="130.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="10.000000"
+ y="60.000000"
+ style="fill:#ffcccc;stroke:#000000;stroke-width:2.0000000"
+ id="rect1561" />
+ <text
+ x="50"
+ y="80"
+ style="text-anchor:middle"
+ id="text1563">Developers</text>
+ <path
+ d="M 90.000000,75.000000 C 103.33333,75.000000 110.00000,83.333333 110.00000,100.00000 C 110.00000,120.00000 116.66667,128.33333 130.00000,125.00000"
+ style="fill:none;stroke:#000000;stroke-width:2.0000000"
+ id="path1565" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="10.000000"
+ y="160.00000"
+ style="fill:#ffcccc;stroke:#000000;stroke-width:2.0000000"
+ id="rect1567" />
+ <text
+ x="50"
+ y="180"
+ style="text-anchor:middle"
+ id="text1569">Developers</text>
+ <path
+ d="M 90.000000,175.00000 C 103.33333,175.00000 110.00000,166.66667 110.00000,150.00000 C 110.00000,130.00000 116.66667,121.66667 130.00000,125.00000"
+ style="fill:none;stroke:#000000;stroke-width:2.0000000"
+ id="path1571" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="130.00000"
+ y="110.00000"
+ style="fill:#ffffff;stroke:#000000;stroke-width:2.0000000"
+ id="rect1573" />
+ <text
+ x="170"
+ y="130"
+ style="text-anchor:middle"
+ id="text1575">dev.gentoo</text>
+ <line
+ id="line1577"
+ stroke="black"
+ stroke-width="2"
+ y2="125.00000"
+ x2="250.00000"
+ y1="125.00000"
+ x1="210.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1579"
+ stroke="black"
+ stroke-width="2"
+ y2="120.00000"
+ x2="242.00000"
+ y1="125.00000"
+ x1="250.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1581"
+ stroke="black"
+ stroke-width="2"
+ y2="130.00000"
+ x2="242.00000"
+ y1="125.00000"
+ x1="250.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="250.00000"
+ y="110.00000"
+ style="fill:#ffffff;stroke:#000000;stroke-width:2.0000000"
+ id="rect1583" />
+ <text
+ x="290"
+ y="123"
+ style="text-anchor:middle"
+ id="text1585">Staging</text>
+ <text
+ x="290"
+ y="135"
+ style="text-anchor:middle"
+ id="text1587">Box</text>
+ <line
+ id="line1589"
+ stroke="black"
+ stroke-width="2"
+ y2="125.00000"
+ x2="370.00000"
+ y1="125.00000"
+ x1="330.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1591"
+ stroke="black"
+ stroke-width="2"
+ y2="120.00000"
+ x2="362.00000"
+ y1="125.00000"
+ x1="370.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1593"
+ stroke="black"
+ stroke-width="2"
+ y2="130.00000"
+ x2="362.00000"
+ y1="125.00000"
+ x1="370.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="370.00000"
+ y="110.00000"
+ style="fill:#ffffff;stroke:#000000;stroke-width:2.0000000"
+ id="rect1595" />
+ <text
+ x="410"
+ y="130"
+ style="text-anchor:middle"
+ id="text1597">OSU Mirrors</text>
+ <line
+ id="line1599"
+ stroke="black"
+ stroke-width="2"
+ y2="70.000000"
+ x2="482.00000"
+ y1="75.000000"
+ x1="490.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1601"
+ stroke="black"
+ stroke-width="2"
+ y2="80.000000"
+ x2="482.00000"
+ y1="75.000000"
+ x1="490.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <path
+ d="M 450.00000,125.00000 C 463.33333,125.00000 470.00000,116.66667 470.00000,100.00000 C 470.00000,80.000000 476.66667,71.666667 490.00000,75.000000"
+ style="fill:none;stroke:#000000;stroke-width:2.0000000"
+ id="path1603" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="490.00000"
+ y="60.000000"
+ style="fill:#ccffcc;stroke:#000000;stroke-width:2.0000000"
+ id="rect1605" />
+ <text
+ x="530"
+ y="80"
+ style="text-anchor:middle"
+ id="text1607">Public mirror</text>
+ <line
+ id="line1609"
+ stroke="black"
+ stroke-width="2"
+ y2="125.00000"
+ x2="490.00000"
+ y1="125.00000"
+ x1="450.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1611"
+ stroke="black"
+ stroke-width="2"
+ y2="120.00000"
+ x2="482.00000"
+ y1="125.00000"
+ x1="490.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1613"
+ stroke="black"
+ stroke-width="2"
+ y2="130.00000"
+ x2="482.00000"
+ y1="125.00000"
+ x1="490.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="490.00000"
+ y="110.00000"
+ style="fill:#ccffcc;stroke:#000000;stroke-width:2.0000000"
+ id="rect1615" />
+ <text
+ x="530"
+ y="130"
+ style="text-anchor:middle"
+ id="text1617">Public mirror</text>
+ <line
+ id="line1619"
+ stroke="black"
+ stroke-width="2"
+ y2="170.00000"
+ x2="482.00000"
+ y1="175.00000"
+ x1="490.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1621"
+ stroke="black"
+ stroke-width="2"
+ y2="180.00000"
+ x2="482.00000"
+ y1="175.00000"
+ x1="490.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <path
+ d="M 450.00000,125.00000 C 463.33333,125.00000 470.00000,133.33333 470.00000,150.00000 C 470.00000,170.00000 476.66667,178.33333 490.00000,175.00000"
+ style="fill:none;stroke:#000000;stroke-width:2.0000000"
+ id="path1623" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="490.00000"
+ y="160.00000"
+ style="fill:#ccffcc;stroke:#000000;stroke-width:2.0000000"
+ id="rect1625" />
+ <text
+ x="530"
+ y="180"
+ style="text-anchor:middle"
+ id="text1627">Public mirror</text>
+ <line
+ id="line1629"
+ stroke="black"
+ stroke-width="2"
+ y2="20.000000"
+ x2="602.00000"
+ y1="25.000000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1631"
+ stroke="black"
+ stroke-width="2"
+ y2="30.000000"
+ x2="602.00000"
+ y1="25.000000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <path
+ d="M 570.00000,75.000000 C 583.33333,75.000000 590.00000,66.666667 590.00000,50.000000 C 590.00000,30.000000 596.66667,21.666667 610.00000,25.000000"
+ style="fill:none;stroke:#000000;stroke-width:2.0000000"
+ id="path1633" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="610.00000"
+ y="10.000000"
+ style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000"
+ id="rect1635" />
+ <text
+ x="650"
+ y="30"
+ style="text-anchor:middle"
+ id="text1637">Users</text>
+ <line
+ id="line1639"
+ stroke="black"
+ stroke-width="2"
+ y2="75.000000"
+ x2="610.00000"
+ y1="75.000000"
+ x1="570.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1641"
+ stroke="black"
+ stroke-width="2"
+ y2="70.000000"
+ x2="602.00000"
+ y1="75.000000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1643"
+ stroke="black"
+ stroke-width="2"
+ y2="80.000000"
+ x2="602.00000"
+ y1="75.000000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="610.00000"
+ y="60.000000"
+ style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000"
+ id="rect1645" />
+ <text
+ x="650"
+ y="80"
+ style="text-anchor:middle"
+ id="text1647">Users</text>
+ <line
+ id="line1649"
+ stroke="black"
+ stroke-width="2"
+ y2="125.00000"
+ x2="610.00000"
+ y1="125.00000"
+ x1="570.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1651"
+ stroke="black"
+ stroke-width="2"
+ y2="120.00000"
+ x2="602.00000"
+ y1="125.00000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1653"
+ stroke="black"
+ stroke-width="2"
+ y2="130.00000"
+ x2="602.00000"
+ y1="125.00000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="610.00000"
+ y="110.00000"
+ style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000"
+ id="rect1655" />
+ <text
+ x="650"
+ y="130"
+ style="text-anchor:middle"
+ id="text1657">Users</text>
+ <line
+ id="line1659"
+ stroke="black"
+ stroke-width="2"
+ y2="175.00000"
+ x2="610.00000"
+ y1="175.00000"
+ x1="570.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1661"
+ stroke="black"
+ stroke-width="2"
+ y2="170.00000"
+ x2="602.00000"
+ y1="175.00000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1663"
+ stroke="black"
+ stroke-width="2"
+ y2="180.00000"
+ x2="602.00000"
+ y1="175.00000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="610.00000"
+ y="160.00000"
+ style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000"
+ id="rect1665" />
+ <text
+ x="650"
+ y="180"
+ style="text-anchor:middle"
+ id="text1667">Users</text>
+ <line
+ id="line1669"
+ stroke="black"
+ stroke-width="2"
+ y2="220.00000"
+ x2="602.00000"
+ y1="225.00000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1671"
+ stroke="black"
+ stroke-width="2"
+ y2="230.00000"
+ x2="602.00000"
+ y1="225.00000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <path
+ d="M 570.00000,175.00000 C 583.33333,175.00000 590.00000,183.33333 590.00000,200.00000 C 590.00000,220.00000 596.66667,228.33333 610.00000,225.00000"
+ style="fill:none;stroke:#000000;stroke-width:2.0000000"
+ id="path1673" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="610.00000"
+ y="210.00000"
+ style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000"
+ id="rect1675" />
+ <text
+ x="650"
+ y="230"
+ style="text-anchor:middle"
+ id="text1677">Users</text>
+</svg>
diff --git a/general-concepts/mirrors/text.xml b/general-concepts/mirrors/text.xml
new file mode 100644
index 0000000..8b12bbb
--- /dev/null
+++ b/general-concepts/mirrors/text.xml
@@ -0,0 +1,89 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/mirrors/">
+<chapter>
+<title>Mirrors</title>
+
+<section>
+<title>Automatic Mirroring</title>
+
+<body>
+<p>
+Packages will automatically have their <c>SRC_URI</c> components mirrored onto
+Gentoo mirrors. When fetching, portage checks Gentoo mirrors first before
+trying the original upstream location.
+</p>
+
+<p>
+This is generally desired behaviour -- upstream mirrors are prone to being
+rearranged, tidied out or having files modified.
+</p>
+</body>
+
+<subsection>
+<title>Restricting Automatic Mirroring</title>
+<body>
+<p>
+Three <c>RESTRICT</c> keywords can be used to control the mirroring process.
+</p>
+
+<p>
+The <c>RESTRICT=&quot;nomirror&quot;</c> setting should be used if we cannot legally mirror
+certain files.
+</p>
+
+<p>
+The <c>RESTRICT="primaryuri"</c> setting causes portage to try
+original locations <e>first</e>, and then fall back to mirrors if necessary -- this
+is sometimes useful if approximate download counts are needed, or if upstream
+have a reliable mirror setup.
+</p>
+
+<p>
+There is also <c>RESTRICT="fetch"</c>, which prevents portage from trying to
+fetch anything manually. The `pkg_nofetch`_ function will be called if any
+<c>SRC_URI</c> components cannot be found. This should only be used if a license
+requires it.
+</p>
+</body>
+</subsection>
+
+<subsection>
+<title>Suitable Download Hosts</title>
+<body>
+<p>
+Hosting files off <c>dev.gentoo.org</c> is <b>not</b> acceptable for main-tree items.
+Instead, these files must be moved onto <c>mirror://gentoo</c> before release.
+</p>
+</body>
+</subsection>
+</section>
+
+<section>
+<title>Gentoo Mirrors</title>
+
+<body>
+<p>
+To manually upload a file to <c>mirror://gentoo</c>, <c>scp</c> it to
+<c>dev.gentoo.org:/space/distfiles-local</c>. You must ensure that the permissions
+are set to <c>ug+rw</c> manually. The file should appear on the mirrors within four
+hours (note that this is *less frequent* than `CVS to rsync`_).
+
+If the upstream download location for a package uses a non-standard TCP port
+(anything other than 21, 80 or 443), you <e>must</e> manually mirror the files. Not
+doing so can cause all kinds of problems with strict firewalls.
+</p>
+</body>
+</section>
+
+<section>
+<title>Mirroring Process</title>
+
+<body>
+<figure short="Mirroring Process" link="diagram.png">
+Diagram showing the mirroring process.
+</figure>
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/general-concepts/overlay/text.xml b/general-concepts/overlay/text.xml
new file mode 100644
index 0000000..d3ae6a1
--- /dev/null
+++ b/general-concepts/overlay/text.xml
@@ -0,0 +1,52 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/mirrors/">
+<chapter>
+<title>Overlay</title>
+
+<body>
+<p>
+Portage can look in multiple places for packages by using an overlay. The
+locations of overlays are controlled by the <c>PORTDIR_OVERLAY</c> variable, which
+should contain a space-separated list of paths.
+</p>
+
+<p>
+The overlay should contain the same directory structure as <c>PORTDIR</c> (although
+only the necessary directories need be included). For example, a simple overlay
+might have a directory structure like:
+</p>
+
+<pre>
+overlay
+|-- dev-util
+ `-- gengetopt
+ |-- Manifest
+ |-- files
+ | `-- digest-gengetopt-2.13
+ `-- gengetopt-2.13.ebuild
+</pre>
+
+<p>
+An overlay can be used to 'add' items to the tree (although you must ensure that
+<c>/etc/portage/categories</c> is used if any new categories are added) or to
+override existing entries.
+</p>
+</body>
+
+<section>
+<title>Overlay and Eclasses</title>
+
+<body>
+<p>
+Be very careful when using eclasses in an overlay. Portage will not do cache
+updates when an overlay eclass is changed, nor will it do cache updates when a
+main portage tree eclass which is used by an overlay ebuild changes. You may
+also encounter bogus 'illegal inherit' notices when working with eclasses in
+overlay (see `QA Notice -- ECLASS foo inherited illegally`_). To be safe,
+manually <c>touch</c> all relevant overlay files after updating overlay eclasses.
+</p>
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/general-concepts/pic/text.xml b/general-concepts/pic/text.xml
new file mode 100644
index 0000000..2472e5f
--- /dev/null
+++ b/general-concepts/pic/text.xml
@@ -0,0 +1,13 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/pic/">
+<chapter>
+<title>Linguas</title>
+
+<body>
+<todo>
+policy. http://www.gentoo.org/proj/en/hardened/pic-internals.xml has some technical details.
+</todo>
+</body>
+
+</chapter>
+</guide>
diff --git a/general-concepts/portage-cache/text.xml b/general-concepts/portage-cache/text.xml
new file mode 100644
index 0000000..73e5622
--- /dev/null
+++ b/general-concepts/portage-cache/text.xml
@@ -0,0 +1,79 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/portage-cache/">
+<chapter>
+<title>The Portage Cache</title>
+
+<body>
+<p>
+Portage uses a cache for most top-level variables (<c>DEPEND</c>, <c>DESCRIPTION</c>,
+<c>SRC_URI</c> and so on). This cache may be generated on a different machine, so
+these variables must be either static or generated using only unchanging
+'version / name' variables (<c>P</c>, <c>PN</c>, <c>PV</c>, <c>PR</c>, <c>PVR</c> and <c>PF</c>).
+</p>
+
+<p>
+So, the following will not work:
+</p>
+
+<codesample lang="ebuild">
+# DO NOT DO THIS!
+if ! has_version "x11-libs/gtk+" ; then
+ DEPEND="${DEPEND}
+ gtk2? ( >=x11-libs/gtk+-2 )
+ !gtk2? ( =x11-libs/gtk+-1.2* )"
+fi
+</codesample>
+
+<p>
+However, this is legal, since <c>versionator.eclass</c> works upon <c>PV</c>, and
+<c>PV</c> and <c>PN</c> are both static:
+</p>
+
+<codesample lang="ebuild">
+inherit versionator
+
+if [[ $(get_major_version) -ge 7 ]] ; then
+ IUSE="${IUSE} tcltk mzscheme"
+ DEPEND="$DEPEND
+ tcltk? ( dev-lang/tcl )
+ mzscheme? ( dev-lisp/mzscheme )"
+ RDEPEND="$RDEPEND
+ tcltk? ( dev-lang/tcl )
+ mzscheme? ( dev-lisp/mzscheme )"
+
+ if [[ "${MY_PN}" != "vim-core" ]] ; then
+ RDEPEND="${RDEPEND} !&lt;app-vim/align-30-r1"
+ fi
+fi
+</codesample>
+</body>
+
+<section>
+<title>Conditional Inherits</title>
+<body>
+<p>
+Because eclasses modify various cached variables, conditional inheritance is not
+allowed except where the same results will always be obtained on every system.
+For example, inherits based upon <c>USE</c> flags are illegal, but inherits based
+solely upon <c>PN</c> are allowed.
+</p>
+
+<p>
+As an example of a legal and possibly useful conditional inherit, some eclasses
+do:
+</p>
+
+<codesample lang="ebuild">
+if [[ "${PN##*-}" == "cvs" ]] ; then
+ inherit cvs
+fi
+</codesample>
+
+<p>
+This allows the same eclass to be used for both regular and <c>-cvs</c> packages.
+</p>
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/general-concepts/privileges/text.xml b/general-concepts/privileges/text.xml
new file mode 100644
index 0000000..8dc516b
--- /dev/null
+++ b/general-concepts/privileges/text.xml
@@ -0,0 +1,15 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/privileges/">
+<chapter>
+<title>Privileges</title>
+
+<body>
+<todo>
+general privs stuff, include stuff on setuid/setgid and sticky since
+a lot of people seem to be confused about those... Also notes on the portage
+user and group issues, and what we use for root:root to make *bsd work.
+</todo>
+</body>
+
+</chapter>
+</guide>
diff --git a/general-concepts/sandbox/text.xml b/general-concepts/sandbox/text.xml
new file mode 100644
index 0000000..d474f26
--- /dev/null
+++ b/general-concepts/sandbox/text.xml
@@ -0,0 +1,30 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/sandbox/">
+<chapter>
+<title>Sandbox</title>
+
+<body>
+<p>
+During the <c>src_unpack</c>, <c>src_compile</c>, <c>src_test</c> and <c>src_install</c>
+phases, <c>ebuild.sh</c> operates inside a <e>sandbox</e>. This is a special environment
+which attempts to help prevent badly written ebuilds (or ebuilds working with
+badly written build systems) accidentally writing outside of permitted locations.
+</p>
+
+<p>
+<b>All packages must build correctly when sandbox is active.</b> Packages must not
+achieve this by using sneaky tricks to make sandbox warnings not show up -- the
+sandbox is there to ensure that binary packages will work correctly, and that
+a badly written <c>Makefile</c> won't cause problems. Using <c>addwrite</c> is
+generally <b>not</b> the correct solution.
+</p>
+
+<p>
+See `Sandbox Functions Reference`_ for details on sandbox-related functions. See
+`Handling Access Violations`_ for suggestions on fixing sandbox-related build
+problems.
+</p>
+</body>
+
+</chapter>
+</guide>
diff --git a/general-concepts/slotting/text.xml b/general-concepts/slotting/text.xml
new file mode 100644
index 0000000..928f3fd
--- /dev/null
+++ b/general-concepts/slotting/text.xml
@@ -0,0 +1,52 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/slotting/">
+<chapter>
+<title>Slotting</title>
+
+<body>
+<p>
+Packages can support having multiple versions installed simultaneously. This is
+useful for libraries which may have changed interfaces between versions -- for
+example, the <c>gtk+</c> package can install both versions <c>1.2</c> and <c>2.6</c> in
+parallel. This feature is called slotting.
+</p>
+
+<p>
+Most packages have no need for slotting. These packages specify <c>SLOT="0"</c> in
+the ebuilds. This is <b>not</b> the same as specifying an empty slot -- an empty
+slot means &quot;disable slotting entirely&quot;, and should not be used.
+</p>
+
+<p>
+Portage permits at most one instance of a package installation <e>per <c>SLOT</c>
+value</e>. For example, say we have the following:
+</p>
+
+<ul>
+ <li><c>foo-1.1</c> with <c>SLOT="1"</c></li>
+ <li><c>foo-1.2</c> with <c>SLOT="1"</c></li>
+ <li><c>foo-2.0</c> with <c>SLOT="2"</c></li>
+ <li><c>foo-2.1</c> with <c>SLOT="2"</c></li>
+</ul>
+
+<p>
+Then the user could have, say, <c>foo-1.2</c> and <c>foo-2.0</c> installed in
+parallel, but <e>not</e> <c>foo-1.1</c> and <c>foo-1.2</c>. Note that it is entirely
+possible that the user may have <c>foo-2.0</c> installed and no <c>foo-1.x</c> at all.
+</p>
+
+<p>
+It is not possible to <c>DEPEND</c> upon a package in a specific slot.
+</p>
+
+<p>
+Currently portage will accept an arbitrary string for the value of <c>SLOT</c>. For
+future compatibility, it is recommended that slots contain only characters which
+are allowed in an ebuild name or version (alphanumerics, hypens, full stops,
+underscores, the plus character) -- other characters may cause problems with
+future portage enhancements.
+</p>
+</body>
+
+</chapter>
+</guide>
diff --git a/general-concepts/text.xml b/general-concepts/text.xml
index 8df1ded..bc35736 100644
--- a/general-concepts/text.xml
+++ b/general-concepts/text.xml
@@ -14,4 +14,14 @@ writing ebuilds or working with the portage tree.
<include href="autotools/"/>
<include href="config-protect/"/>
<include href="licenses/"/>
+<include href="linguas/"/>
+<include href="mirrors/"/>
+<include href="overlay/"/>
+<include href="portage-cache/"/>
+<include href="privileges/"/>
+<include href="sandbox/"/>
+<include href="slotting/"/>
+<include href="tree/"/>
+<include href="use-flags/"/>
+<include href="user-environment/"/>
</guide>
diff --git a/general-concepts/tree/text.xml b/general-concepts/tree/text.xml
new file mode 100644
index 0000000..1caa834
--- /dev/null
+++ b/general-concepts/tree/text.xml
@@ -0,0 +1,185 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/tree/">
+<chapter>
+<title>The Portage Tree</title>
+
+<body>
+<p>
+The basic layout of the portage tree is as follows:
+</p>
+
+<ul>
+ <li>
+ Categories, for example <c>app-editors</c>, <c>sys-apps</c>
+ <ul>
+ <li>Category metadata, for example <c>app-admin/metadata.xml</c></li>
+ <li>
+ Package directories for example <c>app-editors/vim</c>
+ <ul>
+ <li>Package metadata, for example <c>app-editors/vim/metadata.xml</c></li>
+ <li>Package changelog, for example <c>app-editors/vim/ChangeLog</c></li>
+ <li>Package Manifest, for example <c>app-editors/vim/Manifest</c></li>
+ <li>
+ Ebuilds, for example <c>app-editors/vim/vim-6.3.068.ebuild</c>,
+ <c>app-editors/vim/vim-7.0_alpha20050326.ebuild</c>
+ </li>
+ <li>
+ Package files directory, for example <c>app-editors/vim/files</c>
+ <ul>
+ <li>
+ Digest files, for example <c>app-editors/vim/files/digest-vim-6.3.068</c>,
+ <c>app-editors/vim/files/digest-vim-7.0_alpha20050326</c>
+ </li>
+ <li>
+ Small patches and other miscellaneous files, for example
+ <c>app-editors/vim/files/vim-completion</c>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>Eclasses directory, <c>eclass/</c></li>
+ <li>Licenses directory, <c>licenses/</c></li>
+ <li>
+ Profiles directory, <c>profiles/</c>
+ <ul>
+ <li>
+ Various control and documentation files, for example <c>categories</c>,
+ <c>info_pkgs</c>, <c>info_vars</c>, <c>package.mask</c>, <c>use.desc</c>
+ </li>
+ <li>
+ Updates directory, <c>profiles/updates/</c>
+ <ul>
+ <li>Updates files, for example <c>profiles/updates/1Q-2005</c></li>
+ </ul>
+ </li>
+ <li>
+ Main profile cascade
+ </li>
+ </ul>
+ </li>
+ <li>Scripts directory, <c>scripts/</c></li>
+ <li>
+ Distfiles directory, <c>distfiles/</c>. This is not included in the main
+ CVS tree, but it will be found on most user systems.
+ </li>
+ <li>
+ Packages directory, <c>packages</c>. Again, this is found on user systems but not
+ in the main CVS tree.
+ </li>
+</ul>
+</body>
+
+<section>
+<title>What Belongs in the Tree?</title>
+<body>
+
+<p>
+Things that do <b>not</b> belong in the tree:
+</p>
+
+<ul>
+ <li>Large patches</li>
+ <li>Non-text files</li>
+ <li>Photos of teletubbies</li>
+ <li>Files whose name starts with a dot</li>
+</ul>
+
+<p>
+Software-wise, in general all of the following should be met in order for a package to be included in the tree:
+</p>
+
+<dl>
+<dt>Active, Cooperative Upstream</dt>
+<dd>
+ <p>
+ If a package is undeveloped or unmaintained upstream, it can be extremely
+ difficult to get problems fixed. If a package does not have an active
+ upstream, the developers who add the package to the tree must ensure that
+ they are able to fix any issues which may arise.
+ </p>
+ <p>
+ Sometimes upstream may have a reason for not wanting their package included
+ in the tree. This should be respected.
+ </p>
+</dd>
+
+<dt>Reasonably Stable</dt>
+<dd>
+ <p>
+ Keep super-experimental things out of the tree. If you must commit them,
+ consider using ``package.mask`` until things calm down, or better yet make
+ them available as overlay ebuilds.
+ </p>
+</dd>
+
+<dt>Reasonably Useful</dt>
+<dd>
+ <p>
+ Don't feel obliged to include "Joe's '1337 XMMS Skinz Collection" or "Hans'
+ Super Cool Fast File System" in the tree just because a few users ask for
+ it. Stick to things that might actually be of use.
+ </p>
+</dd>
+
+<dt>Properly Packaged</dt>
+<dd>
+ <p>
+ If something is only available in live CVS or dodgy autopackage format,
+ don't include it until upstream can come up with a decent source package.
+ Similarly, avoid things that don't have a proper build system (where
+ relevant) -- these are very tricky to maintain.
+ </p>
+</dd>
+
+<dt>Patching and Distribution Permitted</dt>
+<dd>
+ <p>
+ If we can't patch packages as necessary ourselves, we end up relying
+ entirely upon upstream for support. This can be problematic, especially if
+ upstream are slow at fixing things. We don't want to be in the situation
+ where we can't stable a critical package because we're still waiting for a
+ closed-source vendor to get their act together.
+ </p>
+
+ <p>
+ Similarly, not being able to mirror and distribute tarballs ourselves makes
+ us rely entirely upon upstream mirrors. Experience has shown that these are
+ often extremely unreliable, with files changing, moving or vanishing at
+ random.
+ </p>
+</dd>
+
+<dt>Working Ebuilds</dt>
+<dd>
+ <p>
+ If you don't have a <e>working</e> ebuild, don't include it.
+ </p>
+</dd>
+
+<dt>Portable</dt>
+<dd>
+ <p>
+ If software is unportable, it's generally because it's badly written.
+ Remember that although x86 has a market majority <e>now</e>, it probably won't in
+ the not too distant future once x86-64 catches on.
+ </p>
+</dd>
+
+<dt>Reasonable Security Record</dt>
+<dd>
+ <p>
+ Don't include software that has a terrible security record. Each
+ vulnerability is a <e>lot</e> of work for a lot of people (security teams, arch
+ teams and package maintainers).
+ </p>
+</dd>
+</dl>
+
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
new file mode 100644
index 0000000..34ec457
--- /dev/null
+++ b/general-concepts/use-flags/text.xml
@@ -0,0 +1,230 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/use-flags/">
+<chapter>
+<title>USE Flags</title>
+
+<body>
+<p>
+USE flags are to control optional dependencies and settings which the user may
+reasonably want to select. For example, vim can optionally build with support for
+the ruby interpreter, and it needs ruby installed to do this -- we use the ruby USE
+flag to provide this option. On the other hand, glark requires ruby no matter what,
+so no USE flag is used here.
+</p>
+
+<p>
+No combination of USE flags should cause a package to fail to build.
+</p>
+
+<p>
+Packages should not configure and link based upon what is available at compile time
+-- any autodetection must be overridden.
+</p>
+</body>
+
+<section>
+<title><c>noblah</c> USE Flags</title>
+<body>
+<p>
+If at all possible, avoid <c>noblah</c> style USE flags. These break <c>use.mask</c>
+and cause all sorts of complications for arch developers. Here's why:
+</p>
+
+<p>
+Consider a hypothetical package named 'vplayer', which plays videos. This
+package has optional support, via USE flags, for various sound and video output
+methods, various video codecs and so on.
+</p>
+
+<p>
+One of vplayer's optional features is support for the 'fakemedia' codec, which
+is unfortunately only available as a dodgy x86 binary. We <e>could</e> handle this by
+doing something like:
+</p>
+
+<codesample lang="ebuild">
+RDEPEND="x86? ( fakemedia? ( >=media-libs/fakemedia-1.1 ) )"
+</codesample>
+
+<p>
+Except this is pretty nasty -- what happens when an AMD64 binary is made as
+well? Also, users on other archs will see fakemedia listed in <c>emerge -pv</c>
+output, even though it is not actually available.
+</p>
+
+<p>
+Similarly, say vplayer supports output via the ALSA codec as one option.
+However, ALSA isn't (or wasn't when this example was written) available on SPARC
+or Alpha. So we could do:
+</p>
+
+<codesample lang="ebuild">
+DEPEND="!sparc? ( !alpha? ( alsa? ( media-libs/alsa-lib ) ) )"
+</codesample>
+
+<p>
+Again, it's messy, and ALSA still shows up in the <c>emerge -p</c> output. Also,
+once ALSA starts working on SPARC, every ebuild that does this would have to be
+manually edited.
+</p>
+
+<p>
+The solution is <c>use.mask</c>, which is documented in `Profiles use.mask File`_.
+Each profile can have a <c>use.mask</c> file which can be used to forcibly disable
+certain USE flags on a given arch (or subarch, or subprofile). So, if the
+<c>fakemedia</c> USE flag was use.masked on every non-x86 profile, the following
+would be totally legal and wouldn't break anything:
+</p>
+
+<codesample lang="ebuild">
+RDEPEND="fakemedia? ( >=media-libs/fakemedia-1-1 )"
+</codesample>
+
+<p>
+Users of non-x86 would see the following when doing <c>emerge -pv vplayer</c>:
+</p>
+
+<pre>
+[ebuild R ] media-video/vplayer-1.2 alsa -blah (-fakemedia) xyz
+</pre>
+
+<p>
+To get a flag added to <c>use.mask</c>, ask the relevant arch team.
+</p>
+
+<p>
+So what's the problem with <c>noblah</c> flags?
+</p>
+
+<p>
+There's no way to forcibly <e>enable</e> a given USE flag on a particular profile.
+So, something like:
+</p>
+
+<codesample lang="ebuild">
+RDEPEND="!noalsa? ( media-libs/alsa )"
+</codesample>
+
+<p>
+will make your package unusable by archs without ALSA support, and there is no
+way to fix it that doesn't involve adding in nasty <c>arch?</c> flags.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Local and Global USE Flags</title>
+<body>
+
+<p>
+USE flags are categorised as either local or global. A global USE flag must satisfy several criteria:
+</p>
+
+<ul>
+ <li>It is used by many different packages.</li>
+ <li>It has a general non-specific purpose.</li>
+</ul>
+
+<p>
+The second point is important. If the effect of the <c>thing</c> USE flag upon
+<c>pkg-one</c> is substantially different from the effect it has upon <c>pkg-two</c>,
+then <c>thing</c> is not a suitable candidate for being made a global flag. In
+particular, note that if <c>client</c> and <c>server</c> USE flags are ever
+introduced, they can not be global USE flags for this reason.
+</p>
+
+<p>
+Before introducing a new global USE flag, it must be discussed on the gentoo-dev
+mailing list.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>USE Flag Descriptions</title>
+<body>
+<p>
+All USE flags (excluding <c>USE_EXPAND</c> flags) must be described in either
+<c>use.desc</c> or <c>use.local.desc</c> in the <c>profiles/</c> directory. See
+`portage-5`_ or the comments in these files for an explanation of the format.
+Remember to keep these files sorted.
+</p>
+</body>
+</section>
+
+<section>
+<title>Conflicting USE Flags</title>
+<body>
+<p>
+Occasionally, ebuilds will have conflicting USE flags for functionality.
+Checking for them and returning an error is <e>not</e> a viable solution. Instead,
+you must pick one of the USE flags in conflict to favour.
+</p>
+
+<p>
+One example comes from the <c>msmtp</c> ebuilds. The package can use either SSL
+with GnuTLS, SSL with OpenSSL, or no SSL at all. Because GnuTLS is more
+featureful than OpenSSL, it is favoured:
+</p>
+
+<codesample lang="ebuild">
+src_compile() {
+ local myconf
+
+ if use ssl &amp;&amp; use gnutls ; then
+ myconf="${myconf} --enable-ssl --with-ssl=gnutls"
+ elif use ssl &amp;&amp; ! use gnutls ; then
+ myconf="${myconf} --enable-ssl --with-ssl=openssl"
+ else
+ myconf="${myconf} --disable-ssl"
+ fi
+
+ econf \
+ # Other stuff
+ ${myconf} \
+ || die "configure failed"
+
+ emake || die "make failed"
+}
+</codesample>
+</body>
+</section>
+
+<section>
+<title>USE_EXPAND and ARCH USE Flags</title>
+<body>
+
+<p>
+The <c>VIDEO_CARDS</c>, <c>INPUT_DEVICES</c> and <c>LINGUAS</c> variables are
+automatically expanded into USE flags. These are known as <c>USE_EXPAND</c>
+variables. If the user has <c>LINGUAS="en fr"</c> in <c>make.conf</c>, for example,
+then <c>USE="linguas_en linguas_fr"</c> will automatically be set by portage.
+</p>
+
+<p>
+The <c>USE_EXPAND</c> list is set in <c>profiles/base/make.default</c> as of Portage
+2.0.51.20. This must not be modified without discussion on the gentoo-dev list,
+and it must not be modified in any subprofile.
+</p>
+
+<p>
+The current architecture (e.g. <c>x86</c>, <c>sparc</c>, <c>ppc-macos</c>) will
+automatically be set as a USE flag as well. See <c>profiles/arch.list</c> for a
+full list of valid architecture keywords, and `GLEP 22`_ for an explanation of
+the format.
+</p>
+
+<warning>
+It is a common misconception that the architecture variable is somehow
+related to <c>ACCEPT_KEYWORDS</c>. It isn't. Accepting <c>x86</c> keywords on
+<c>sparc</c>, for example, won't set <c>USE="x86"</c>. Similarly, there are no
+<c>~arch</c> USE flags, so don't try <c>if use ~x86</c>.
+</warning>
+
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/general-concepts/user-environment/text.xml b/general-concepts/user-environment/text.xml
new file mode 100644
index 0000000..d1a5431
--- /dev/null
+++ b/general-concepts/user-environment/text.xml
@@ -0,0 +1,88 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/user-environment/">
+<chapter>
+<title>User Environment</title>
+
+<body>
+<p>
+User environment variables and <c>make.conf</c> settings get passed on to ebuilds.
+This can be useful -- it's how <c>CFLAGS</c> and friends work, for example -- but
+it can also result in nasty build-breaking variables like <c>LANG</c> and
+<c>LC_ALL</c> getting through. Currently no sanitisation is performed upon the
+environment.
+</p>
+</body>
+
+<section>
+<title>Filtering Variables</title>
+<body>
+<p>
+Certain variables will really really upset certain build systems. A good example
+is the locale variables (<c>LC_ALL</c> et al), which if set to certain values will
+cause <c>sed</c> or <c>grep</c> expressions involving the likes of <c>[A-Z]</c> to fail.
+The easiest thing to do here is to <c>unset</c> or sanitise the offending variables
+inside <c>pkg_setup</c>.
+</p>
+
+<p>
+The simplest way to unset all locale-related variables is:
+</p>
+
+<codesample lang="ebuild">
+pkg_setup() {
+ # Unset all locale related variables, they can make the
+ # build fail.
+
+ eval unset ${!LC_*} LANG
+}
+</codesample>
+</body>
+</section>
+
+<section>
+<title>Not Filtering Variables</title>
+<body>
+<p>
+On the other hand, it is extremely important that certain user preferences are
+honoured as far as possible. A good example is <c>CFLAGS</c>, which <e>must</e> be
+respected (selective filtering is fine, but outright ignoring is not). Ignoring
+<c>CFLAGS</c> when compiling can cause serious problems:
+</p>
+
+<ul>
+<li>
+ Ignoring <c>march/mcpu</c> may force kernel or software emulation for certain
+ opcodes on some architectures. This can be *very* slow -- for example,
+ <c>openssl</c> built for SPARC v7 but run on v9 is around five times slower for
+ RSA operations.
+</li>
+
+<li>
+ Stripping certain ABI-related flags will break linkage.
+</li>
+
+<li>
+ Stripping certain ABI-related flags will result in invalid code being produced
+ for certain setups. In extreme cases, we could end up with daft things like
+ big endian code being produced for little endian CPUs.
+</li>
+
+<li>
+ If a user's <c>march/mcpu/mtune</c> is ignored, and an auto-detected setting is
+ used instead, GRP and stages will break. For example, <c>i686</c> stages could no
+ longer be produced on a <c>pentium-4</c>, and <c>v8</c> stages could no longer be
+ produced on an <c>UltraSparc</c>.
+</li>
+</ul>
+
+<p>
+Some packages do this by accident. For example, one might see
+<c>CFLAGS=-Wall</c> in <c>Makefile.am</c>. To fix this, either <c>sed</c> in the user's
+<c>CFLAGS</c>, or (the better solution) change the variable to <c>AM_CFLAGS</c>, which
+will automatically be merged with the user's settings.
+</p>
+</body>
+</section>
+
+</chapter>
+</guide>