initial import2.1

11 files changed, 2508 insertions, 0 deletions

diff --git a/doc/handbook/Makefile b/doc/handbook/Makefile
new file mode 100644
index 0000000..5a70059
--- /dev/null
+++ b/doc/handbook/Makefile
@@ -0,0 +1,61 @@
+#
+# Makefile for CRUX Handbook
+# Copyright (c) 2003-2005 Per Liden <per@fukt.bth.se>
+#
+
+# Requirements:
+#   - libxml2
+#   - libxslt
+#   - links/elinks
+#   - fop		 (http://xml.apache.org/fop/)
+#   - docbook-xsl 1.58.1 (http://docbook.sourceforge.net/projects/xsl/)
+#   - docbook-xml 4.2    (http://www.oasis-open.org/docbook/xml/)
+
+CHAPTERS = intro.xml \
+           install.xml \
+           package.xml \
+           ports.xml \
+           configure.xml \
+           faq.xml
+
+HTML_TARGET	= handbook.html
+TXT_TARGET      = handbook.txt
+PDF_TARGET	= handbook.pdf
+HTML_XSL	= html.xsl
+PDF_XSL		= pdf.xsl
+
+all: html txt pdf
+
+html: $(HTML_TARGET)
+
+txt: $(TXT_TARGET)
+
+pdf: $(PDF_TARGET)
+
+$(HTML_TARGET): $(HTML_XSL) $(CHAPTERS)
+
+$(TXT_TARGET): $(HTML_TARGET)
+
+$(PDF_TARGET): $(PDF_XSL) $(CHAPTERS)
+
+%.html: %.xml
+	xsltproc -o $@ $(HTML_XSL) $<
+
+%.txt: %.html
+	links -dump -no-numbering -dump-width 80 $< > $@
+
+%.pdf: %.fo
+	fop -q -fo $< -pdf $@
+
+%.fo: %.xml
+	xsltproc -o $@ $(PDF_XSL) $<
+
+publish:
+	scp $(HTML_TARGET) $(TXT_TARGET) $(PDF_TARGET) tower:www/crux/doc/
+
+clean:
+	@if [ -f $(HTML_TARGET) ]; then rm $(HTML_TARGET); fi
+	@if [ -f $(TXT_TARGET) ]; then rm $(TXT_TARGET); fi
+	@if [ -f $(PDF_TARGET) ]; then rm $(PDF_TARGET); fi
+
+# End of file.
diff --git a/doc/handbook/configure.xml b/doc/handbook/configure.xml
new file mode 100644
index 0000000..cc8f947
--- /dev/null
+++ b/doc/handbook/configure.xml
@@ -0,0 +1,387 @@
+<!-- $Id: configure.xml,v 1.4 2004/05/08 19:57:39 per Exp $ -->
+
+<title>Configuration</title>
+
+<section id="Initialization-Scripts">
+  <title>Initialization Scripts</title>
+
+  <section id="Runlevels">
+    <title>Runlevels</title>
+
+    <para>The following runlevels are used in CRUX (defined in
+      <filename>/etc/inittab</filename>).</para>
+
+    <informaltable>
+      <tgroup cols="2">
+        <thead>
+          <row>
+            <entry>Runlevel</entry>
+            <entry>Description</entry>
+          </row>
+        </thead>
+
+        <tbody>
+          <row>
+            <entry>0</entry>
+
+            <entry>Halt</entry>
+          </row>
+
+          <row>
+            <entry>1 (S)</entry>
+            <entry>Single-user Mode</entry>
+          </row>
+
+          <row>
+            <entry>2</entry>
+
+            <entry>Multi-user Mode</entry>
+          </row>
+
+          <row>
+            <entry>3-5</entry>
+
+            <entry>(Not used)</entry>
+          </row>
+
+          <row>
+            <entry>6</entry>
+
+            <entry>Reboot</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </informaltable>
+  </section>
+
+  <section id="Layout">
+    <title>Layout</title>
+
+    <para>The initialization scripts used in CRUX follow the BSD-style
+      (as opposed to the SysV-style) and have the following
+      layout.</para>
+
+    <informaltable>
+      <tgroup cols="2">
+        <thead>
+          <row>
+            <entry>File</entry>
+
+            <entry>Description</entry>
+          </row>
+        </thead>
+
+        <tbody>
+          <row>
+            <entry><filename>/etc/rc</filename></entry>
+
+            <entry>System boot script</entry>
+          </row>
+
+          <row>
+            <entry><filename>/etc/rc.single</filename></entry>
+
+            <entry>Single-user startup script</entry>
+          </row>
+
+          <row>
+            <entry><filename>/etc/rc.modules</filename></entry>
+
+            <entry>Module initialization script</entry>
+          </row>
+
+          <row>
+            <entry><filename>/etc/rc.multi</filename></entry>
+
+            <entry>Multi-user startup script</entry>
+          </row>
+
+          <row>
+            <entry><filename>/etc/rc.local</filename></entry>
+
+            <entry>Local multi-user startup script (empty by
+              default)</entry>
+          </row>
+
+          <row>
+            <entry><filename>/etc/rc.shutdown</filename></entry>
+
+            <entry>System shutdown script</entry>
+          </row>
+
+          <row>
+            <entry><filename>/etc/rc.conf</filename></entry>
+
+            <entry>System configuration</entry>
+          </row>
+
+          <row>
+            <entry><filename>/etc/rc.d/</filename></entry>
+
+            <entry>Service start/stop script directory</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </informaltable>
+
+    <para>Modify <filename>/etc/rc.modules</filename>, <filename
+      >/etc/rc.local</filename> and <filename>/etc/rc.conf</filename>
+      according to your needs.</para>
+  </section>
+
+  <section id="Configuration-Variables-in-rc.conf">
+    <title>Configuration Variables in <filename
+      >/etc/rc.conf</filename></title>
+
+    <para>The following configuration variables are found in
+      <filename>/etc/rc.conf</filename>.</para>
+
+    <informaltable>
+      <tgroup cols="2">
+        <thead>
+          <row>
+            <entry>Variable</entry>
+
+            <entry>Description</entry>
+          </row>
+        </thead>
+
+        <tbody>
+          <row>
+            <entry><literal>FONT</literal></entry>
+
+            <entry>
+              <para>Specifies which console font to load at system
+                startup. The contents of this variable will be passed
+                as argument to <userinput>setfont(1)</userinput>.
+                The available fonts are located in <filename
+                >/usr/share/kbd/consolefonts/</filename>.</para>
+
+              <para>Example: <literal
+                >FONT=default</literal></para>
+            </entry>
+          </row>
+
+          <row>
+            <entry><literal>KEYMAP</literal></entry>
+
+            <entry>
+              <para>Specifies which console keyboard map to load at system
+                startup. The contents of this variable will be passed
+                as argument to <userinput>loadkeys(1)</userinput>.
+                The available keyboard maps are located in <filename
+                >/usr/share/kbd/keymaps/</filename>.</para>
+
+              <para>Example: <literal
+                >KEYMAP=sv-latin1</literal></para>
+            </entry>
+          </row>
+
+          <row>
+            <entry><literal>TIMEZONE</literal></entry>
+
+            <entry>
+              <para>Specifies the timezone used by the system. The
+                available zone description files are located in 
+                <filename>/usr/share/zoneinfo/</filename>.</para>
+              <para>Example: <literal
+                >TIMEZONE=Europe/Stockholm</literal></para>
+            </entry>
+          </row>
+
+          <row>
+            <entry><literal>HOSTNAME</literal></entry>
+
+            <entry>
+              <para>Specifies the hostname.</para>
+
+              <para>Example: <literal>HOSTNAME=pluto</literal></para>
+            </entry>
+          </row>
+
+<!--
+OBSOLETE SECTION
+          <row>
+            <entry><literal>IFCONFIG_UP</literal></entry>
+
+            <entry>
+              <para>Specifies network interface configuration
+                commands. When entering multi-user mode the strings
+                specified in this array will one by one be passed as
+                arguments to <userinput
+                >ifconfig(8)</userinput>.</para>
+
+              <para>Example:</para>
+
+<programlisting>IFCONFIG_UP=("lo 127.0.0.1" \
+             "eth0 195.38.1.140 netmask 255.255.255.224" \
+             "eth1 192.168.0.1 netmask 255.255.255.0")</programlisting>
+            </entry>
+          </row>
+
+          <row>
+            <entry><literal>IFCONFIG_DOWN</literal></entry>
+
+            <entry>
+              <para>Specifies network interface shutdown commands.
+                At system shutdown or when entering single-user mode
+                the strings specified in this arrat will one by one be
+                passed as arguments to <userinput
+                >ifconfig(8)</userinput>.</para>
+
+              <para>Example:</para>
+
+<programlisting
+    >IFCONFIG_DOWN=("lo down" "eth0 down" "eth1 down")</programlisting></entry>
+          </row>
+
+          <row>
+            <entry><literal>ROUTE</literal></entry>
+
+            <entry>
+              <para>Specifies network route configuration commands.
+                When entering multi-user mode the strings in
+                specified in this array will one by one be passed as
+                arguments to <userinput>route(8)</userinput>.</para>
+
+              <para>Example:</para>
+
+<programlisting>ROUTE=("add default gw 195.38.1.129")</programlisting></entry>
+          </row>
+END OBSOLETE SECTION
+-->
+
+          <row>
+            <entry><literal>SERVICES</literal></entry>
+
+            <entry>
+              <para>Specifies which services to start at system
+                startup. The services specified in this array must
+                have a matching start/stop script in <filename
+                >/etc/rc.d/</filename>. When entering multi-user mode
+                the specified scripts will be called in the specified
+                order with the argument <userinput>start</userinput>.
+                At system shutdown or when entering single-user mode
+                these scripts will be called in the reverse order with
+                the argument <userinput>stop</userinput>.</para>
+
+              <para>Example: <literal>SERVICES=(crond identd sshd sendmail)</literal></para>
+            </entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </informaltable>
+  </section>
+
+  <section id="Network-Configuration">
+    <title>Network Configuration</title>
+
+    <para>The network configuration is found in the service script
+      <filename>/etc/rc.d/net</filename>. To enable this service you
+      need to add <literal>net</literal> to the <literal
+      >SERVICES</literal> array in <filename>/etc/rc.conf</filename>.
+      By default this service script only configures the <filename
+      >lo</filename> device, you have to add additional <userinput
+      >ifconfig(8)</userinput> and <userinput>route(8)</userinput>
+      commands if you want to setup other network devices (<filename
+      >eth0</filename>, <filename>eth1</filename>, etc).
+      Example:</para>
+
+    <informalexample>
+<programlisting>#!/bin/sh
+#
+# /etc/rc.d/net: start/stop network
+#
+
+case $1 in
+start)
+        /sbin/ifconfig lo 127.0.0.1
+        /sbin/ifconfig eth0 195.38.1.140 netmask 255.255.255.224
+        /sbin/ifconfig eth1 192.168.0.1 netmask 255.255.255.0
+        /sbin/route add default gw 195.38.1.129
+        ;;
+stop)
+        /sbin/ifconfig eth1 down
+        /sbin/ifconfig eth0 down
+        /sbin/ifconfig lo down
+        ;;
+restart)
+        $0 stop
+        $0 start
+        ;;
+*)
+        echo "usage: $0 [start|stop|restart]"
+        ;;
+esac
+
+# End of file</programlisting>
+    </informalexample>
+
+    <para>If you want to configure your system to be a DHCP client you
+      use the <userinput>dhcpcd(8)</userinput> command (istead of
+      <command>ifconfig(8)</command>). Example:</para>
+
+    <informalexample>
+<programlisting>#!/bin/sh
+#
+# /etc/rc.d/net: start/stop network
+#
+
+case $1 in
+start)
+        /sbin/ifconfig lo 127.0.0.1
+        /sbin/dhcpcd eth0 <replaceable>[add additional options if needed]</replaceable>
+        ;;
+stop)
+        killall -q /sbin/dhcpcd
+        /sbin/ifconfig lo down
+        ;;
+restart)
+        $0 stop
+        $0 start
+        ;;
+*)
+        echo "usage: $0 [start|stop|restart]"
+        ;;
+esac
+
+# End of file</programlisting>
+    </informalexample>
+  </section>
+</section>
+
+<section id="Passwords">
+  <title>Passwords</title>
+
+  <para>CRUX uses MD5SUM passwords by default. This can be turned off
+    if you instead want to use the traditional DES passwords. Note
+    however that DES passwords are considered less secure. To disable
+    MD5SUM passwords change the <literal>MD5_CRYPT_ENAB</literal>
+    variable in <filename>/etc/login.defs</filename> to <literal
+    >no</literal>.</para>
+
+  <para>Further, when compiling programs that use the <literal
+    >crypt(3)</literal> function to authenticate users you should make
+    sure that these programs are linked against the <filename
+    >libcrypt</filename> library (i.e. use <userinput
+    >-lcrypt</userinput> when linking) which contains the MD5SUM
+    version of the <literal>crypt</literal> function (this version is
+    backwards compatible and understands DES passwords as
+    well).</para>
+</section>
+
+<section id="Upgrading-the-Kernel">
+  <title>Upgrading the Kernel</title>
+
+  <para>The kernel source, which is found in <filename
+    >/usr/src/linux-&kernel;/</filename> is not installed using <userinput
+    >pkgadd</userinput>. If you decide to upgrade your kernel you can
+    safely do so by manually replacing the kernel source with a newer
+    version (or place it somewhere else). This will not make the
+    package database inconsistent (since it's not installed with
+    <userinput>pkgadd</userinput>) nor will it affect the kernel
+    headers found in <filename>/usr/include/linux</filename> and
+    <filename>/usr/include/asm</filename> since these are not
+    symlinks to the kernel source, but instead contain copies of the
+    headers.</para>
+</section>
diff --git a/doc/handbook/faq.xml b/doc/handbook/faq.xml
new file mode 100644
index 0000000..1c14079
--- /dev/null
+++ b/doc/handbook/faq.xml
@@ -0,0 +1,178 @@
+<!-- $Id: faq.xml,v 1.6 2004/05/28 11:30:00 per Exp $ -->
+
+<title>Frequently Asked Questions</title>
+
+<section id="Frequently-Asked-Questions-General">
+  <title>General</title>
+
+  <procedure>
+    <step>
+      <title>Why the name <quote>CRUX</quote>?</title>
+
+      <para>Sorry, there's no interesting story behind the name.
+	I chose it simply because I thought it sounded cool, it was short,
+	it was failry easy to remember and it had the mandatory X in the end
+	to make it UNIX/Linux-ish ;)</para>
+    </step>
+
+    <step>
+      <title>When will the next version be released?</title>
+
+      <para>Well, the standard answer to this question is
+        <quote>when it's done</quote>. New versions are however
+        usually released every 3 or 4 months. Between releases,
+        updated packages are made available through the ports
+        system.</para>
+    </step>
+
+    <step>
+      <title>Is it called CRUX Linux or CRUX GNU/Linux?</title>
+
+      <para>None of the above. It's called CRUX, no more no less.</para>
+    </step>
+
+    <step>
+      <title>I heard CRUX was based on Slackware, is that true?</title>
+
+      <para>No, that's incorrect. CRUX was built from scratch and has never
+        been based on any other Linux distribution.</para>
+    </step>
+  </procedure>
+</section>
+
+<section id="Frequently-Asked-Questions-Installation">
+  <title>Installation</title>
+
+  <procedure>
+    <step>
+      <title>Will CRUX work with AMD K6/K6-II/K6-III?</title>
+
+      <para>Yes and No. AMD K6, K6-II and K6-III have an i586
+        (Pentium) compatible instruction set. Packages on the official
+        CRUX ISO are compiled with <userinput
+        >-march=i686</userinput>, which means that CRUX requires a
+        processor which has an i686 compatible instruction set (i.e.
+        Intel PPro/Celeron/PII/PIII/P4 or AMD K7/Athlon). However,
+        J&uuml;rgen Daubert maintains an i586 version of the CRUX ISO
+        image which can be found <ulink url="ftp://ftp.fukt.bth.se/pub/os/linux/crux/latest/contrib/"
+        >here</ulink>. The i586 version of the CRUX ISO works on AMD
+        K6/K6-II/K6-III.</para>
+    </step>
+
+    <step>
+      <title>When booting from the CRUX CD-ROM I get a kernel panic
+        saying <quote>VFS: Unable to mount root fs</quote>. What's
+        wrong?</title>
+
+      <para>This can happen if you have more than one CD-ROM drive.
+        Make sure you boot from then "first" CD-ROM drive, i.e.
+        <filename>/dev/cdroms/cdrom0</filename>. If you must boot from
+        a different drive (i.e. not the first one) you can still do
+        that but you have to type <userinput>CRUX
+        root=/dev/cdroms/cdrom1</userinput> at the boot prompt
+        (<userinput>cdrom1</userinput> indicates that it is the
+        second drive, <userinput>cdrom2</userinput> that it is the
+        third, and so on).</para>
+    </step>
+
+    <step>
+      <title>When booting CRUX for the first time I get the error
+        <quote>Unable to open initial console</quote>. What's
+        wrong?</title>
+
+      <para>You most likely forgot to enable devfs or didn't tell the
+        kernel to mount devfs at boot. The installation instructions
+        (<xref linkend="Installing-From-CD-ROM"/>) tell you how to
+        enable it.</para>
+    </step>
+
+    <step>
+      <title>When logging in to my newly installed CRUX for the first
+        time it asks for a password, but the installation guide says
+        <quote>Login as  root (no password required)</quote>. What's
+        wrong?</title>
+
+      <para>You most likely forgot to edit <filename
+        >/mnt/etc/fstab</filename> before you rebooted or you entered
+        the wrong name of your new root parition at the boot
+        prompt.</para>
+    </step>
+  </procedure>
+</section>
+
+<section id="Frequently-Asked-Questions-Configuration">
+  <title>Configuration</title>
+
+  <procedure>
+    <step>
+      <title>Why are changes made to files under <filename
+        >/dev</filename> lost the next time I boot into CRUX?</title>
+
+      <para>CRUX uses <literal>devfs</literal>, which is a virtual
+        filsystem kept in RAM. Changes made to files under <filename
+        >/dev</filename> are always lost when you turn off the power.
+        However, you can configure <userinput>devfsd(8)</userinput>
+        to restore them when you boot. You need to modify <filename
+        >/etc/devfsd.conf</filename> according to your needs. See the
+        <userinput>devfsd(8)</userinput> man-page for details.
+        Example:</para>
+
+      <informalexample>
+<programlisting>#
+# /etc/devfsd.conf: devfsd(8) configuration
+#
+
+REGISTER        .*              MKOLDCOMPAT
+UNREGISTER      .*              RMOLDCOMPAT
+
+LOOKUP          .*              MODLOAD
+
+REGISTER        ^sound/.*       PERMISSIONS root.users 660
+REGISTER        ^v4l/.*         PERMISSIONS root.users 660
+
+# End of file</programlisting>
+      </informalexample>
+    </step>
+
+    <step>
+      <title>How do I get sshd running?</title>
+
+      <para>You have to edit <filename>/etc/hosts.deny</filename>
+        and/or <filename>/ets/hosts.allow</filename> to specify which
+        hosts are allowed/denied access. To allow anyone to connect
+        to your machine you can add <literal>sshd: ALL</literal> to
+        <filename>/etc/hosts.allow</filename>. See the
+        <literal>hosts_access(5)</literal> man-page for further
+        information about the file format. When this is done you can
+        start sshd by entering the command <userinput>/etc/rc.d/sshd
+        start</userinput> and/or edit <filename
+        >/etc/rc.conf</filename> and add <literal>sshd</literal> to
+        the <literal>SERVICES</literal> array, i.e. <literal
+        >SERVICES=(<replaceable
+        >...</replaceable>&nbsp;sshd&nbsp;<replaceable
+        >...</replaceable>)</literal>, which means that sshd will be
+        started when the system boots.</para>
+    </step>
+
+    <step>
+      <title>Mozilla crashes or refuses to start, what's wrong?</title>
+
+      <para>Mozilla is extremely sensitive to missing <filename
+        >fonts.cache-1</filename> files. If mozilla refuses to start
+        (due to segmentation violation or just silent permature
+        termination) it is most likely becuase the font cache files
+        are missing. Run <userinput>fc-cache</userinput> (as
+        <userinput>root</userinput>) to create/update the cache files.
+        See the <userinput>fc-cache(1)</userinput> man page for
+        information about this program.</para>
+    </step>
+
+    <step>
+      <title>It says <quote><literal>ports: no driver(s) installed</literal></quote> when
+	I try to update my ports, what's wrong?</title>
+
+      <para>You forgot to install the <filename>opt/cvsup</filename> package. You will find
+	it on the CRUX ISO (under <filename>/crux/opt/</filename>).</para>
+    </step>
+  </procedure>
+</section>
diff --git a/doc/handbook/handbook.css b/doc/handbook/handbook.css
new file mode 100644
index 0000000..aacd8b3
--- /dev/null
+++ b/doc/handbook/handbook.css
@@ -0,0 +1,167 @@
+/*
+ * Copyright (c) 2001 The FreeBSD Documentation Project
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ *
+ * $FreeBSD: doc/share/misc/docbook.css,v 1.4 2001/07/11 12:46:50 nik Exp $
+ * 
+ * Modified by: Rob McMeekin <viper@mcmeekin.info>
+ *   Thu Nov 28 16:21:01 EST 2002
+ *
+ * Modified by: Per Liden <per@fukt.bth.se>
+ *   Sat Jan 18 18:16:37 CET 2003
+ */
+
+BODY ADDRESS {
+	line-height: 1.3;
+	margin: .6em 0;
+}
+
+blockquote {
+	margin-top: .75em;
+	line-height: 1.5;
+	margin-bottom: .75em;
+}
+
+body {
+	margin: 1em 8% 1em 10%;
+	line-height: 1.2;
+	background-color: #ffffff;
+}
+
+.legalnotice {
+	font-size: small;
+	font-variant: small-caps;
+}
+
+div {
+	margin: 0;
+}
+
+dl {
+	margin: .8em 0;
+	line-height: 1.2;
+}
+
+form {
+	margin: .6em 0;
+}
+
+h1, h2, h3, h4 {
+	color: #990000;
+}
+
+h1 {
+	margin: .8em 0 0 -4%;
+	line-height: 1.3;
+}
+
+h2 {
+	margin: .8em 0 0 -4%;
+	line-height: 1.3;
+}
+
+h3 {
+	margin: .8em 0 0 -3%;
+	line-height: 1.3;
+}
+
+h4 {
+	margin: .8em 0 0 -3%;
+	line-height: 1.3;
+}
+
+h5 {
+	margin: .8em 0 0 -2%;
+	line-height: 1.3;
+}
+
+h6 {
+	margin: .8em 0 0 -1%;
+	line-height: 1.3;
+}
+
+/*
+hr {
+	margin: .6em
+}
+*/
+
+img.navheader {
+	margin: 0 0 0 -4%;
+}
+
+ol {
+	margin: 0 0 0 5%;
+	line-height: 1.2;
+}
+
+p {
+	margin: .6em 0;
+	line-height: 1.2;
+}
+
+pre {
+	margin: .75em 0;
+	line-height: 1.0;
+	color: #461b7e;
+}
+
+td {
+	line-height: 1.2
+}
+
+th {
+	line-height: 1.2;
+}
+
+ul, dir, menu {
+	margin: 0 0 0 5%;
+	line-height: 1.2;
+}
+
+html {
+	margin: 0; 
+	padding: 0;
+}
+
+
+h1, h2, h3, h4, h5, h6 {
+	margin-left: 0
+} 
+
+.programlisting {
+        margin: 1em 5% 1em 5%;
+	color: #000000;
+        background-color: #eeeeee;
+}
+
+.filename {
+	color: #007a00;
+}
+
+/*
+.literal {
+	color: #007a88;
+}
+*/
diff --git a/doc/handbook/handbook.xml b/doc/handbook/handbook.xml
new file mode 100644
index 0000000..b052aba
--- /dev/null
+++ b/doc/handbook/handbook.xml
@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!-- $Id: handbook.xml,v 1.11 2005/03/27 21:36:13 per Exp $ -->
+
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+<!ENTITY intro     SYSTEM "intro.xml">
+<!ENTITY install   SYSTEM "install.xml">
+<!ENTITY package   SYSTEM "package.xml">
+<!ENTITY ports     SYSTEM "ports.xml">
+<!ENTITY configure SYSTEM "configure.xml">
+<!ENTITY faq       SYSTEM "faq.xml">
+
+<!ENTITY crux    "2.1">
+<!ENTITY kernel  "2.6.11.7">
+
+]>
+
+<book>
+  <bookinfo>
+    <title>CRUX Handbook</title>
+    <subtitle>RELEASE &crux;</subtitle>
+    <pubdate><?dbtimestamp format="Y-m-d"?></pubdate>
+
+    <copyright>
+      <year>2001</year>
+      <year>2002</year>
+      <year>2003</year>
+      <year>2004</year>
+      <year>2005</year>
+      <holder>
+        <ulink url="mailto:per@fukt.bth.se">Per Lid&eacute;n</ulink>
+      </holder>
+    </copyright>
+
+    <abstract>
+      <title></title>
+
+      <para>This handbook covers the installation, configuration and
+        administration of CRUX. Please note that this handbook only
+        covers topics that are specific to <ulink
+        url="http://crux.nu/">CRUX</ulink>. For further information
+        about Linux see the <ulink url="http://www.tldp.org/">Linux
+        Documentation Project</ulink>.</para>
+    </abstract>
+  </bookinfo>
+
+  <preface id="Preface">
+    <title>Preface</title>
+
+    <para><ulink url="mailto:per@fukt.bth.se"
+      >Per Lid&eacute;n</ulink> wrote this handbook. <ulink
+      url="mailto:viper@mcmeekin.info">Robert McMeekin</ulink>
+      converted it to DocBook. Numerous others have given feedback
+      and improvement suggestions.</para>
+  </preface>
+
+  <chapter id="Introduction">
+    &intro;
+  </chapter>
+
+  <chapter id="Installing-CRUX">
+    &install;
+  </chapter>
+
+  <chapter id="The-Package-System">
+    &package;
+  </chapter>
+
+  <chapter id="The-Ports-System">
+    &ports;
+  </chapter>
+
+  <chapter id="Configuration">
+    &configure;
+  </chapter>
+
+  <chapter id="Frequently-Asked-Questions">
+    &faq;
+  </chapter>
+</book>
diff --git a/doc/handbook/html.xsl b/doc/handbook/html.xsl
new file mode 100644
index 0000000..955b3d0
--- /dev/null
+++ b/doc/handbook/html.xsl
@@ -0,0 +1,19 @@
+<?xml version='1.0'?>
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+
+<xsl:import href="/usr/share/xml/docbook/xsl/html/docbook.xsl"/>
+
+<xsl:param name="html.stylesheet" select="'handbook.css'"/>
+<xsl:param name="admon.graphics" select="1"/>
+<xsl:param name="chapter.autolabel" select="1"/>
+<xsl:param name="section.autolabel" select="1"/>
+<xsl:param name="section.label.includes.component.label" select="2"/>
+<xsl:param name="generate.toc">book toc,title</xsl:param>
+<xsl:template match="filename|literal">
+  <span class="{name(.)}">
+    <xsl:call-template name="inline.monoseq"/>
+  </span>
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/doc/handbook/install.xml b/doc/handbook/install.xml
new file mode 100644
index 0000000..84a6d71
--- /dev/null
+++ b/doc/handbook/install.xml
@@ -0,0 +1,500 @@
+<!-- $Id: install.xml,v 1.7 2005/03/27 21:36:13 per Exp $ -->
+
+<title>Installing CRUX</title>
+
+<section id="Supported-Harware">
+  <title>Supported Hardware</title>
+
+  <para>Packages on the official CRUX ISO image are compiled with
+    optimization for i686 (Pentium-Pro/Celeron/Pentium-II or better)
+    processors. Do <emphasis>not</emphasis> try to install it on an
+    i586 (Pentium, AMD K6/K6-II/K6-III) or lower processor, since
+    it simply	will not work. To install CRUX on an i586 system you
+    need to download the i586 version of the CRUX ISO image.</para>
+
+  <para>The kernel used during installation, i.e. when booting from
+    the CRUX ISO image (El Torito), is compiled with the following
+    disk controllers and USB support:</para>
+
+  <informaltable>
+    <tgroup cols="2">
+      <thead>
+        <row>
+          <entry>Subsystem</entry>
+
+          <entry>Driver(s) included in bootkernel</entry>
+        </row>
+      </thead>
+
+      <tbody>
+        <row>
+          <entry>IDE</entry>
+
+          <entry>Generic PCI IDE chipset</entry>
+        </row>
+
+        <row>
+          <entry>SATA</entry>
+
+          <entry>ServerWorks Frodo/Apple K2, Intel PIIX/ICH, Promise,
+            Silicon Image, VIA, VITESSE VSC-7174</entry>
+        </row>
+
+        <row>
+          <entry>SCSI</entry>
+
+          <entry>7000FASST, ACARD, Adaptec AACRAID, Adaptec AIC7xxx,
+            Adaptec AIC79xx U320, AdvanSys, Always IN2000,
+            AMI MegaRAID, BusLogic, Compaq Fibre Channel,
+            NCR5380/53c400, IBM ServeRAID, SYM53C8XX,
+            Tekram DC390(T) and Am53/79C974</entry>
+        </row>
+
+        <row>
+          <entry>USB</entry>
+
+          <entry>USB device filesystem,
+            EHCI HCD (USB 2.0) support,
+            UHCI (Intel PIIX4, VIA, ...) support,
+            OHCI (Compaq, iMacs, OPTi, SiS, ALi, ...) support,
+            USB Mass Storage support,
+            USB Human Interface Device (full HID) support,
+            HID input layer support</entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </informaltable>
+
+  <para>In order to install CRUX, your disk controller must be
+    present in the list above. If your hardware is not supported or
+    you have other problems installing CRUX you might find a
+    solution in <xref linkend="Alternative-Installation-Methods"
+    />.</para>
+</section>
+
+<section id="Installing-From-CD-ROM">
+  <title>Installing From CD-ROM</title>
+
+  <procedure>
+    <step>
+      <para>Download the CRUX ISO image (<filename
+        >crux-&crux;.iso</filename>).
+        To ensure that the download was successful you should
+        examine its checksum using <userinput
+        >md5sum</userinput>.</para>
+
+      <informalexample>
+        <screen>$ <userinput>md5sum crux-&crux;.iso</userinput></screen>
+      </informalexample>
+
+      <para>Compare the output with the file <filename
+        >crux-&crux;.md5sum</filename>,
+        which can be found in the same directory as the ISO image
+        on the download site. If the checksums match the download
+        was successful and you can continue by burning the ISO
+        image on a CD.</para>
+    </step>
+
+    <step>
+      <para>The ISO image is bootable, just insert the newly burned
+        CD and reboot your computer. Press <literal>Enter</literal>
+        at the boot prompt.</para>
+    </step>
+
+    <step>
+      <para>Login as <userinput>root</userinput> (no password
+        required).</para>
+    </step>
+
+    <step>
+      <para>Create (if necessary) and format the partition(s) you
+        want CRUX to be installed on.</para>
+
+      <informalexample>
+<screen>$ <userinput>fdisk /dev/discs/disc<replaceable
+    >?</replaceable>/disc</userinput>
+$ <userinput>mkreiserfs /dev/discs/disc<replaceable
+    >?</replaceable>/part<replaceable>?</replaceable></userinput>
+$ <userinput>mkswap /dev/discs/disc<replaceable
+    >?</replaceable>/part<replaceable
+    >?</replaceable></userinput></screen>
+        </informalexample>
+
+      <para>The amount of disk space you need depends on how many
+        packages you choose to install. I recommend having at least
+        a 1G root partition (CRUX will use about 200MB-500MB
+        depending on your configuration).</para>
+
+      <para>Using ReiserFS is recommended, but there is support for
+        Ext2fs/Ext3fs, XFS and JFS as well. Further, I highly recommend
+        separating system data from user data, i.e. use a
+        separate partition for <filename>/home</filename> (and
+        possibly <filename>/var</filename>) since that will make
+        your life a lot easier the day you want to
+        upgrade/reinstall/remove your system.</para>
+
+      <note>
+        <para>Make sure that any BIOS Virus Protection option is
+          DISABLED as this option may prevent <userinput
+          >fdisk</userinput> from writing new partitions
+          correctly.</para>
+      </note>
+    </step>
+
+    <step>
+      <para>Mount the partition on which you want to install this
+        distribution.</para> 
+
+      <informalexample>
+<screen>$ <userinput>mount /dev/discs/disc<replaceable
+    >?</replaceable>/part<replaceable
+    >?</replaceable> /mnt</userinput></screen>
+      </informalexample>
+
+      <para>If you want the installation to span more than one
+        partition, mount those partitions as well. For
+        example, if you want to have a different partition for
+        <filename>/home</filename> or <filename>/var</filename>,
+        then do:</para>
+
+      <informalexample>
+<screen>$ <userinput>mkdir /mnt/var</userinput>
+$ <userinput>mount /dev/discs/disc<replaceable
+    >?</replaceable>/part<replaceable
+    >?</replaceable> /mnt/var</userinput></screen>
+      </informalexample>
+    </step>
+
+    <step>
+      <para>Activate your swap partition(s).</para>
+
+      <informalexample>
+<screen>$ <userinput>swapon /dev/discs/disc<replaceable
+    >?</replaceable>/part<replaceable
+    >?</replaceable></userinput></screen>
+      </informalexample>
+    </step>
+
+    <step>
+      <para>Type <userinput>setup</userinput> to start the package
+        installation script. The script will ask where you
+        mounted your new root partition and which packages you want
+        to install. Just select the packages you want and nothing
+        else will be installed. However, I recommend at
+        least installing all the packages marked <filename
+        >base</filename>.</para>
+
+      <para>Once it has installed the selected packages, the <userinput
+        >setup</userinput> script will display an installation log.
+        Make sure the last line in the log says <quote><literal>0
+        error(s)</literal></quote>.</para>
+
+      <para>If you at a later stage find that you need some
+        additional packages you can just mount the CRUX CD-ROM and
+        use <userinput>pkgadd</userinput> to install them.</para>
+
+      <note>
+        <para>There is no package dependency checking. This means
+          that it is up to you to figure out that if you for
+          example install the <filename>sendmail</filename> package
+          you also need to install the <filename>db</filename>
+          package.</para>
+      </note>
+
+      <para><ulink url="http://crux.nu/doc/screenshots.html"
+        >Screenshots of setup</ulink></para>
+    </step>
+
+    <step>
+      <para>Now it's time to compile your kernel and do basic
+        system configuration. The kernel compilation requires that
+        you <quote>chroot</quote> into your new CRUX installation.</para>
+
+      <informalexample>
+<screen>$ <userinput>mount -t devfs devfs /mnt/dev</userinput>
+$ <userinput>mount -t proc proc /mnt/proc</userinput>
+$ <userinput>chroot /mnt /bin/bash</userinput></screen>
+      </informalexample>
+    </step>
+
+    <step>
+      <para>Set the <userinput>root</userinput> password.</para>
+
+      <informalexample>
+<screen>$ <userinput>passwd</userinput></screen>
+      </informalexample>
+    </step>
+
+    <step>
+      <para>Edit <filename>/etc/fstab</filename> to configure your
+        filesystem(s). Editors <userinput>vim</userinput> and
+        <userinput>pico</userinput> are available.</para>
+    </step>
+
+    <step>
+      <para>Edit <filename>/etc/rc.conf</filename> to configure
+        font, keyboard, timezone, hostname and services. See <xref
+        linkend="Configuration-Variables-in-rc.conf"/> for details
+        about <filename>/etc/rc.conf</filename>.</para>
+    </step>
+
+    <step>
+      <para>Edit <filename>/etc/rc.d/net</filename>, <filename
+        >/etc/hosts</filename> and <filename
+        >/etc/resolv.conf</filename> to configure your network
+        (ip-address/gateway/hostname/domain/dns).</para>
+    </step>
+
+    <step>
+      <para>Go to <filename>/usr/src/linux-&kernel;</filename>,
+        configure and compile a new kernel.</para>
+
+      <informalexample>
+<screen>$ <userinput>cd /usr/src/linux-&kernel;</userinput>
+$ <userinput>make menuconfig</userinput>
+$ <userinput>make all</userinput>
+$ <userinput>make modules_install</userinput>
+$ <userinput>cp arch/i386/boot/bzImage /vmlinuz</userinput>
+$ <userinput>cp System.map /</userinput></screen>
+      </informalexample>
+
+      <para>Remember to enable the following kernel options:</para>
+
+<programlisting>Code maturity level options  --->
+      [*] Prompt for development and/or incomplete code/drivers
+
+File systems  --->
+   Pseudo filesystems  --->
+      [*] /dev file system support
+      [*]   Automatically mount at boot</programlisting>
+    </step>
+
+    <step>
+      <para>Edit <filename>/etc/lilo.conf</filename> to boot the
+        kernel you just compiled and run <userinput
+        >lilo</userinput> to make the new system bootable.</para>
+    </step>
+
+    <step>
+      <para>Remove the CRUX CD-ROM from your drive and reboot from
+        harddisk.</para>
+    </step>
+  </procedure>
+</section>
+
+<section id="Upgrading-From-CDROM">
+  <title>Upgrading From CD-ROM</title>
+
+  <procedure>
+    <step>
+      <para>Download the CRUX ISO image (<filename
+         >crux-&crux;.iso</filename>).
+         To ensure that the download was successful you should
+         examine its checksum using <userinput
+         >md5sum</userinput>.</para>
+
+      <informalexample>
+<screen>$ <userinput>md5sum crux-&crux;.iso</userinput></screen>
+      </informalexample>
+
+      <para>Compare the output with the file <filename
+        >crux-&crux;.md5sum</filename>,
+        which can be found in the same directory as the ISO image
+        on the download site. If the checksums match the download
+        was successful and you can continue with burning the ISO
+        image on a CD.</para>
+    </step>
+
+    <step>
+      <para>The ISO image is bootable, just insert the newly burned
+        CD and reboot your computer. Press <literal>Enter</literal>
+        at the boot prompt.</para>
+    </step>
+
+    <step>
+      <para>Login as <userinput>root</userinput> (no password
+        required).</para>
+    </step>
+
+    <step>
+      <para>Mount your CRUX root partition.</para>
+
+      <informalexample>
+<screen>$ <userinput>mount /dev/discs/disc<replaceable
+    >?</replaceable>/part<replaceable
+    >?</replaceable> /mnt</userinput></screen>
+      </informalexample>
+
+      <para>If your installation spans over more than one
+        partition, then mount these partitions as well. For
+        example, if you have a different partition for <filename
+        >/var</filename>, then do:</para>
+
+      <informalexample>
+<screen>$ <userinput>mount /dev/discs/disc<replaceable
+    >?</replaceable>/part<replaceable
+    >?</replaceable> /mnt/var</userinput></screen>
+      </informalexample>
+    </step>
+
+    <step>
+      <para>Activate your swap partition(s).</para>
+
+      <informalexample>
+<screen>$ <userinput>swapon /dev/discs/disc<replaceable
+    >?</replaceable>/part<replaceable
+    >?</replaceable></userinput></screen>
+      </informalexample>
+    </step>
+
+    <step>
+      <para>Type <userinput>setup</userinput> to start the
+        package installation script. The script will ask you where
+        you mounted your root partition and which packages you want
+        to upgrade. It is a good idea to upgrade all packages, else
+        you might get into trouble later, e.g. in case a new version
+        of some library isn't 100% backwards compatible.</para>
+
+      <note>
+        <para>The <userinput>setup</userinput> script uses the
+          <filename>/etc/pkgadd.conf</filename> of the target
+          system to determine which files to upgrade and which
+          files not to upgrade. The files that are not upgraded
+          are put in <filename>/var/lib/pkg/rejected/</filename>
+          (<xref linkend="Upgrading-a-Package"/>).</para>
+      </note>
+
+      <para>When the <userinput>setup</userinput> script has
+        upgraded the selected packages an upgrade log will be
+        displayed. Make sure the last line in the log says
+        <quote><literal>0 error(s)</literal></quote>.</para>
+
+      <para>If you at a later stage find that you need some
+        additional packages you can just mount the CRUX CD-ROM and
+        use <userinput>pkgadd</userinput> to install them.</para>
+    </step>
+
+    <step>
+      <para>Now it's time to compile your kernel. The kernel
+        compilation requires that you <quote>chroot</quote> into your CRUX
+        installation.</para>
+
+      <informalexample>
+<screen>$ <userinput>mount -t devfs devfs /mnt/dev</userinput>
+$ <userinput>mount -t proc proc /mnt/proc</userinput>
+$ <userinput>chroot /mnt /bin/bash</userinput></screen>
+      </informalexample>
+    </step>
+
+    <step>
+      <para>Go to <filename>/usr/src/linux-&kernel;</filename>,
+        configure and compile a new kernel. Remember to enable the
+        following kernel options:</para>
+
+<programlisting>Code maturity level options  - - ->
+      [*] Prompt for development and/or incomplete code/drivers
+
+File systems  - - ->
+      [*] /dev file system support
+      [*]   Automatically mount at boot</programlisting>
+    </step>
+
+    <step>
+      <para>Edit <filename>/etc/lilo.conf</filename> to boot the
+        kernel you just compiled and run <userinput
+        >lilo</userinput> to make the new system bootable.</para>
+    </step>
+
+    <step>
+      <para>Remove the CRUX CD-ROM from your drive and reboot from
+        harddisk.</para>
+    </step>
+  </procedure>
+
+</section>
+
+<section id="Alternative-Installation-Methods">
+  <title>Alternative Installation Methods</title>
+
+  <section id="Building-Your-Own-Bootkernel">
+    <title>Building Your Own Bootkernel</title>
+
+    <para>If you are unable to install CRUX from CD-ROM because
+      your hardware is not supported by the bootkernel you can
+      build your own bootkernel and add whatever hardware support
+      you need. To do this you need a 1.44Mb floppy disk, access to
+      another Linux box and the CRUX ISO image burned on a CD.
+      Basic knowledge about how to configure and compile the Linux
+      kernel is of course also required.</para>
+
+    <procedure>
+      <step>
+        <para>Build a new kernel with support for your
+          hardware. Use the kernel configuration used by the
+          existing bootkernel as a starting point (you can find it
+          <ulink url="http://crux.nu/cvs.cgi/crux/kernel"
+          >here</ulink>) and add the hardware support you need. If
+          the kernel gets too big it is safe to remove SCSI and USB
+          drivers (unless you need them of course), but do not
+          remove any filesystem related options.</para>
+      </step>
+
+      <step>
+        <para>Download the <ulink url="http://crux.nu/files/mkbootfloppy.tar.gz"
+          >boot floppy creation kit</ulink> and unpack it.</para>
+      </step>
+
+      <step>
+        <para>Go into the <filename>mkbootfloppy</filename>
+          directory and execute the <userinput
+          >mkbootfloppy</userinput> script (as <userinput
+          >root</userinput>). This script requires one argument, the
+          kernel image you want to place on the floppy image.
+          Before you do this, make sure you do not have anything
+          mounted on <filename>/mnt</filename> since the
+          <userinput>mkbootfloppy</userinput> script will use that
+          as a mount point.</para>
+
+        <informalexample>
+<screen>$ <userinput>cd mkbootfloppy</userinput>
+$ <userinput>./mkbootfloppy <replaceable>/path/to/linux/kernel</replaceable>/arch/i386/boot/bzImage</userinput>
+1440+0 records in
+1440+0 records out
+mke2fs 1.27 (8-Mar-2002)
+Added CRUX *</screen>
+        </informalexample>
+      </step>
+
+      <step>
+        <para>Write the resulting <filename>boot.img</filename>
+          file to a floppy disk.</para>
+
+        <informalexample>
+<screen>$ <userinput>dd if=boot.img of=/dev/fd0</userinput></screen>
+        </informalexample>
+      </step>
+
+      <step>
+        <para>Insert both the floppy disk and the CRUX CD into the
+          system you want to install CRUX on and reboot.</para>
+      </step>
+
+      <step>
+        <para>Install CRUX.</para>
+      </step>
+    </procedure>
+  </section>
+
+  <section id="Network-Installation">
+    <title>Network Installation</title>
+
+    <para>If you do not have a CD burner, are unable to boot your
+      machine using the CRUX CD-ROM or for any other reason are
+      unable to install CRUX the normal way (<xref
+      linkend="Installing-From-CD-ROM"/>) you might want to check
+      out Martin Opel's <ulink url="http://rfhs8012.fh-regensburg.de/~opel/crux/network-setup.php"
+      >CRUX Network Setup Guide</ulink> or <ulink url="http://jue.li/crux/doc/crux-nfs-install.html"
+      >HOWTO install CRUX via NFS</ulink> by J&uuml;rgen
+      Daubert.</para>
+  </section>
+</section>
diff --git a/doc/handbook/intro.xml b/doc/handbook/intro.xml
new file mode 100644
index 0000000..4939089
--- /dev/null
+++ b/doc/handbook/intro.xml
@@ -0,0 +1,80 @@
+<!-- $Id: intro.xml,v 1.1 2003/04/28 23:18:22 per Exp $ -->
+
+<title>Introduction</title>
+
+<section id="What-is-CRUX">
+  <title>What is CRUX?</title>
+
+  <para>CRUX is a lightweight, i686-optimized Linux distribution
+    targeted at experienced Linux users. The primary focus of this
+    distribution is <quote>keep it simple</quote>, which it reflects
+    in a simple tar.gz-based package system, BSD-style initscripts,
+    and a relatively small collection of trimmed packages. The
+    secondary focus is utilization of new Linux features and recent
+    tools and libraries. CRUX also has a ports system which makes it
+    easy to install and upgrade applications.</para>
+</section>
+
+<section id="Why-use-CRUX">
+  <title>Why use CRUX?</title>
+    
+  <para>There are many Linux distributions out there these days, so
+    what makes this distribution any better than the others? Well,
+    it's all about taste really. I can give you a hint about my taste,
+    and perhaps we share the same taste, or we don't. First of all, I
+    want a distribution made with simplicity in mind from
+    beginning to end. Further, I want my packages
+    up-to-date, not the latest bleeding-edge-alpha version, but the
+    latest stable version. I want to easily create new and
+    update old packages (updating a package in CRUX is often just a
+    matter of typing <userinput >pkgmk -d -u</userinput>). I want
+    packages optimized for my processor (think
+    <userinput>-march=i686</userinput>). I don't want my filesystem
+    cluttered with files I never use (think
+    <filename>/usr/doc/*</filename>, etc). If I need more information
+    about a specific program, other than information found on the
+    man-page, I'll find it on the net. And finally, I want
+    to use new features offered by recent Linux kernels (think devfs,
+    reiserfs, ext3fs, etc).</para>
+  
+  <para>If you are a somewhat experienced Linux user that wants a
+    clean and solid Linux distribution as the foundation of your
+    installation, prefers editing configuration files with an editor
+    to using a GUI, and doesn't hesitate to download and
+    compile programs yourself, then this distribution might suit you
+    well.</para>
+</section>
+
+<section id="License">
+  <title>License</title>
+
+  <section id="License-Packages">
+    <title>Packages</title>
+
+    <para>Since CRUX is a Linux distribution, it contains software
+      written by a lot of different people. Each software package
+      comes with its own license, chosen by its author(s). To find
+      out how a particular package is licensed, have a look
+      at its source code.</para>
+  </section>
+
+  <section id="License-Build-Scripts">
+    <title>Build Scripts</title>
+
+    <para>All package build scripts in CRUX (in package categories
+      <filename>base</filename> and <filename>opt</filename>) are
+      Copyright &copy; 2000-2003 by Per Lid&eacute;n and
+      licensed through the <ulink
+      url="http://www.gnu.org/copyleft/gpl.html">GNU General
+      Public License</ulink>.</para>
+  </section>
+
+  <section id="License-NO-WARRANTY">
+    <title>NO WARANTY</title>
+
+    <para>CRUX is distributed in the hope that it will be useful,
+      but WITHOUT ANY WARRANTY; without even the implied warranty
+      of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Use
+      it at YOUR OWN RISK.</para>
+  </section>
+</section>
diff --git a/doc/handbook/package.xml b/doc/handbook/package.xml
new file mode 100644
index 0000000..4dde170
--- /dev/null
+++ b/doc/handbook/package.xml
@@ -0,0 +1,632 @@
+<!-- $Id: package.xml,v 1.5 2005/03/27 21:36:13 per Exp $ -->
+
+<title>The Package System</title>
+
+<section id="The-Package-System-Introduction">
+  <title>Introduction</title>
+
+  <para>The package system (<ulink
+    url="http://www.fukt.bth.se/~per/pkgutils/">pkgutils</ulink>)
+    is made with simplicity in mind, where all packages are plain
+    <filename>tar.gz</filename> files (i.e. without any kind of meta
+    data). Packages follow the naming convention <filename
+    ><replaceable>&lt;name&gt;</replaceable>#<replaceable
+    >&lt;version&gt;</replaceable>-<replaceable
+    >&lt;release&gt;</replaceable>.pkg.tar.gz</filename>,
+    where <filename><replaceable
+    >&lt;name&gt;</replaceable></filename> is the name of the program,
+    <filename><replaceable>&lt;version&gt;</replaceable></filename>
+    is the version number of the program, and <filename><replaceable
+    >&lt;release&gt;</replaceable></filename> is the version number
+    of the package. The <filename>pkg.tar.gz</filename> extension is
+    used (instead of just <filename>tar.gz</filename>) to indicate
+    that this is not just any <filename>tar.gz</filename> file, but a
+    <filename>tar.gz</filename> that is meant to be installed using
+    <userinput>pkgadd</userinput>. This way it is easy to tell
+    packages apart from other <filename>tar.gz</filename>
+    files.</para>
+
+  <para><userinput>pkgadd(8)</userinput>, <userinput
+    >pkgrm(8)</userinput>, <userinput>pkginfo(8)</userinput>, and
+    <userinput>pkgmk(8)</userinput> are the package management
+    utilities. With these utilities you can install, uninstall,
+    inspect, make packages and query the package database.</para>
+
+  <para>When a package is installed using <userinput
+    >pkgadd</userinput> a new record is added to the package database
+    (stored in <filename>/var/lib/pkg/db</filename>). The package
+    system does not have any kind of dependency checking, thus it
+    will not warn you if you install a package that requires other
+    packages to be installed.</para>
+
+  <para>The following sections will in short describe how to use the
+    package utilities. Additional information about these utilities
+    can be found on their respective man page.</para>
+</section>
+
+<section id="Using-the-Package-System">
+  <title>Using the Package System</title>
+
+  <section id="Installing-a-Package">
+    <title>Installing a Package</title>
+
+    <para>Installing a package is done by using <userinput
+      >pkgadd</userinput>. This utility requires at least one
+      argument, the package you want to install. Example:</para>
+
+    <informalexample>
+<screen>$ <userinput>pkgadd bash#2.05-1.pkg.tar.gz</userinput></screen>
+    </informalexample>
+
+    <para>When installing a package the package manager will ensure
+      that no previously installed files are overwritten. If conflicts
+      are found an error message will be printed and <userinput
+      >pkgadd</userinput> will abort without installing the package.
+      The error message will contain the names of the conflicting
+      files. Example:</para>
+
+    <informalexample>
+<screen>$ <userinput>pkgadd bash#2.05-1.pkg.tar.gz</userinput>
+bin/sh
+usr/man/man1/sh.1.gz
+pkgadd error: listed file(s) already installed (use -f to ignore and overwrite)</screen>
+    </informalexample>
+
+    <para>To force the installation and overwrite the conflicting
+      files you can use the option <userinput>-f</userinput> (or
+      <userinput>--force</userinput>). Example:</para>
+
+    <informalexample>
+<screen>$ <userinput>pkgadd -f bash#2.05-1.pkg.tar.gz</userinput></screen>
+    </informalexample>
+
+    <para>The package system allows a file to be owned by
+      exactly one package. When forcing an installation the ownership
+      of the conflicting files will be transferred to the package
+      that is currently being installed. Directories can however be
+      owned by more then one package.</para>
+
+    <warning>
+      <para>It is often not a good idea to force the installation
+        unless you really know what you are doing. If a package
+        conflicts with already installed files it could be a sign
+        that the package is broken and installs unexpected files. Use
+        this option with extreme care, preferably not at all.</para>
+    </warning>
+
+    <para>As said earlier the package file itself does not contain any
+      meta data. Instead the package manager uses the package
+      filename to determine the package name and version. Thus, when
+      installing a package file named <filename
+      >bash#2.05-1.pkg.tar.gz</filename> the package manager will
+      interpret this as a package named <filename>bash</filename> at
+      version <filename>2.05-1</filename>. If <userinput
+      >pkgadd</userinput> is unable to interpret the filename (e.g.
+      <literal>#</literal> is missing or the filename does not end
+      with <filename>.pkg.tar.gz</filename>) an error message will be
+      printed and <userinput>pkgadd</userinput> will abort without
+      installing the package.</para>
+  </section>
+
+  <section id="Upgrading-a-Package">
+    <title>Upgrading a Package</title>
+
+    <para>Upgrading a package is done using <userinput
+      >pkgadd</userinput> with the <userinput>-u</userinput> option.
+      Example:</para>
+
+    <informalexample>
+<screen>$ <userinput>pkgadd -u bash#2.05-1.pkg.tar.gz</userinput></screen>
+    </informalexample>
+
+    <para>This will replace the previously installed <filename
+      >bash</filename> package with the new one. If you have not
+      previously installed <filename>bash</filename>, <userinput
+      >pkgadd</userinput> will print an error message.
+      The package system does not care about
+      the version number of the package in that you can
+      <quote>upgrade</quote> version <filename>2.05-1</filename>
+      with version <filename>2.04-1</filename> (or even with version
+      <filename>2.05-1</filename> itself). The installed package will
+      be replaced with the specified package.</para>
+
+    <para>Upgrading a package is equivalent to executing <userinput
+      >pkgrm</userinput> followed by <userinput>pkgadd</userinput>
+      with one (big) exception. When upgrading a package (with
+      <userinput>pkgadd -u</userinput>) you have the option to
+      prevent some of the already installed files
+      from getting replaced. This is typically useful when you want
+      to preserve configuration and log files.</para>
+
+    <para>When executing <userinput>pkgadd</userinput> the file
+      <filename>/etc/pkgadd.conf</filename> will be read. This file
+      can contain rules describing how <userinput>pkgadd</userinput>
+      should behave when doing upgrades. A rule is built out of three
+      fragments; <emphasis>event</emphasis>, <emphasis
+      >pattern</emphasis> and <emphasis>action</emphasis>. The event
+      describes in what kind of situation this rule applies.
+      Currently only one type of event is supported, that is
+      <literal>UPGRADE</literal>. The <emphasis>pattern</emphasis> is
+      a filename pattern expressed as a regular expression and the
+      action applicable to the <literal>UPGRADE</literal> event is
+      <literal>YES</literal> or <literal>NO</literal>. More than one
+      rule of the same event type is allowed, in which case the first
+      rule will have the lowest priority and the last rule will have
+      the highest priority. Example:</para>
+
+    <informalexample>
+<programlisting>#
+# /etc/pkgadd.conf: pkgadd(8) configuration
+#
+
+UPGRADE         ^etc/.*$                NO
+UPGRADE         ^var/log/.*$            NO
+UPGRADE         ^etc/X11/.*$            YES
+UPGRADE         ^etc/X11/XF86Config$    NO
+
+# End of file</programlisting>
+    </informalexample>
+
+    <para>The above example will cause <userinput>pkgadd</userinput>
+      to never upgrade anything in <filename>/etc/</filename> or
+      <filename>/var/log/</filename> (subdirectories included), except
+      files in <filename>/etc/X11/</filename> (subdirectories
+      included), unless it is the file <filename
+      >/etc/X11/XF86Config</filename>. The default rule is to upgrade
+      everything, rules in this file are exceptions to that
+      rule.</para>
+
+    <note>
+      <para>A <emphasis>pattern</emphasis> should never contain an
+        initial <quote>/</quote> since you are referring to the files
+        in the package, not the files on the disk.</para>
+    </note>
+
+    <para>If <userinput>pkgadd</userinput> finds that a specific file
+      should not be upgraded it will install it under
+      <filename>/var/lib/pkg/rejected/</filename>. Files in this
+      directory are never added to the package database. The user is then
+      free to examine, use and/or remove that file manually.   
+      Another option is to use <userinput>rejmerge</userinput>.
+      For each rejected file found in <filename>/var/lib/pkg/rejected/</filename>,
+      <userinput>rejmerge</userinput> will display the difference between the
+      installed version and the rejected version. The user can then choose to keep
+      the installed version, upgrade to the rejected version or perform a merge
+      of the two. Example (using the above <filename>/etc/pkgadd.conf</filename>):</para>
+
+    <informalexample>
+<screen>$ <userinput>pkgadd -u bash#2.05-1.pkg.tar.gz</userinput>
+pkgadd: rejecting etc/profile, keeping existing version
+$ <userinput>ls /var/lib/pkg/rejected/</userinput>
+etc/
+$ <userinput>ls /var/lib/pkg/rejected/etc/</userinput>
+profile</screen>
+    </informalexample>
+  </section>
+
+  <section id="Removing-a-Package">
+    <title>Removing a Package</title>
+
+    <para>Removing a package is done by using <userinput
+      >pkgrm</userinput>. This utility requires one argument, the
+      name of the package you want to remove. Example:</para>
+
+    <informalexample>
+      <screen>$ <userinput>pkgrm bash</userinput></screen>
+    </informalexample>
+
+    <warning>
+      <para>This will remove all files owned by the package, no
+        questions asked. Think twice before doing it and make sure
+        that you did not misspell the package name since that could
+        remove something completely different (e.g. think about what
+        could happen if you misspelled <filename>glib</filename> as
+        <filename>glibc</filename>).</para>
+    </warning>
+  </section>
+
+  <section id="Querying-the-Package-Database">
+    <title>Querying the Package Database</title>
+
+    <para>Querying the package database is done using
+      <userinput>pkginfo</userinput>. This utility has a few options
+      to answer different queries.</para>
+
+    <informaltable>
+      <tgroup cols="2">
+        <thead>
+          <row>
+            <entry>Option</entry>
+
+            <entry>Description</entry>
+          </row>
+        </thead>
+
+        <tbody>
+          <row>
+            <entry><userinput>-i</userinput>, <userinput
+              >--installed</userinput></entry>
+
+            <entry>List installed packages and their version.</entry>
+          </row>
+
+          <row>
+            <entry><userinput>-l</userinput>,&nbsp;<userinput
+              >--list&nbsp;<replaceable
+              >package|file</replaceable></userinput></entry>
+
+            <entry>List files owned by the specified <userinput
+              ><replaceable>package</replaceable></userinput> or
+              contained in <userinput><replaceable
+              >file</replaceable></userinput></entry>
+          </row>
+
+          <row>
+            <entry><userinput>-o</userinput>, <userinput
+              >--owner <replaceable
+              >pattern</replaceable></userinput></entry>
+
+            <entry>List owner(s) of file(s) matching <userinput><replaceable
+              >pattern</replaceable></userinput>.</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </informaltable>
+
+    <para>Examples:</para>
+
+    <informalexample>
+<screen>$ <userinput>pkginfo -i</userinput>
+audiofile 0.2.3-1
+autoconf 2.52-1
+automake 1.5-1
+&lt;...&gt;
+xmms 1.2.7-1
+zip 2.3-1
+zlib 1.1.4-1</screen>
+
+<screen>$ <userinput>pkginfo -l bash</userinput>
+bin/
+bin/bash
+bin/sh
+etc/
+etc/profile
+usr/
+usr/man/
+usr/man/man1/
+usr/man/man1/bash.1.gz
+usr/man/man1/sh.1.gz</screen>
+
+<screen>$ <userinput>pkginfo -l grep#2.5-1.pkg.tar.gz</userinput>
+usr/
+usr/bin/
+usr/bin/egrep
+usr/bin/fgrep
+usr/bin/grep
+usr/man/
+usr/man/man1/
+usr/man/man1/egrep.1.gz
+usr/man/man1/fgrep.1.gz
+usr/man/man1/grep.1.gz</screen> 
+
+<screen>$ <userinput>pkginfo -o bin/ls</userinput>
+e2fsprogs  usr/bin/lsattr
+fileutils  bin/ls
+modutils   sbin/lsmod</screen>
+    </informalexample>
+  </section>
+</section>
+
+<section id="Creating-Packages">
+  <title>Creating Packages</title>
+
+  <para>Creating a package is done using <userinput
+    >pkgmk</userinput>. This utility uses a file called <filename
+    >Pkgfile</filename>, which contains information about the package
+    (such as name, version, etc) and the commands that should be
+    executed in order to compile the package in question. To be more
+    specific, the <filename>Pkgfile</filename> file is actually a
+    <userinput>bash(1)</userinput> script, which defines a number of
+    variables (<literal>name</literal>, <literal>version</literal>,
+    <literal>release</literal> and <literal>source</literal>) and a
+    function (<literal>build</literal>). Below is an example of what a
+    <filename>Pkgfile</filename> file might look like. The example
+    shows how to package the <userinput>grep(1)</userinput> utility.
+    Some comments are inserted for explanation.</para>
+
+  <informalexample>
+<programlisting># Specify the name of the package.
+name=grep
+
+# Specify the version of the package.
+version=2.4.2
+
+# Specify the package release.
+release=1
+
+# The source(s) used to build this package.
+source=(ftp://ftp.ibiblio.org/pub/gnu/$name/$name-$version.tar.gz)
+
+# The build() function below will be called by pkgmk when
+# the listed source files have been unpacked.
+build() {
+   # The first thing we do is to cd into the source directory.
+   cd $name-$version
+
+   # Run the configure script with desired arguments.
+   # In this case we want to put grep under /usr/bin and
+   # disable national language support.
+   ./configure --prefix=/usr --disable-nls
+
+   # Compile.
+   make
+
+   # Install the files, BUT do not install it under /usr, instead
+   # we redirect all the files to $PKG/usr by setting the DESTDIR
+   # variable. The $PKG variable points to a temporary directory
+   # which will later be made into a tar.gz-file. Note that the
+   # DESTDIR variable is not used by all Makefiles, some use prefix
+   # and others use ROOT, etc. You have to inspect the Makefile in
+   # question to find out. Some Makefiles do not support redirection
+   # at all. In those cases you will have to create a patch for it.
+   make DESTDIR=$PKG install
+
+   # Remove unwanted files, in this case the info-pages.
+   rm -rf $PKG/usr/info
+}</programlisting>
+  </informalexample>
+
+  <para>In reality you do not include all those comments, thus the real
+    <filename>Pkgfile</filename> for <userinput>grep(1)</userinput> looks
+    like this:</para>
+
+  <informalexample>
+<programlisting># $Id: package.xml,v 1.5 2005/03/27 21:36:13 per Exp $
+# Maintainer: Per Lid&eacute;n &lt;per@fukt.bth.se&gt;
+
+name=grep
+version=2.4.2
+release=1
+source=(ftp://ftp.ibiblio.org/pub/gnu/$name/$name-$version.tar.gz)
+
+build() {
+  cd $name-$version
+  ./configure --prefix=/usr --disable-nls
+  make
+  make DESTDIR=$PKG install
+  rm -rf $PKG/usr/info
+}</programlisting>
+  </informalexample>
+
+  <note>
+    <para>The <literal>build()</literal> function in the example
+      above is just an example of how <userinput>grep</userinput> is
+      built. The contents of the function can differ significantly
+      if the program is build in some other way, e.g. does not use
+      <userinput>autoconf</userinput>.</para>
+  </note>
+
+  <para>When the <literal>build()</literal> function has been
+    executed, the <filename>$PKG</filename> directory will be made
+    into a package named <filename><replaceable
+    >&lt;name&gt;</replaceable>#<replaceable
+    >&lt;version&gt;</replaceable>-<replaceable
+    >&lt;release&gt;</replaceable>.pkg.tar.gz</filename>. Before the
+    package creation is completed, <userinput>pkgmk</userinput>
+    will check the content of the package against the <filename
+    >.footprint</filename> file. If this file does not exist, it will
+    be created and the test will be skipped. The <filename
+    >.footprint</filename> file will contain a list of all files
+    that should be in the package if the build was successful or a
+    list of all the files that were installed in <filename
+    >$PKG</filename> (if the <filename>.footprint</filename> did not
+    already exist).
+    If there is a mismatch the test will fail and an error message
+    will be printed. You should not write the <filename
+    >.footprint</filename> file by hand. Instead, when a package has
+    been upgraded and you need to update the contents of the <filename
+    >.footprint</filename> file you simply do <userinput>pkgmk
+    -uf</userinput>. This test ensures that a rebuild of the package
+    turned out as expected.</para>
+
+  <para>If the package built without errors it's time to install it
+    by using <userinput>pkgadd</userinput> and try it out. I highly
+    recommend looking at the <filename>Pkgfile</filename> in another
+    package(s), since looking at examples is a great way to
+    learn.</para>
+</section>
+
+<section id="Package-Guidelines">
+  <title>Package Guidelines</title>
+
+  <section id="Package-Guidelines-General">
+    <title>General</title>
+
+    <itemizedlist>
+      <listitem>
+        <para>The name of a package should always be lowercase (e.g.
+          <literal>name=eterm</literal> and not <literal
+          >name=Eterm</literal>). In case the package is added to the
+          CRUX ports system the exact same name should be use for
+          the name of the directory in the ports structure, i.e.
+          <filename>/usr/ports/???/eterm</filename>.</para>
+      </listitem>
+
+      <listitem>
+        <para>Do not combine several separately distributed
+          programs/libraries into one package. Make several
+          packages instead.</para>
+      </listitem>
+    </itemizedlist>
+  </section>
+
+  <section id="Package-Guidelines-Directories">
+    <title>Directories</title>
+
+    <itemizedlist>
+      <listitem>
+        <para>In general packages should install files in these
+          directories. Exceptions are of course allowed if there is
+          a good reason. But try to follow the following directory
+          structure as close as possible.</para>
+
+        <informaltable>
+          <tgroup cols="2">
+            <thead>
+              <row>
+                <entry>Directory</entry>
+
+                <entry>Description</entry>
+              </row>
+            </thead>
+
+            <tbody>
+              <row>
+                <entry><filename>/usr/bin/</filename></entry>
+
+                <entry>User command/application binaries</entry>
+              </row>
+
+              <row>
+                <entry><filename>/usr/sbin/</filename></entry>
+
+                <entry>System binaries (e.g. daemons)</entry>
+              </row>
+
+              <row>
+                <entry><filename>/usr/lib/</filename></entry>
+
+                <entry>Libraries</entry>
+              </row>
+
+              <row>
+                <entry><filename>/usr/include/</filename></entry>
+
+                <entry>Header files</entry>
+              </row>
+
+              <row>
+                <entry><filename>/usr/lib/<replaceable
+                  >&lt;prog&gt;</replaceable>/</filename></entry>
+
+                <entry>Plug-ins, addons, etc</entry>
+              </row>
+
+              <row>
+                <entry><filename>/usr/man/</filename></entry>
+
+                <entry>Man pages</entry>
+              </row>
+
+              <row>
+                <entry><filename>/usr/share/<replaceable
+                  >&lt;prog&gt;</replaceable>/</filename></entry>
+
+                <entry>Data files</entry>
+              </row>
+
+              <row>
+                <entry><filename>/usr/etc/<replaceable
+                  >&lt;prog&gt;</replaceable>/</filename></entry>
+
+                <entry>Configuration files</entry>
+              </row>
+
+              <row>
+                <entry><filename>/etc/</filename></entry>
+
+                <entry>Configuration files for system software
+                  (daemons, etc)</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </informaltable>
+      </listitem>
+
+      <listitem>
+        <para><filename>/usr/X11R6</filename> and
+          <filename>/usr/<replaceable>???</replaceable>/X11</filename>
+          are reserved for X11 only. X related programs that are
+          not shipped with X11 should be placed under
+          <filename>/usr</filename> and NOT under
+          <filename>/usr/X11R6</filename> or
+          <filename>/usr/<replaceable
+            >???</replaceable>/X11</filename>.</para>
+      </listitem>
+
+      <listitem>
+        <para><filename>/opt</filename> directory is reserved for
+          manually compiled/installed applications. Packages should
+          never place anything there.</para>
+      </listitem>
+
+      <listitem>
+        <para><filename>/usr/libexec/</filename> is <emphasis
+          >not</emphasis> used in CRUX, thus packages should never
+          install anything there. Use <filename
+          >/usr/lib/<replaceable
+          >&lt;prog&gt;</replaceable>/</filename> instead.</para>
+      </listitem>
+    </itemizedlist>
+  </section>
+
+  <section id="Remove-Junk-Files">
+    <title>Remove Junk Files</title>
+
+    <itemizedlist>
+     <listitem>
+       <para>Packages should not contain <quote>junk files</quote>.
+         This includes info pages and other online documentation, man
+         pages excluded (e.g. <filename>usr/doc/*</filename>,
+         <filename>README</filename>, <filename>*.info</filename>,
+         <filename>*.html</filename>, etc).</para>
+     </listitem>
+
+     <listitem>
+       <para>Files related to NLS (national language support), always
+         use <userinput>--disable-nls</userinput> when available.</para>
+     </listitem>
+
+     <listitem>
+       <para>Useless or obsolete binaries (e.g.
+         <filename>/usr/games/banner</filename> and
+         <filename>/sbin/mkfs.minix</filename>).</para>
+     </listitem>
+    </itemizedlist>
+  </section>
+
+  <section id="Pkgfile">
+    <title>Pkgfile</title>
+
+    <itemizedlist>
+      <listitem>
+        <para>Do not add new variables to the <filename>Pkgfile</filename>.
+          Only in very few cases does this actually improve the
+          readability or the quality of the package. Further, the only
+          variables that are guranteed to work with future versions of
+          <userinput>pkgmk</userinput> are <literal>name</literal>,
+          <literal>version</literal>, <literal>release</literal>,
+          and <literal>source</literal>. Other names could be in
+          conflict with internal variables in
+          <userinput>pkgmk</userinput>.</para>
+      </listitem>
+
+      <listitem>
+        <para>Use the <literal>$name</literal> and
+          <literal>$version</literal> variables to make the package
+          easier to update/maintain. For example, 
+          <literal>source=(http://xyz.org/$name-$version.tar.gz)</literal>
+          is better than
+          <literal>source=(http://xyz.org/myprog-1.0.3.tar.gz)</literal>
+          since the URL will automatically updated when you modify the
+          <literal>$version</literal> variable.</para>
+      </listitem>
+
+      <listitem>
+        <para>Remember that source is an array, i.e. always do
+          <literal>source=(...)</literal> and not
+          <literal>source=...</literal></para>
+      </listitem>
+    </itemizedlist>
+  </section>
+</section>
diff --git a/doc/handbook/pdf.xsl b/doc/handbook/pdf.xsl
new file mode 100644
index 0000000..0047f62
--- /dev/null
+++ b/doc/handbook/pdf.xsl
@@ -0,0 +1,27 @@
+<?xml version='1.0'?>
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+
+<xsl:import href="/usr/share/xml/docbook/xsl/fo/docbook.xsl"/>
+
+<xsl:param name="paper.type" select="'A4'"/>
+<xsl:param name="fop.extensions" select="1"/>
+<xsl:param name="chapter.autolabel" select="1"/>
+<xsl:param name="section.autolabel" select="1"/>
+<xsl:param name="section.label.includes.component.label" select="2"/>
+<xsl:param name="title.margin.left" select="'0pc'"/>
+<xsl:param name="shade.verbatim" select="1"/>
+<xsl:attribute-set name="shade.verbatim.style">
+  <xsl:attribute name="padding-top">0.3em</xsl:attribute>
+  <xsl:attribute name="padding-bottom">0.3em</xsl:attribute>
+  <xsl:attribute name="padding-start">0.3em</xsl:attribute>
+  <xsl:attribute name="padding-end">0.3em</xsl:attribute>
+<!--
+  <xsl:attribute name="margin-left">0.1em</xsl:attribute>
+  <xsl:attribute name="margin-right">0.1em</xsl:attribute>
+  <xsl:attribute name="margin-top">0.1em</xsl:attribute>
+  <xsl:attribute name="margin-bottom">0.1em</xsl:attribute>
+-->
+</xsl:attribute-set>
+
+</xsl:stylesheet>
diff --git a/doc/handbook/ports.xml b/doc/handbook/ports.xml
new file mode 100644
index 0000000..09c1070
--- /dev/null
+++ b/doc/handbook/ports.xml
@@ -0,0 +1,375 @@
+<!-- $Id: ports.xml,v 1.2 2004/05/20 22:57:20 per Exp $ -->
+
+<title>The Ports System</title>
+
+<section id="The-Ports-System-Introduction">
+  <title>Introduction</title>
+
+  <section id="What-is-a-Port">
+    <title>What is a Port?</title>
+
+    <para>A port is a directory containing the files needed for building
+      a package using <userinput>pkgmk</userinput>. This means that this
+      directory at least has the files <filename>Pkgfile</filename>
+      (which is the package build description) and <filename>.footprint</filename>
+      (which is used for regression testing and contains a list of
+      files this package is expected to contain once it is built).
+      Further, a port directory can contain patches and/or other files
+      needed for building the package. It is important to understand
+      that the actual source code for the package is not
+      necessarily present in port directory. Instead the
+      <filename>Pkgfile</filename> contains an URL which points to
+      a location where the source can be downloaded.</para>
+
+    <para>The use of the word <emphasis>port</emphasis> in this context is borrowed from
+      the BSD world, where a <emphasis>port</emphasis> refers to a program that has been
+      ported to a system or platform. The word can sometimes be a
+      bit misleading since most programs require no actual porting to
+      run on CRUX (or on Linux in general).</para>
+  </section>
+
+  <section id="What-is-the-Ports-System">
+    <title>What is the Ports System?</title>
+
+    <para>The term <emphasis>Ports System</emphasis> refers to a CVS
+      repository containing <emphasis>ports</emphasis> and a client
+      program capable of downloading <emphasis>ports</emphasis> from
+      that CVS repository. CRUX users use the <userinput>ports(8)</userinput>
+      utility to download ports from the CVS repositorty and place
+      them in <filename>/usr/ports/</filename>. The
+      <userinput>ports</userinput> utility uses <userinput><ulink url="http://www.cvsup.org/">CVSup(1)</ulink></userinput>
+      to do the actual downloading/synchronization.</para>
+  </section>
+</section>
+
+<section id="Using-the-Ports-System">
+  <title>Using the Ports System</title>
+
+  <section id="Synchronizing-Your-Local-Ports-Structure">
+    <title>Synchronizing Your Local Ports Structure</title>
+
+    <para>When CRUX is installed for the first time the local ports
+      structure (<filename>/usr/ports/</filename>) is empty. To
+      bring your local ports structure up to date you use the
+      <userinput>ports</userinput> utility with the <userinput>-u</userinput>
+      option. Example:</para>
+
+    <informalexample>
+      <screen>$ <userinput>ports -u</userinput></screen>
+    </informalexample>
+
+    <para>The <userinput>-u</userinput> option means <emphasis>update</emphasis>,
+      and tells <userinput>ports</userinput> to contact the ports CVS
+      repository and download new and updated ports. The output from
+      this execution is something like this:</para>
+
+    <informalexample>
+<screen>Connected to cvsup.fukt.bth.se
+Updating collection base/cvs
+...
+Updating collection opt/cvs
+...
+Finished successfully</screen>
+    </informalexample>
+
+    <para>The output reveals which files are downladed, updated and
+      deleted.</para>
+  </section>
+
+  <section id="Listing-Local-Ports">
+    <title>Listing Local Ports</title>
+
+    <para> When the local ports structure has been updated the
+      directory <filename>/usr/ports/</filename> will contain two
+      package categories, <filename>base</filename> and
+      <filename>opt</filename>. Under each of these directories
+      you will find ports. You can simply browse around in the directory
+      structure to find out which ports are available.</para>
+
+    <informalexample>
+<screen>$ <userinput>cd /usr/ports/base/</userinput>
+$ <userinput>ls</userinput>
+autoconf/   filesystem/  man/            sh-utils/
+automake/   fileutils/   man-pages/      shadow/
+bash/       findutils/   modutils/       sysklogd/
+bin86/      flex/        nasm/           sysvinit/
+binutils/   gawk/        ncurses/        tar/
+bison/      gcc/         net-tools/      tcp_wrappers/
+bsdinit/    glibc/       netkit-base/    tcsh/
+bzip2/      grep/        patch/          textutils/
+cpio/       groff/       perl/           time/
+db/         gzip/        pkgutils/       traceroute/
+dcron/      kbd/         procps/         util-linux/
+devfsd/     less/        psmisc/         vim/
+diffutils/  libtool/     readline/       wget/
+e2fsprogs/  lilo/        reiserfsprogs/  which/
+ed/         m4/          sed/            zlib/
+file/       make/        sendmail/</screen>
+    </informalexample>
+
+    <para>You can also use <userinput>ports</userinput> with the
+      <userinput>-l</userinput> option to list all local ports. Example:</para>
+
+    <informalexample>
+<screen>$ <userinput>ports -l</userinput>
+base/autoconf
+base/automake
+base/bash
+base/bin86
+base/binutils
+base/bison
+...</screen>
+    </informalexample>
+
+    <para>If you are looking for a specific package it might be easier
+      to use this approach (e.g. <userinput>ports&nbsp;-l&nbsp;| grep&nbsp;sendmail</userinput>)
+      to find out if the package is available and if so in which
+      category it is located.</para>
+  </section>
+
+  <section id="Listing-Version-Differences">
+    <title>Listing Version Differences</title>
+
+    <para>To find out if the ports structure carries ports that are
+      different (likely newer) compared to the versions currently
+      installed you can use the option <userinput>-d</userinput>.
+      If version differences are found, the output from the above
+      command could look something like this:</para>
+
+    <informalexample>
+<screen>$ <userinput>ports -d</userinput>
+Collection  Name     Port     Installed
+base        glibc    2.3.2-2  2.3.3-1
+opt         gtk      2.2.0-1  2.4.0-1</screen>
+    </informalexample>
+
+    <para>If no version differences were found, i.e. the system is in sync with the ports structure. Then output will simply be:</para>
+
+    <informalexample>
+<screen>$ <userinput>ports -d</userinput>
+No differences found</screen>
+    </informalexample>
+  </section>
+
+  <section id="Building-and-Installing-Packages">
+    <title>Building and Installing Packages</title>
+
+    <para>Once you have found a port that you want to build and install
+      you simply go into the desired port directory and use
+      <userinput>pkgmk</userinput> to build it. Example:</para>
+
+    <informalexample>
+<screen>$ <userinput>cd /usr/ports/base/sendmail</userinput>
+$ <userinput>pkgmk -d</userinput></screen>
+    </informalexample>
+
+    <para>The <userinput>-d</userinput> option means <emphasis>download
+      missing source files</emphasis> and tells <userinput>pkgmk</userinput>
+      to download the source(s) specified in the <filename>Pkgfile</filename>
+      (in case the source is already downloaded this option is ignored).
+      When the download is completed the package will be built. If the
+      package was built successfully you can use <userinput>pkgadd</userinput>
+      to install or upgrade it. Example:</para>
+
+    <informalexample>
+<screen>$ <userinput>pkgadd sendmail#8.11.6-2.pkg.tar.gz</userinput></screen>
+    </informalexample>
+
+    <para>To make life a bit easier these two steps can be made into
+      one by using the options <userinput>-i</userinput> (for install)
+      or <userinput>-u</userinput> (for upgrade). Example:</para>
+
+    <informalexample>
+<screen>$ <userinput>pkgmk -d -i</userinput></screen>
+    </informalexample>
+
+    <para>or</para>
+
+    <informalexample>
+      <screen>$ <userinput>pkgmk -d -u</userinput></screen>
+    </informalexample>
+
+    <para>This will download, build and then install/upgrade the
+      package. Note that the package will only be installed/upgraded
+      if the build is successful.</para>
+  </section>
+</section>
+
+<!--
+OBSOLETE SECTION
+
+<section>
+  <title>Contributing Ports</title>
+
+  <section id="Contributing-Ports-Introduction">
+    <title>Introduction</title>
+
+    <para>The ports system has three sections <filename>base</filename>,
+      <filename>opt</filename> and <filename>contrib</filename>. Sections
+      <filename>base</filename> and <filename>opt</filename> are
+      maintained by me (Per Lid&eacute;n) while the contrib section
+      is maintained by trusted port contributors (contrib maintainers)
+      which have been given write access to the CVS repository. People
+      that create ports are encuraged to publish them on the web and
+      send the URL to the mailinglist to inform others about their work.
+      The contrib maintainers will (when time permits) have a look at
+      them. If they find that the ports are properly made, follow the
+      guidelines and add a <emphasis>real</emphasis> value to CRUX
+      they might decide to add them to the CVS <filename>contrib</filename>
+      section. Please keep in mind that just because someone has made
+      a port it does not mean that it will be included in the
+      <filename>contrib</filename> section. The ports that go into the
+      <filename>contrib</filename> section are carefully selected by the
+      contrib maintainers.</para>
+  </section>
+
+  <section id="Contrib-Maintainers">
+    <title>Contrib Maintainers</title>
+
+    <para>The table below contains the names and e-mail addresses of
+      the people that currenty has write permissions to the
+      <filename>contrib</filename> section of the ports repository.</para>
+
+    <informaltable>
+      <tgroup cols="2">
+        <thead>
+          <row>
+            <entry>Name</entry>
+
+            <entry>E-mail</entry>
+          </row>
+        </thead>
+
+        <tbody>
+          <row>
+            <entry>J&uuml;rgen Daubert (jue)</entry>
+
+            <entry><filename>Juergen.Daubert@t-online.de</filename></entry>
+          </row>
+
+          <row>
+            <entry>Markus Ackermann (maol)</entry>
+
+            <entry><filename>maol@symlink.ch</filename></entry>
+          </row>
+
+          <row>
+            <entry>Jussi M&auml;ki (valen)</entry>
+
+            <entry><filename>valen@ihanaa.org</filename></entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </informaltable>
+  </section>
+
+  <section id="Quick-CVS-Manual">
+    <title>Quick CVS Manual</title>
+
+    <para>This section is a quick introduction on how to add a port to
+      the CRUX CVS repository. For more information about CVS, see
+      <ulink url="http://www.cvshome.org/docs/">http://www.cvshome.org/docs/</ulink>.</para>
+
+    <note>
+      <para>Only trusted port contributors with a CVS account can access
+        the repository this way. Regular CRUX users access the
+        repository (read only) using the ports system.</para>
+    </note>
+
+    <para>Settings:</para>
+
+    <informalexample>
+<screen>$ <userinput>export CVSROOT=:ext:<replaceable>username</replaceable>@cvs.fukt.bth.se:/home/per/crux/ports</userinput>
+$ <userinput>export CVS_RSH=ssh</userinput></screen>
+    </informalexample>
+
+    <para>Checking out/Updating the contrib tree:</para>
+
+    <informalexample>
+      <informaltable>
+        <tgroup cols="2">
+          <tbody>
+            <row>
+              <entry><screen>$ <userinput>cvs checkout -r \</userinput>
+>  <userinput>STABLE-<replaceable>X_X_X</replaceable> contrib</userinput></screen></entry>
+
+              <entry>get a fresh copy of the contrib tree</entry>
+            </row>
+
+            <row>
+              <entry><screen>$ <userinput>cvs update -d -r \</userinput>
+>  <userinput>STABLE-<replaceable>X_X_X</replaceable> contrib</userinput></screen></entry>
+
+              <entry>update an already checked out tree</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </informaltable>
+    </informalexample>
+
+    <para>Adding a new port to the contrib tree:</para>
+
+    <informalexample>
+      <informaltable>
+        <tgroup cols="2">
+          <tbody>
+            <row>
+              <entry><screen>$ <userinput>cd crontrib</userinput>
+$ <userinput>mkdir <replaceable>myport</replaceable></userinput>
+$ <userinput>cvs add <replaceable>myport</replaceable></userinput></screen></entry>
+
+              <entry>add port directory</entry>
+            </row>
+
+            <row>
+              <entry><screen>$ <userinput>cd <replaceable>myport</replaceable></userinput>
+&lt;create Pkgfile, .footprint, .md5sum, etc&gt;
+$ <userinput>cvs add Pkgfile .footprint .md5sum</userinput></screen></entry>
+
+              <entry>schedule files for addition</entry>
+            </row>
+
+            <row>
+              <entry><screen>$ <userinput>cvs commit -m "<replaceable>Comment...</replaceable>"</userinput></screen></entry>
+
+              <entry>commit changes/additions</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </informaltable>
+    </informalexample>
+  </section>
+
+  <section id="CVS-Guidelines">
+    <title>CVS Guidelines</title>
+    <itemizedlist>
+      <listitem>
+        <para>The name of a port directory should always be the same
+          as the package name specified in the <filename>Pkgfile</filename> (i.e.
+          lowercase).</para>
+      </listitem>
+
+      <listitem>
+        <para>At least, have the following two lines in the top of
+          your <filename>Pkgfile</filename>:</para>
+
+        <informalexample>
+<programlisting># $Id: ports.xml,v 1.2 2004/05/20 22:57:20 per Exp $
+# Maintainer: <replaceable>Your Name</replaceable> &lt;<replaceable>your@mail.org</replaceable>&gt;</programlisting>
+        </informalexample>
+      </listitem>
+
+      <listitem>
+        <para>Never add any binary files (like <filename>.gz</filename>)
+          to the repository, only plain text ASCII files are allowed.</para>
+      </listitem>
+
+      <listitem>
+        <para>Please think twice before adding/committing/tagging files.</para>
+      </listitem>
+    </itemizedlist>
+  </section>
+</section>
+
+END OBSOLETE SECTION
+-->