Index: trunk/doc/guide/Makefile
===================================================================
--- trunk/doc/guide/Makefile	(revision 4425)
+++ trunk/doc/guide/Makefile	(revision 4478)
@@ -1,3 +1,3 @@
-# $Id: Makefile,v 1.7 2003/07/20 17:00:51 fkr Exp $
+# $Id: Makefile,v 1.8 2004/01/06 09:19:36 fkr Exp $
 
 # To build DarwinPorts  guide files from the source docbook xml.
@@ -28,5 +28,5 @@
 
 SOURCEDIR?=		xml
-DOCBOOK_XSL?=	        ${prefix}/share/xsl/docbook-xsl/1.61.0
+DOCBOOK_XSL?=	        ${prefix}/share/xsl/docbook-xsl/
 HTMLDIR?=		html
 XHTMLDIR?=		xhtml
@@ -35,4 +35,5 @@
 XML_CATALOG_FILES?=    ${prefix}/etc/xml/catalog
 XML_DEBUG_CATALOG?=
+STRINGPARAMS?=		--stringparam html.stylesheet docbook.css 
 
 .PHONY : all
@@ -53,5 +54,5 @@
 xhtml: 
 	mkdir -p ${XHTMLDIR}
-	xsltproc --xinclude -o "${XHTMLDIR}/" "${XSTYLESHEET}" "${SOURCEDIR}/guide.xml"
+	xsltproc --xinclude ${STRINGPARAMS} -o "${XHTMLDIR}/" "${XSTYLESHEET}" "${SOURCEDIR}/guide.xml"
 
 all: html xhtml tidy
Index: trunk/doc/guide/resources/docbook.css
===================================================================
--- trunk/doc/guide/resources/docbook.css	(revision 4478)
+++ trunk/doc/guide/resources/docbook.css	(revision 4478)
@@ -0,0 +1,100 @@
+/*
+ * DarwinPorts Guide Stylesheet
+ */
+
+* {
+	font-family: Georgia, "New Century Schoolbook", "Times New Roman", Times, serif;
+}
+
+body {
+	background: #e3f1c7;
+	width: 720px;
+	margin: 15px auto 15px auto;
+	font-size: 12px;
+        line-height: 1.2;
+}
+
+a:link {
+	color: #669;
+	text-decoration: none;
+	font-weight: bold;
+	border-bottom: 1px dotted #c63;
+}
+
+a:visited {
+	color: #888;
+	text-decoration: none;
+	font-weight: bold;
+	border-bottom: 1px dotted #669;
+}
+
+a:hover {
+	color: #c63;
+	text-decoration: none;
+	font-weight: bold;
+	border-bottom: 1px dotted #369;
+}
+
+hr { 
+	display: none;
+}
+
+h3.title {
+	color: #879880;
+	margin: 1em 0 1em 0;
+	padding: 0;
+	border-bottom: 1px solid #ddd;
+}
+
+h4.title {
+	color: #999;
+	margin: 0 auto;
+	padding: 0;
+}
+
+h1.title, h2.title {
+	color: #669;
+	margin: 5px 0 5px 0;
+	padding: 10px 0 0 0;
+	border-bottom: 1px solid #bbb;
+}
+
+.navheader, 
+.navfooter, 
+div.book,
+div.part,
+div.chapter,
+div.preface,
+div.sect1 {
+	background: #fff;
+	padding: 0.5em 2em;
+	margin: 0.5em; 
+	border: 1px solid #bbb;
+}
+
+div.chapter div.sect1, div.preface div.sect1 {
+	border: 0;
+	padding: 0;
+	margin: 0;
+}
+
+div.sect2, div.sect3 {
+	margin: 0 1em;
+}
+
+pre.programlisting {
+	color: #669;
+	font-family: "Courier New", Courier;	
+}
+
+.userinput {
+	color: #669;
+}
+
+tt {
+	font-family: "Courier New", Courier;	
+}
+
+.filename {
+	color: #673;
+}
Index: trunk/doc/guide/xml/guide.xml
===================================================================
--- trunk/doc/guide/xml/guide.xml	(revision 4425)
+++ trunk/doc/guide/xml/guide.xml	(revision 4478)
@@ -3,8 +3,7 @@
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
-
-<book xmln:xi="http://www.w3.org/2001/XInclude">
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
   <bookinfo>
-    <title>DarwinPorts User Guide</title>
+    <title>DarwinPorts Guide</title>
       
     <author>
@@ -18,4 +17,12 @@
     </author>
 
+		<author>
+			<firstname>Will</firstname>
+			<surname>Barton</surname>
+			<affiliation>
+				<address><email>wbb4@opendarwin.org</email></address>
+			</affiliation>
+		</author>
+
     <copyright>
       <year>2002</year>
@@ -27,6 +34,9 @@
   <preface>
     <title>About this guide</title>
-      <para>This guide shows you how to use the DarwinPorts system and
-	develop new DarwinPorts.</para>
+      <para>Part I of this guide is intended to help you use
+        to DarwinPorts system.  The Part II is directed towards
+        users who wish to add their favorite software to DarwinPorts.
+        The Part III is intended for developers interested in extending
+        the DarwinPorts system.</para>
 
       <para>The Guide is still at an early draft stage, if you have any
@@ -36,12 +46,46 @@
   </preface>
 
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="user.xml" /> 
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="quick.xml" />
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="details.xml" /> 
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="submission.xml" /> 
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="special.xml" /> 
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="variants.xml" />
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="style.xml" />
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="testing.xml" /> 
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="commands.xml" /> 
+  <part>
+    <title>Using DarwinPorts</title>
+
+    <xi:include href="user/user.xml" /> 
+
+    <xi:include href="user/dp_manager.xml" /> 
+  </part>
+
+  <part>
+    <title>DarwinPorts Portfiles</title>
+    
+    <xi:include href="portfiles/quick.xml" />
+    
+		<xi:include href="portfiles/details.xml" /> 
+    
+		<xi:include href="portfiles/hier.xml" /> 
+
+    <xi:include href="portfiles/special.xml" /> 
+
+    <xi:include href="portfiles/variants.xml" />
+
+    <xi:include href="portfiles/style.xml" />
+
+    <xi:include href="portfiles/testing.xml" /> 
+    
+    <xi:include href="portfiles/commands.xml" /> 
+  </part>
+
+  <part>
+    <title>DarwinPorts Internals</title>
+  
+    <xi:include href="internals/internals.xml" /> 
+	</part>
+
+	<part>
+		<title>The DarwinPorts Project</title>
+
+    <xi:include href="project/roadmap.xml" /> 
+
+    <xi:include href="project/policies.xml" /> 
+
+    <xi:include href="project/submission.xml" /> 
+  </part>
  </book>
Index: trunk/doc/guide/xml/internals/internals.xml
===================================================================
--- trunk/doc/guide/xml/internals/internals.xml	(revision 4478)
+++ trunk/doc/guide/xml/internals/internals.xml	(revision 4478)
@@ -0,0 +1,209 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<chapter id="internals">
+  <chapterinfo>
+    <keywordset>
+      <keyword>
+      </keyword>
+    </keywordset>
+  </chapterinfo>
+  
+  <title>DarwinPorts APIs</title> 
+
+  <sect1 id="about">
+    <title>About This Chapter</title>
+
+    <para>DarwinPorts contains two application programming interfaces
+    (APIs), written in Tcl.</para>
+    
+    <para>The Ports API is an internal API used to run individual
+      Portfiles.  The DarwinPorts (dport*) API is a high-level API used by
+      client applications such as DarwinPorts Manager.app or
+      <command>port</command>.</para>
+  </sect1>
+
+  <sect1 id="ports-api">
+    <title>Ports API</title>
+
+    <para>The code for the Port API is located in
+      <filename>base/src/port1.0</filename>.  The Port API performs the
+      following functions:</para>
+
+    <para>
+      <itemizedlist>
+        <listitem>
+          <para>Manages target registrations.  All targets register
+            themselves with the Port API.  Accordingly, the Port API
+            creates pre-/post-/main overrides for each of the targets.</para>
+        </listitem>
+
+        <listitem>
+          <para>Option/Default handling.  All
+            <filename>Portfile</filename> options
+            (<function>name</function>, <function>version</function>,
+            <function>revision</function> ...) are registered by targets.
+            The Port API creates procedures for these options, and sets
+            up the complex variable traces necessary to support option
+            defaults.</para>
+        </listitem>
+
+        <listitem>
+          <para>Executes target procedures, including the pre/post/main
+            routines.</para>
+        </listitem>
+
+        <listitem>
+          <para>Manages a state file containing information about what
+            variants were specified and what targets have run
+            successfully.</para>
+        </listitem>
+
+        <listitem>
+          <para>Provides essential portfile primitives (such as
+            <function>reinplace</function>).</para>
+        </listitem>
+
+        <listitem>
+          <para>Provides simple access to the ui_event mechanism by
+            providing the various ui_ procedures (i.e.,
+            <function>ui_msg</function>,
+            <function>ui_error</function>).</para>
+        </listitem>
+
+      </itemizedlist>
+    </para>
+
+  </sect1>
+
+  <sect1 id="dp_api">
+    <title>DarwinPorts API</title>
+
+    <para>The code for the DarwinPorts API is located in
+      base/src/darwinports1.0. The DarwinPorts API performs the
+      following functions:</para>
+
+    <para>
+      <itemizedlist>
+        <listitem>
+          <para>Dependency implementation. This portion is implemented
+            in a highly generic fashion, and is used throughout the
+            system. The dependency functions are exported to the Port
+            API, and the Port API uses them execute targets in the
+            correct order.</para>
+        </listitem>
+
+        <listitem>
+          <para>Software dependencies. Software dependencies are handled
+            at this layer using the dependency implementation.</para>
+        </listitem>
+
+        <listitem>
+          <para>UI abstractions. UI Abstractions are handled at this
+            layer. Each port action is provided a context, and a
+            mechanism for posting user interface events is exported to
+            the Port API (<function>ui_event</function>).</para>
+        </listitem>
+
+        <listitem>
+          <para>Registry management routines. Manages the rudimentary
+            port registry in
+            <filename>${prefix}/var/db/dports/receipts/</filename>.</para>
+
+          <para>
+            <itemizedlist>
+              <listitem>
+                <para><function>dportregistry::new</function>: create a
+                  new port registry entry</para>
+              </listitem>
+
+              <listitem>
+                <para><function>dportregistry::exists</function>: check
+                  if a port registry entry exists (either versioned or
+                  not)</para>
+              </listitem>
+
+              <listitem>
+                <para><function>dportregistry::delete</function>: delete
+                  an existing registry entry</para>
+              </listitem>
+
+              <listitem>
+                <para><function>dportregistry::close</function>: closes
+                  a new registry entry</para>
+              </listitem>
+            </itemizedlist>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>Exports the "darwinports" API for use by client
+            applications:</para>
+
+          <para>
+            <itemizedlist>
+              <listitem>
+                <para><function>dportinit</function>: Initializes the
+                  darwinports system. Should be called before trying to
+                  use any other procedure</para>
+              </listitem>
+
+              <listitem>
+                <para><function>dportsearch</function>: Given a regexp,
+                  searches the PortIndex for ports with matching
+                  names</para>
+              </listitem>
+
+              <listitem>
+                <para><function>dportopen</function>: Given a URI to a
+                  port, opens the port and returns an opaque handle to
+                  it</para>
+              </listitem>
+
+              <listitem>
+                <para><function>dportclose</function>: Given a port
+                  handle, closes the port.</para>
+              </listitem>
+
+              <listitem>
+                <para><function>dportexec</function>: Given a port
+                  handle, executes a target (i.e. install)</para>
+              </listitem>
+
+              <listitem>
+                <para><function>dportinfo</function>: Given a port
+                  handle, this returns the PortInfo array (as a flat
+                  list of array elements). This is a little tricky and
+                  unstable and only used by the 'portindex'
+                  command</para>
+              </listitem>
+
+              <listitem>
+                <para><function>dpoprtdepends</function>: Given a port
+                  handle, returns a list of ports the specified port
+                  depends upon</para>
+              </listitem>
+            </itemizedlist>
+          </para>
+        </listitem>
+      </itemizedlist>
+    </para>
+    
+    <para>An example of how the DarwinPorts API is used:</para>
+
+    <para><function>dportsearch</function> returns an arbitrary number
+      of Tcl arrays containing data from the
+      <filename>PortIndex</filename>. The returned data includes the
+      port name, version, revision, epoch, variants, depends, etc. When
+      one executes <userinput>port install cm3</userinput>, the
+      <command>port</command> utility uses the
+      <function>dportsearch</function> function to find the first port
+      that matches the name "cm3", uses <function>dportopen</function>
+      to open the port, and then uses <function>dportexec</function> to
+      execute the install target in the port. Then, it uses
+      <function>dportclose</function> to close the port. When one
+      executes <userinput>port search cm3</userinput>, the port utility
+      uses <function>dportsearch</function>, takes the list of arrays,
+      and formats the data for human consumption.</para>
+  </sect1>
+</chapter>
Index: trunk/doc/guide/xml/portfiles/commands.xml
===================================================================
--- trunk/doc/guide/xml/portfiles/commands.xml	(revision 4478)
+++ trunk/doc/guide/xml/portfiles/commands.xml	(revision 4478)
@@ -0,0 +1,512 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<chapter id="commands">
+  <title>Portfile Command Reference</title>
+
+  <sect1>
+    <title>Commands</title>
+    
+    <sect2>
+      <title>Fetch Options</title>
+
+      <para></para>
+
+    </sect2>
+    
+    <sect2>
+      <title>Extract Options</title>
+
+      <variablelist>
+        <varlistentry>
+          <term>extract.only</term>
+
+          <listitem>
+            <synopsis>Type: Optional Default: ${distfiles}</synopsis>
+
+            <para>List of files to extract into ${workpath}.</para>
+
+            <para><userinput>extract.only worksrc-1.4.4.tar.gz
+            </userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>extract.cmd</term>
+
+          <listitem>
+            <synopsis>Type: optional Default: gzip</synopsis>
+
+            <para>Command to perform extract.</para>
+
+            <para><userinput>extract.cmd bzip2</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>extract.pre_args</term>
+
+          <listitem>
+            <synopsis>Type: optional Default: -dc</synopsis>
+
+            <para>Arguments added to ${extract.cmd} before a file name.</para>
+
+            <para><userinput>extract.pre_args -cd</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>extract.args</term>
+
+          <listitem>
+            <synopsis>Type: read-only Default: ${distpath}/${distfile}</synopsis>
+
+            <para>Arguments to ${extract.cmd}.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>extract.post_args</term>
+
+          <listitem>
+            <synopsis>Type: optional Default: | tar -xf -</synopsis>
+
+            <para>Arguments added to extract command after a file name.</para>
+
+            <para><userinput>
+            extract.post_args | tar -x -s@bladeenc-0.94.2/other_makefiles/BladeEnc..@@p -f -
+            </userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>extract.sufx</term>
+
+          <listitem>
+            <synopsis>Type: optional Default: .tar.gz</synopsis>
+
+            <para>Suffix to append to ${distname}</para>
+
+            <para><userinput>extract.sufx .tgz</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>use_zip</term>
+
+          <listitem>
+            <synopsis>Type: optional</synopsis>
+
+            <para>Sets extract.sufx to: .zip Sets extract.cmd to: 
+            unzip Sets extract.pre_args to: -q Sets extract.post_args 
+            to: "-d $portpath/$workdir"</para>
+
+            <para><userinput>use_zip yes</userinput></para>
+
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect2>
+    
+    <sect2>
+      <title>File Verification Options</title>
+		<variablelist>
+		  <varlistentry>
+			  <term>checksums</term>
+	
+			  <listitem>
+				<synopsis>Type: optional</synopsis>
+				
+				<para>List of checksums in the format: &lt;file name&gt; 
+				&lt;checksum type&gt; &lt;checksum&gt; Currently, the only 
+				supported checksum type is md5. If only one file is 
+				downloaded, the filename may be ommitted.</para>
+
+				<para><userinput>checksums dictd-1.7.1.tar.gz 
+				md5 81317b86ea0a5df0163900ad2e6bb12c</userinput></para>
+
+			  </listitem>
+			</varlistentry>
+      </variablelist>
+    </sect2>
+
+    <sect2>
+      <title>CVS Options</title>
+
+      <para></para>
+
+    </sect2>
+
+    <sect2>
+      <title>Patch Options</title>
+
+      <para></para>
+
+    </sect2>
+	<sect2>
+      <title>Configure Options</title>
+
+      <variablelist>
+        <varlistentry>
+          <term>configure.pre_args</term>
+
+          <listitem>
+            <synopsis>Type: optional</synopsis>
+
+            <para>Arguments added to configure command before 
+            ${configure.args}.</para>
+
+            <para><userinput>configure.pre_args 
+            --prefix=${prefix}/etc</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>configure.args</term>
+
+          <listitem>
+            <synopsis>Type: optional</synopsis>
+
+            <para>Arguments to pass to ${configure.cmd}.</para>
+
+            <para><userinput>configure.args 
+            --etcdir=${prefix}/etc</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>configure.dir</term>
+
+          <listitem>
+            <synopsis>Type: optional</synopsis>
+
+            <para>Directory in which to run ${configure-cmd}.</para>
+
+            <para><userinput>configure.dir src</userinput></para>
+
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect2>
+
+    <sect2>
+      <title>Automake Options</title>
+
+      <variablelist>
+        <varlistentry>
+          <term>use_automake</term>
+
+          <listitem>
+            <synopsis>Type: optional Default: ${workpath}/${worksrcdir}
+            </synopsis>
+
+            <para>If set to yes, use ${automake.cmd}.</para>
+
+            <para><userinput>use_automake yes</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>automake.env</term>
+
+          <listitem>
+            <synopsis>Type: optional</synopsis>
+
+            <para>Environmental variables to pass to ${automake.cmd}.</para>
+
+            <para><userinput>automake.env 
+            CFLAGS=-I${prefix}/include/gtk12</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>automake.args</term>
+
+          <listitem>
+            <synopsis>Type: optional</synopsis>
+
+            <para>Arguments to pass to ${automake.cmd}.</para>
+
+            <para><userinput>automake.args --foreign</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>automake.dir</term>
+
+          <listitem>
+            <synopsis>Type: optional Default: 
+            ${workpath}/${worksrcdir}</synopsis>
+
+            <para>Directory in which to run ${automake.cmd}.</para>
+
+            <para><userinput>automake.dir src</userinput></para>
+
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect2>
+
+    <sect2>
+      <title>Autoconf Options</title>
+
+      <variablelist>
+        <varlistentry>
+          <term>use_autoconf</term>
+
+          <listitem>
+            <synopsis>Type: Optional</synopsis>
+
+            <para>If set to yes, run ${autoconf.cmd}.</para>
+
+            <para><userinput>use_autoconf yes</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>autoconf.env</term>
+
+          <listitem>
+            <synopsis>Type: optional</synopsis>
+
+            <para>Environment variables to pass to ${autoconf.cmd}.</para>
+
+            <para><userinput>autoconf.env 
+            CFLAGS=-I${prefix}/include/gtk12</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>autoconf.args</term>
+
+          <listitem>
+            <synopsis>Type: optional</synopsis>
+
+            <para>Arguments to pass to ${autoconf.cmd}.</para>
+
+            <para><userinput>autoconf.args -l 
+            src/aclocaldir</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>autoconf.dir</term>
+
+          <listitem>
+            <synopsis>Type: optional Default: ${autoconf.dir}</synopsis>
+
+            <para>Directory in which to run ${autoconf.cmd}.</para>
+
+            <para><userinput>autoconf.dir src</userinput></para>
+
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect2>
+    
+    <sect2>
+      <title>Build Options</title>
+
+      <variablelist>
+        <varlistentry>
+          <term>build.cmd</term>
+
+          <listitem>
+            <synopsis>cmdType: optional, Default: make</synopsis>
+
+            <para>Make command to run relative to ${worksrcdir}.</para>
+
+            <para><userinput>build.cmd pbxbuild</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>build.type</term>
+
+          <listitem>
+            <synopsis>Type: optional Default: make</synopsis>
+
+            <para>Defines which 'make' is required, either 'gnu' or 'bsd' 
+            Sets build.cmd to either 'gnumake' or 'bsdmake' accordingly</para>
+
+            <para><userinput>build.type bsd</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>build.pre_args</term>
+
+          <listitem>
+            <synopsis>Type: read-only Default: ${build.target}</synopsis>
+
+            <para>Arguments to pass to ${build.cmd} before ${build.args}.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>build.args</term>
+
+          <listitem>
+            <synopsis>Type: optional</synopsis>
+
+            <para>Arguments to pass to ${build.cmd}.</para>
+
+            <para><userinput>build.args -DNOWARN</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>build.target</term>
+
+          <listitem>
+            <synopsis>Type: optional Default: all</synopsis>
+
+            <para>Target to pass to make for building everything.</para>
+
+            <para><userinput>build.target all-src</userinput></para>
+
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect2>
+
+    <sect2>
+      <title>Install Options</title>
+
+      <variablelist>
+        <varlistentry>
+          <term>install.cmd</term>
+
+          <listitem>
+            <synopsis>cmdType: optional, Default: ${build.cmd}</synopsis>
+
+            <para>Install command to run relative to ${worksrcdir}.</para>
+
+            <para><userinput>install.cmd pbxbuild</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>install.type</term>
+
+          <listitem>
+            <synopsis>Type: optional Default: ${build.type}</synopsis>
+
+            <para>Defines which 'make' is required, either 'gnu' or 'bsd' 
+            Sets build.cmd to either 'gnumake' or 'bsdmake' 
+            accordingly. </para>
+
+            <para><userinput>install.type gnu</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>install.pre_args</term>
+
+          <listitem>
+            <synopsis>Type: read-only Default: ${install.target}</synopsis>
+
+            <para>Arguments to pass to ${install.cmd} before 
+            ${install.args}.</para>
+            
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>install.args</term>
+
+          <listitem>
+            <synopsis>Type: optional</synopsis>
+
+            <para>Arguments to pass to ${install.cmd}.</para>
+
+            <para><userinput>build.args -DNOWARN</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>install.target</term>
+
+          <listitem>
+            <synopsis>Type: optional Default: install</synopsis>
+
+            <para>Install target to pass to ${install.cmd}.</para>
+
+            <para><userinput>install.target install-src</userinput></para>
+
+          </listitem>
+        </varlistentry>
+
+		<varlistentry>
+          <term>install.destroot</term>
+
+          <listitem>
+            <synopsis>Type: optional Default: DESTDIR='${destroot}'</synopsis>
+
+            <para>Arguement passed to ${install.cmd} to cause port to 
+            install via the temporary destroot.</para>
+
+            <para><userinput>install.destroot prefix='${destroot}'
+            </userinput></para>
+
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect2>
+
+    <sect2>
+      <title>Xmkmf Options</title>
+
+      <variablelist>
+        <varlistentry>
+          <term>xmkmf</term>
+
+          <listitem>
+            <synopsis>
+            </synopsis>
+
+            <para>Does nothing.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect2>
+
+    <sect2>
+      <title>Libtool Options</title>
+
+      <variablelist>
+        <varlistentry>
+          <term>libtool</term>
+
+          <listitem>
+            <synopsis>
+            </synopsis>
+
+            <para>Does nothing.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect2>
+  </sect1>
+</chapter>
+
+
Index: trunk/doc/guide/xml/portfiles/details.xml
===================================================================
--- trunk/doc/guide/xml/portfiles/details.xml	(revision 4478)
+++ trunk/doc/guide/xml/portfiles/details.xml	(revision 4478)
@@ -0,0 +1,1128 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id='details'>
+    <title>Portfile details</title>
+    <para> This Chapter describes in detail how each part of a portfile is 
+    works and is used. </para>
+    
+    <sect1>
+    	<title>General syntax</title>
+    	
+    	<para>A Portfile is a TCL script, so the syntax used must be valid 
+    	TCL or the Portfile will not work. The basic syntax of the Portfile 
+    	has been designed so most tasks are performed using key value(s) 
+    	combinations. Many people don't realise it is TCL until they want to do 
+    	something more advanced and realise all that power is there.</para>
+    	
+		<para>All key value pairs in a Portfile are single lines so line breaks 
+		must be escaped with a back slash ('\'). </para>
+		<para>Variables syntax is ${foo} for the foo variant.</para>
+    	<sect2>
+			<title>Special characters</title>
+			<para>As the Portfile is a TCL script certain charachters are 
+			"special". These have a special meaning in TCL and if you dont 
+			want that special meaning, they must be escaped. In general a 
+			character is escaped using the back slash ('\'). The main 
+			characters you need to be careful with are 
+			<simplelist type="inline">
+					<member>$</member>
+					<member>}</member>
+					<member>}</member>
+					<member>[</member>
+					<member>]</member>
+					</simplelist></para>
+					
+		</sect2>
+		
+		<sect2>
+			<title>Required keys</title>
+			
+			<para>There is a small set of required key/value pairs without 
+			which a Portfile cannot be correct.</para>
+			
+			<para>The required keys are 
+				<simplelist type="vert">
+					<member>PortSystem</member>
+					<member>name</member>
+					<member>version</member>
+					<member>platforms</member>
+					<member>maintainers</member>
+					<member>categories</member>
+					<member>description</member>
+					<member>master_sites</member>
+					<member>checksums</member>
+					<member>homepage</member>
+					<member>long_description</member>
+					
+				</simplelist>
+			Each of these keys is described in the following pages of 
+			the guide. </para>
+
+				
+		</sect2>
+	</sect1>
+	<sect1>
+		<title>Useful preset variables</title>
+		<para></para>
+		<variablelist>
+			<varlistentry id='prefix'>
+				<term>prefix</term>
+				<listitem>
+					<para>Installation prefix, set in the systemwide 
+					configuration file /etc/ports/ports.conf. Can be 
+					overridden on a per port basis. For example XFree86 
+					needs to install in the /usr tree, or aqua applications 
+					are installed in /Applications/Ports</para>
+					
+				</listitem>
+			</varlistentry>
+			
+			<varlistentry id='libpath'>
+				<term>libpath</term>
+				<listitem>
+					<para>Path to the DarwinPorts TCL libraries. Read 
+					only.</para>
+					
+				</listitem>
+			</varlistentry>
+			
+			<varlistentry id='portpath'>
+				<term>portpath</term>
+				<listitem>
+					<para>Path to the directory containing the downloaded 
+					Portfiles. Read Only.</para>
+					
+				</listitem>
+			</varlistentry>
+			
+			<varlistentry id='filedir'>
+				<term>filedir</term>
+				<listitem>
+					<para>Path to port files relative to ${portpath}. 
+					Read Only.</para>
+					
+				</listitem>
+			</varlistentry>
+			
+			<varlistentry id='workdir'>
+				<term>workdir</term>
+				<listitem>
+					<para>Path to work directory relative to ${portpath}. 
+					Read Only</para>
+					
+				</listitem>
+			</varlistentry>
+			
+			<varlistentry id='workpath'>
+				<term>workpath</term>
+				<listitem>
+					<para>Full path to work directory. Read only.</para>
+					
+				</listitem>
+			</varlistentry>
+						
+			<varlistentry id='distpath'>
+				<term>distpath</term>
+				<listitem>
+					<para>Location to store downloaded distfiles. Read 
+					Only</para>
+					
+				</listitem>
+			</varlistentry>
+			
+			<varlistentry id='os_arch'>
+				<term>os_arch</term>
+				<listitem>
+					<para>Identifies hardware type (ie, "Power Macintosh"). 
+					Read Only</para>
+					
+				</listitem>
+			</varlistentry>
+			
+			<varlistentry id='os_version'>
+				<term>os_version</term>
+				<listitem>
+					<para>Version number of operating system (ie "6.0"). 
+					Read Only.</para>
+					
+				</listitem>
+			</varlistentry>
+			
+		</variablelist>
+	</sect1>
+
+	<sect1>
+		<title>Initialization phase</title>
+		<para>The first part of a Portfile deals with initialisation. Most 
+		of the keys (or options) in the initialisation phase  are required 
+		for all Portfiles. </para>
+
+		<variablelist>
+			<varlistentry id='PortSystem'>
+				<term>PortSystem</term>
+				<listitem>
+					<para>Determines which version of the portsystem the 
+					Portfile is compatible with. DarwinPorts supports 
+					versioning of the PortSystem so if new, backwards 
+					incompatible changes are introduced older Portfiles 
+					can continue to use the older version of the system. 
+					The PortSystem line wraps the loading of TCL libraries 
+					appropriate for that version of DarwinPorts. If you 
+					don't load the libraries, nothing else in the Portfile 
+					will work. Thus, the PortSystem should be the top line 
+					in the Portfile.</para>
+					
+					<para>Currently DarwinPorts only has version 1.0 so you 
+					should put: <userinput>PortSystem 1.0</userinput> in your 
+					Portfile.</para>
+
+				</listitem>
+			</varlistentry>
+			<varlistentry id='name'>
+				<term>name</term>
+				<listitem>
+					<para>The name of the Port. By default this is used to 
+					build the url from which the Port is fetched. The name 
+					should be lowercase.</para>
+					
+					<para><userinput>name foo</userinput></para>
+					
+				</listitem>
+			</varlistentry>
+			<varlistentry id='version'>
+				<term>version</term>
+				<listitem>
+					<para>The version of the Port. By default this is used to 
+					build the url from which the Port is fetched. </para>
+					
+					<para><userinput>version 1.23.45</userinput></para>
+					
+				</listitem>
+			</varlistentry>
+			<varlistentry id='platforms'>
+				<term>platforms</term>
+				<listitem>
+					<para>The platforms on which the port has been 
+					tested. </para>
+					<para><userinput>platforms darwin freebsd</userinput></para>
+				</listitem>
+			</varlistentry>
+			<varlistentry id='categories'>
+				<term>categories</term>
+				<listitem>
+					<para>The type of Port. The first category should be the 
+					same as the directory in which the Portfile is stored 
+					and therefore should be chosen with care. A Port may have 
+					more that one category but is not required to.</para>
+					
+					<para><userinput>categories foo bar</userinput></para>
+					
+				</listitem>
+			</varlistentry>
+			<varlistentry id='description'>
+				<term>description</term>
+				<listitem>
+					<para>One sentence describing what the port is, use 
+					long_description for more detail. If you use 
+					long_description you must still use description. </para>
+					
+					<para><userinput>description foo performs the 
+					transformation of bar into xml</userinput> </para>
+					
+				</listitem>
+				
+			</varlistentry>
+			<varlistentry id='long_description'>
+				<term>long_description</term>
+				<listitem>
+					<para>Description of what the port is/does. Long lines 
+					can be broken with escaped newlines. </para>
+					<para><programlisting><userinput>long_description foo 
+					performs the transformation of bar into xml \
+This allows users to rapidly transform documentation into multiple \
+formats. </userinput></programlisting></para>
+				</listitem>
+			</varlistentry>
+			
+			<varlistentry id='maintainers'>
+				<term>maintainers</term>
+				<listitem>
+					<para>List the email address or addresses of the 
+					Portfile maintainer(s)</para>
+					<para><userinput>maintainers 
+					joeblogs@somerandom.domain.com</userinput></para>
+				</listitem>
+			</varlistentry>
+			<varlistentry id='revision'>
+				<term>revision</term>
+				<listitem>
+				
+					<para>Local revision number of portfile.  Increment 
+					for port revisions. The default for this is 0. It 
+					should be incremented for revisions that change the 
+					installed port.</para>
+
+					<para>This key should only be used if the Portfile for the
+					same port version has changed significantly.  It should not be
+					used if the port ${version} has changed.  Most of the time,
+					this key is not needed at all.</para>
+
+					<para><userinput>revision 1.1</userinput></para>
+					
+				</listitem>
+			</varlistentry>
+			<varlistentry id='extract.sufx'>
+				<term>extract.sufx</term>
+				<listitem>
+					<para>By default the value of ${extract.sufx} is .tar.gz. 
+					Specifying extract.sufx is optional, only use it if the 
+					suffix is not 'tar.gz.'. </para>
+					
+					<para><userinput>extract.sufx .tgz</userinput></para>
+					
+				</listitem>
+			</varlistentry>
+			<varlistentry id='distname'>
+				<term>distname</term>
+				<listitem>
+					<para>By default distname is ${name}-${version}. 
+					Specifying distname is optional, only use it if the 
+					file that contains the port is not ${name}-${version} 
+					(without the extract.sufx).</para>
+					
+					<para><userinput>distname ${name}_${version}</userinput></para>
+					
+				</listitem>
+			</varlistentry>
+			
+			<varlistentry id='distfiles'>
+				<term>distfiles</term>
+				<listitem>
+					<para>Defaults to ${distname}.${extract.sufx}. Specifying 
+					distfiles is optional, only use it if the file that 
+					contains the port is not ${distname}.${extract.sufx} 
+					or more than one file needs to be retirieved. </para>
+					
+					<para><userinput>distfiles stable.${extract.sufx} 
+					installer.sh</userinput></para>
+					
+					<para>Some ports require multiple items to be fetched 
+					from different sites, this can be achieved using tags. 
+					The tags are then used to identify which of the 
+					master_sites to fetch the file from.see master_sites 
+					below for more information. As with long_description, 
+					long lines should be broken up with escaped 
+					newlines. </para>
+					<para><userinput>distfiles 
+					stable.${extract.sufx}:source 
+					installer.sh:install</userinput></para>
+				</listitem>
+			</varlistentry>
+			
+			<varlistentry id='use_zip'>
+				<term>use_zip</term>
+				<listitem>
+					<para>Specifying use_zip is optional, only use it if 
+					the file downloades is zipped rather than tarred and 
+					gziped. use_zip set ${extract.sufx} to .zip and 
+					extract.cmd to unzip, extract.pre_args to -q and 
+					extract.post_args to "-d $portpath/$workdir".</para>
+					
+					<para><userinput>use_zip yes</userinput></para>
+					
+				</listitem>
+			</varlistentry>
+			<varlistentry id='use_bzip2'>
+				<term>use_bzip2</term>
+				<listitem>
+					<para>Specifying use_bzip2 is optional, only use it 
+					if the file downloades is bzipped rather than tarred 
+					and gziped. use_bzip2 set ${extract.sufx} to .bzip2 
+					and extract.cmd to bzip2.</para>
+					
+					<para><userinput>use_bzip2 yes</userinput></para>
+					
+				</listitem>
+			</varlistentry>
+			
+		</variablelist>
+	</sect1>
+	<sect1>
+		<title>Fetch phase</title>
+          
+             
+		<variablelist>	
+			<varlistentry id="master_sites">
+				<term>master_sites</term>
+				<listitem>
+					<para> A whitespace delimited list of urls from which the 
+					source of the port can be retrieved. The URL should not 
+					include the name of the file being retrieved.</para>
+					
+					<para>If you have multiple sites you should break up 
+					long lines with escapend newlines. </para>
+		
+                <programlisting><userinput>master_sites   http://www.somesite.org/files/ \
+               http://www.somemirror.org/somesite_org/files/</userinput></programlisting>
+
+					<tip><para>Always put the trailing forward slash at the 
+					end of a url, and remember to not include the filename 
+					itself.</para></tip>
+					
+					<para>If you need to retrieve files from different 
+					sites you can label the urls with tags.</para>
+
+                <programlisting><userinput>master_sites   http://www.somesite.org/files/:source \
+               http://www.someothersite.org/somesite_extras/:extras</userinput></programlisting>
+	      </listitem>
+	    </varlistentry>
+			
+	    <varlistentry id='master_sites_subdir'>
+              <term>master_sites.mirror_subdir</term>
+	      
+              <listitem>
+                <para>Subdirectory to add to mirror sites taken from a
+                  mirror sites list.  Please see the section below on
+                  Mirror Site Lists for more details.</para>
+				</listitem>
+			</varlistentry>
+			
+				<varlistentry id='patchsites'>
+					<term>patch_sites</term>
+	      
+					<listitem>
+						<para>List sites from which to download patchfiles 
+						from, syntax is the same as master_sites. See the 
+						Patch phase below for more information. </para>
+
+                <programlisting><userinput>patch_sites    ftp://ftp.patchcityrepo.com/pub/magic/patches</userinput></programlisting>
+					</listitem>
+				</varlistentry>
+				
+            <varlistentry id='patchsites_subdir'>
+	      <term>patch_sites.mirror_subdir</term>
+	      
+              <listitem>
+                <para>Subdirectory to add to mirror sites taken from a
+                  mirror sites list.  Please see the section below on
+                  Mirror Site Lists for more details.</para>
+	      </listitem>
+	    </varlistentry>
+		</variablelist>
+          
+          <sect2>
+            <title>Mirror Site Lists</title>
+
+            <para>Mirror site lists are, as one might guess, predefined
+              lists of mirror sites for use in
+              <varname>master_sites</varname> or
+              <varname>patch_sites</varname>.  The basic usage of mirror
+              site lists in a <filename>Portfile</filename> is:</para>
+
+            <programlisting><userinput>master_sites                sourceforge http://distfiles.opendarwin.org/
+master_sites.mirror_subdir  ${name}</userinput></programlisting>
+
+            <para>Where '<varname>sourceforge</varname>' is the name of
+              the mirror list which specifies SourceForge mirrors.
+              <varname>master_sites.mirror_subdir</varname> is used to
+              specify the subdirectory of <emphasis>all</emphasis> sites
+              in in any mirror lists in which the file is found.  The
+              above example is equivalent to:</para>
+
+            <programlisting><userinput>master_sites  http://us.dl.sourceforge.net/${name}/ \
+              http://eu.dl.sourceforge.net/${name}/ \
+              ftp://us.dl.sourceforge.net/pub/sourceforge/${name}/ \
+              ...
+              http://distfiles.opendarwin.org/</userinput></programlisting>
+
+            <para>There are two potential problems when using mirror
+              site lists as described above.  First, if you are using
+              multiple mirror site lists, such as
+              <varname>sourceforge</varname> and <varname>gnu</varname>,
+              the subdirectory might not always be the same.  Second, if
+              you have multiple distfiles and are using distfile tags to
+              specify which site in <varname>master_sites</varname> to
+              download which file from.</para>
+            
+            <para>Fortunately DarwinPorts also provides a much more
+              powerful and flexible syntax for mirror site lists.</para>
+
+            <programlisting><userinput>distfiles                   file_one.tar.gz:tagone file_two.tar.gz:tagtwo file_three.tar.gz
+master_sites                sourceforge::tagone gnu:directory:tagtwo \
+                            http://distfiles.opendarwin.org/
+master_sites.mirror_subdir  ${name}</userinput></programlisting>
+
+            <para>At first glance, this example is probably quite
+              confusing.  Basically, the advanced syntax is
+              <varname>list:subdirectory:tag</varname>.  The above
+              example shows the many ways this can be used.  The above
+              example will:</para>
+
+            <itemizedlist>
+              <listitem>
+                <para>Look for <filename>file_one.tar.gz</filename>
+                  in:</para>
+
+                <programlisting>http://us.dl.sourceforge.net/${name}/
+http://eu.dl.sourceforge.net/${name}/
+ftp://us.dl.sourceforge.net/pub/sourceforge/${name}/
+...</programlisting>
+              </listitem>
+
+              <listitem>
+                <para>Look for <filename>file_two.tar.gz</filename>
+                  in:</para>
+
+                <programlisting>ftp://ftp.gnu.org/gnu/directory/${name}/
+ftp://gatekeeper.dec.com/pub/GNU/directory/${name}/
+ftp://ftp.uu.net/archive/systems/gnu/directory/${name}/
+...</programlisting>
+              </listitem>
+
+              <listitem>
+                <para>Look for <filename>file_three.tar.gz</filename>
+                  in:</para>
+
+                <programlisting>http://distfiles.opendarwin.org/</programlisting>
+              </listitem>
+            </itemizedlist>
+
+            <para>There are a few important points to remember when
+              using this syntax.  The subdirectory specified with the
+              list
+              (<varname>gnu:<emphasis>directory</emphasis></varname>) is
+              appended to all of the mirror sites in that list
+              <emphasis>before</emphasis> the
+              <varname>master_sites.mirror_subdir</varname>, and
+              <varname>master_sites.mirror_subdir</varname> is
+              <emphasis>always</emphasis> appended to the end of the
+              mirror site.  When using tags, you are not required to
+              specify a subdirectory
+              (<varname>sourceforge::tagone</varname>).
+              <varname>master_sites.mirror_subdir</varname> is also not
+              required when specifying a subdirectory with the
+              list.</para>
+
+            <para>The original example could also be have been written
+              using this syntax without the need of
+              <varname>master_sites.mirror_subdir</varname> like
+              this:</para>
+
+            <programlisting><userinput>master_sites   sourceforge:${name} http://distfiles.opendarwin.org/</userinput></programlisting>
+
+            <para>The mirror site lists functionality also works exactly
+              the same for <varname>patch_sites</varname> and
+              <varname>patch_sites.mirror_subdir</varname>.</para>
+
+            <para>Below is a list of the mirror site lists that can be
+              used.</para>
+
+            <itemizedlist>
+              <listitem><para><varname>apache</varname></para></listitem>
+              <listitem><para><varname>gnome</varname></para></listitem>
+              <listitem><para><varname>gnu</varname></para></listitem>
+              <listitem><para><varname>isc</varname></para></listitem>
+              <listitem><para><varname>kde</varname></para></listitem>
+              <listitem><para><varname>perl_cpan</varname></para></listitem>
+              <listitem><para><varname>ruby</varname></para></listitem>
+              <listitem><para><varname>sourceforge</varname></para></listitem>
+              <listitem><para><varname>sunsite</varname></para></listitem>
+              <listitem><para><varname>tcltk</varname></para></listitem>
+              <listitem><para><varname>xcontrib</varname></para></listitem>
+              <listitem><para><varname>xfree</varname></para></listitem>
+            </itemizedlist>
+          </sect2>
+	</sect1>
+
+	<sect1>
+		<title>Integrity checking phase</title>
+		<para>Each file downloaded is integrity checked using a checksum. 
+		This is used to help prevent trojaned sources being downloaded. 
+		If you do not include the checksums line, the file will be 
+		downloaded and the checksum reported as a conenience to the Portfile 
+		author.</para>
+		
+		<variablelist>
+			<varlistentry id='checksums'>
+					<term>checksums</term>
+					<listitem>
+						<para>Currently only the md5 checksum is supported. 
+						Specify the filename, the checksum type and the 
+						checksum.</para>
+						
+						<para><programlisting><userinput>
+						${distname}-${extract.sufx} md5 65b89365a65dcad71d4402b48 \
+						foo.tar.gz md5 65b89365a65dcad71d4402b44</userinput>
+							</programlisting></para>
+
+						<tip><para>If you only have one file being fetched the 
+						filename can be omitted. </para>
+						
+						<para><userinput>md5 65b89365a65dcad71d4402b48</userinput>
+						</para></tip>
+					</listitem>
+				</varlistentry>
+			</variablelist>
+	</sect1>
+	<sect1>
+		<title>Extract phase</title>
+		<para></para>
+		<variablelist>
+			<varlistentry id='extract.only'>
+					<term>extract.only</term>
+					<listitem>
+						<para>List of files to extract into ${workpath}, 
+						defaults to ${distfiles}. Useful when some files 
+						are not compressed. Only use extract.only if the 
+						default does not do the right thing.</para>
+						
+						<para>
+						<userinput>extract.only foo.tar.gz bar.tar.gz</userinput>
+						</para>
+
+					</listitem>
+				</varlistentry>
+				
+				<varlistentry id='extract.cmd'>
+					<term>extract.cmd</term>
+					<listitem>
+						<para>Command to perform extraction. Defaults to gzip. </para>
+						<para><userinput>extract.cmd gunzip</userinput></para>
+
+					</listitem>
+				</varlistentry>
+				
+				<varlistentry id='extract.pre_args'>
+					<term>extract.pre_args</term>
+					<listitem>
+						<para>Arguments added to extract command before a 
+						file name. Defaults to -dc. </para>
+						<para><userinput>extract.pre_args    -cd</userinput>
+						</para>
+
+					</listitem>
+				</varlistentry>
+				
+				<varlistentry id='extract.args'>
+					<term>extract.args</term>
+					<listitem>
+						<para>Arguments to extract.cmd, Read Only. The value 
+						is ${distpath}/${distfile}</para>
+
+					</listitem>
+				</varlistentry>
+				
+				<varlistentry id='extract.post_args'>
+					<term>extract.post_args></term>
+					<listitem>
+						<para>Arguments added to extract command after a file 
+						name. Defaults to "| tar -xf". </para>
+						<para><userinput>extract.post_args   | tar -xf
+						</userinput></para>
+
+					</listitem>
+				</varlistentry>
+				
+			</variablelist>
+	</sect1>
+	<sect1>
+		<title>Patch phase</title>
+		<para></para>
+			<variablelist>
+				<varlistentry id='patchfiles'>
+					<term>patchfiles</term>
+					<listitem>
+						<para>List of patch files to apply to source. Patch 
+						files can be supplied in a port in a directory named 
+						files (based on the value of ${filepath}) within the 
+						port directory or fetched from ${patchsites}. Each 
+						patchfile supplied by the Portfile author should 
+						patch a single file. The standard convention is to 
+						name the patch file 'patch-&lt;filename&gt;.diff, 
+						with one diff file per file altered in the source. 
+						If the filename is ambiguous because there are 
+						multiple files with that name in the distribution, 
+						supply the path components to uniquely identify the 
+						file being patched. Diffs should be created with 
+						<userinput>diff -u file1 
+						file2 >../../files/patch-file.diff</userinput>. 
+						Patches downloaded from patchsites must have 
+						checksumes.</para>
+						<para><userinput>patchfiles patch-Makefile.in 
+						patch-source.c</userinput></para>
+
+					</listitem>
+				</varlistentry>
+				
+			</variablelist>
+	</sect1>
+	<sect1 id='configure'>
+		<title>Configuration phase</title>
+		<para></para>
+			
+			<sect2>
+				<title> Automake and autoconf</title>						
+					<variablelist>
+						<varlistentry id='use_automake'>
+							<term>use_automake</term>
+							<listitem>
+								<para>If set to yes, use automake</para>
+								<para><userinput>use_automake yes
+								</userinput></para>
+
+							</listitem>
+						</varlistentry>
+						
+						<varlistentry id='automake.env'>
+							<term>automake.env</term>
+							<listitem>
+								<para>Environmental variables to pass 
+								to automake</para>
+								<para><userinput>CFLAGS="-I'${prefix}/include'"
+								</userinput></para>
+
+							</listitem>
+						</varlistentry>
+						
+						<varlistentry id='automake.args'>
+							<term>automake.args</term>
+							<listitem>
+								<para>Arguments to pass to automake. </para>
+								<para><userinput>automake.args  --foreign
+								</userinput></para>
+
+							</listitem>
+						</varlistentry>
+						
+						<varlistentry id='automake.dir'>
+							<term>automake.dir</term>
+							<listitem>
+								<para>Directory in which to run ${automake.cmd}. 
+								Defaults to ${worksrcpath}</para>
+								<para><userinput>automake.dir</userinput></para>
+
+							</listitem>
+						</varlistentry>
+						
+						<varlistentry id='use_autoconf'>
+							<term>use_autoconf</term>
+							<listitem>
+								<para>If set to yes, run autoconf. </para>
+								<para><userinput>use_autoconf   yes
+								</userinput></para>
+
+							</listitem>
+						</varlistentry>
+						
+						<varlistentry id='autoconf.env'>
+							<term>autoconf.env</term>
+							<listitem>
+								<para>Environmental variables to pass to 
+								autoconf</para>
+								<para><userinput>autoconf.env   
+								CFLAGS=-I'${prefix}/include/gtk12'</userinput>
+								</para>
+
+							</listitem>
+						</varlistentry>
+						
+						<varlistentry id='autoconf.args'>
+							<term>autoconf.args</term>
+							<listitem>
+								<para>Arguments to pass to autoconf. </para>
+								<para><userinput>autoconf.args  -l 
+								src/aclocaldir</userinput></para>
+
+							</listitem>
+						</varlistentry>
+						
+						<varlistentry id='autoconf.dir'>
+							<term>autoconf.dir</term>
+							<listitem>
+								<para>Directory in which to run 
+								${autoconf.cmd}. </para>
+								<para><userinput>autoconf.dir   
+								src</userinput></para>
+
+							</listitem>
+						</varlistentry>
+						
+					</variablelist>
+				</sect2>
+				<sect2>
+					<title>configure</title>
+					<variablelist>
+						<varlistentry id='configure.env'>
+							<term>configure.env</term>
+							<listitem>
+								<para>Set environment variables for 
+								configure.</para>
+								<para><userinput>configure.env 
+								CFLAGS="-I'${prefix}/include'"</userinput>
+								</para>
+
+							</listitem>
+						</varlistentry>
+						
+						<varlistentry id='configure.pre_args'>
+							<term>configure.pre_args</term>
+							<listitem>
+								<para>Arguments added to configure command 
+								before ${configure.args}. Defaults to 
+								--prefix=${prefix}. </para>
+								<para><userinput>configure.pre_args       
+								--prefix="${prefix}/apache2"</userinput></para>
+
+							</listitem>
+						</varlistentry>
+						
+						<varlistentry id='configure.args'>
+							<term>configure.args</term>
+							<listitem>
+								<para>Arguments to pass to configure.</para>
+								<para><userinput>configure.args      
+								--etcdir="${prefix}/etc"</userinput></para>
+
+							</listitem>
+						</varlistentry>
+					</variablelist>
+				</sect2>
+				
+	</sect1>
+	<sect1>
+		<title>Build phase</title>
+		<para></para>
+		
+		<variablelist>
+			
+			<varlistentry id='build.cmd'>
+				<term>build.cmd</term>
+				<listitem>
+					<para>Make command to run relative to ${worksrcdir}. 
+					Defaults to make.</para>
+					<para><userinput>build.cmd pbxbuild</userinput></para>
+
+				</listitem>
+			</varlistentry>
+			
+			<varlistentry id='build.type'>
+				<term>build.type</term>
+				<listitem>
+					<para>Defines which 'make' is required, either 'gnu' 
+					or 'bsd' Sets build.cmd to either
+						'gnumake' or 'bsdmake' accordingly</para>
+						
+					<para><userinput>build.type     gnu</userinput></para>
+
+				</listitem>
+			</varlistentry>
+			
+			<varlistentry id='build.pre_args'>
+				<term>build.pre_args</term>
+				<listitem>
+					<para>Arguments to pass to ${build.cmd} before 
+					${build.args}. Read only. Set to 
+					${build.target.current}</para>
+
+				</listitem>
+			</varlistentry>
+			
+			<varlistentry id='build.args'>
+				<term>build.args</term>
+				<listitem>
+					<para>Arguments to pass to ${build.cmd}</para>
+					<para><userinput>build.args     
+					-DNOWARN</userinput></para>
+
+				</listitem>
+			</varlistentry>
+			
+			<varlistentry id='build.target'>
+				<term>build.target</term>
+				<listitem>
+					<para>Target to pass to make for building everything. 
+					Defaults to all.</para>
+					<para><userinput>build.target.all all-src</userinput>
+					</para>
+
+				</listitem>
+			</varlistentry>
+
+		</variablelist>
+	</sect1>
+
+	<sect1>
+          <title>Destroot phase</title>
+		
+          <variablelist>
+
+            <varlistentry id='destroot.cmd'>
+              <term>destroot.cmd</term>
+              <listitem>
+                <para>Install command to run relative to ${worksrcdir}. 
+                  Defaults to ${build.cmd}.</para>
+                <para><userinput>destroot.cmd pbxbuild</userinput></para>
+              </listitem>
+            </varlistentry>
+			
+            <varlistentry id='destroot.type'>
+              <term>destroot.type</term>
+              <listitem>
+                <para>Defines which 'make' is required, either 'gnu' or 
+                  'bsd' Sets install.cmd to either
+                  'gnumake' or 'bsdmake' accordingly</para>
+                <para><userinput>destroot.type     gnu</userinput></para>
+              </listitem>
+            </varlistentry>
+			
+            <varlistentry id='destroot.pre_args'>
+              <term>destroot.pre_args</term>
+              <listitem>
+                <para>Arguments to pass to ${destroot.cmd} before 
+                  ${destroot.args}. Read only. Set to  ${destroot.target}</para>
+              </listitem>
+            </varlistentry>
+			
+            <varlistentry id='destroot.args'>
+              <term>destroot.args</term>
+              <listitem>
+                <para>Arguments to pass to ${destroot.cmd}</para>
+                <para><userinput>destroot.args     -DNOWARN</userinput></para>
+              </listitem>
+            </varlistentry>
+		
+            <varlistentry id='destroot.target'>
+              <term>destroot.target</term>
+              <listitem>
+                <para>Install target to pass to ${destroot.cmd}.</para>
+                <para><userinput>destroot.target install-src</userinput></para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry id='destroot.destroot'>
+              <term>destroot.destroot</term>
+              <listitem>
+                <para>Arguments passed to ${destroot.cmd} in order to 
+                  install correctly into the destroot.</para>
+                <para>All ports must install via the 'destroot' so 
+                  that the DarwinPorts infrastructure can register each 
+                  file and directory a port installs. Most autoconf based 
+                  build systems will behave correctly and respect DESTDIR, 
+                  however some will not. Most of those that do not respect 
+                  DESTDIR will install correctly if you use 'prefix', as 
+                  in the example below. If your port doesn't respect either 
+                  of these, you'll have to figure out what to do yourself. 
+                  Some ports use another term, others require you to patch 
+                  the Makefile (or other build related script). </para>
+                <para><userinput>destroot.destroot prefix=${destroot}${prefix}
+                    </userinput></para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+        </sect1>
+
+        <sect1>
+          <title>Test phase</title>
+
+          <variablelist>
+
+            <varlistentry id="test.run">
+              <term>test.run</term>
+
+              <listitem>
+                <para>Enable running test suites bundled with a
+                port</para>
+                
+                <para><userinput>test.run yes</userinput></para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry id="test.cmd">
+              <term>test.cmd</term>
+
+              <listitem>
+                <para>Test command to run relative to
+                ${worksrcdir}</para>
+
+                <para><userinput>test.cmd checks.sh</userinput></para>
+              </listitem>
+            </varlistentry>
+            
+            <varlistentry id="test.target">
+              <term>test.target</term>
+
+              <listitem>
+                <para>Test target to pass to ${test.cmd}</para>
+
+                <para><userinput>test.target
+                checks</userinput></para>
+              </listitem>
+            </varlistentry>
+              
+            <varlistentry id="test.dir">
+              <term>test.dir</term>
+
+              <listitem>
+                <para>Directory in which to run ${test.cmd}</para>
+
+                <para><userinput>test.dir
+                ${worksrcpath}/checks</userinput></para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+        </sect1>
+
+        <sect1>
+          <title>Install phase</title>
+
+          <para>These keys have all been deprecated.  You should use the
+            destroot keys in their place.</para>
+        </sect1>
+
+	<sect1>
+    	<title>Dependencies</title>
+    	<para></para>    		
+    	<sect2>
+			<title>Principles</title>
+			<para></para>
+		</sect2>
+		<sect2>
+			<title>Dependency tests</title>
+			<para></para>
+			<variablelist>
+				<varlistentry>
+						<term> depends_fetch </term>
+						<listitem>
+						<para></para>
+						</listitem>
+				</varlistentry>
+				<varlistentry>
+						<term> depends_extract </term>
+						<listitem>
+						<para></para>
+						</listitem>
+				</varlistentry>
+				<varlistentry>
+						<term> depends_lib </term>
+						<listitem>
+						<para></para>
+						</listitem>
+				</varlistentry>
+				<varlistentry>
+						<term> depends_build </term>
+						<listitem>
+						<para></para>
+						</listitem>
+				</varlistentry>
+				<varlistentry>
+						<term> depends_run </term>
+						<listitem>
+							<para></para>
+						</listitem>
+				</varlistentry>	
+            </variablelist>
+        </sect2>
+    </sect1>
+
+	<sect1>
+          <title>TCL primitives</title>
+          <para>DarwinPorts provides several useful TCL primitives for
+            use within Portfiles.</para>
+
+          <sect2>
+            <title>adduser</title>
+
+            <para>Add a user to the system.</para>
+            
+            <para>Usage: <userinput>adduser name</userinput></para>
+            
+            <para>Where <userinput>name</userinput> is the username
+              to add.  You can also override the defaults for any of the
+              following user settings:</para>
+
+            <para><userinput>adduser name password={\*} uid=[nextuid] 
+              gid=[nextgid] realname=${name} home=/dev/null
+              shell=/dev/null</userinput></para>
+          </sect2>
+
+          <sect2>
+            <title>addgroup</title>
+            
+            <para>Add a group to the system.</para>
+
+            <para>Usage: <userinput>addgroup name</userinput></para>
+
+            <para>Where <userinput>name</userinput> is the name of the
+            group to add.  You can also override the defaults for any of
+            the following group settings:</para>
+
+            <para><userinput>addgroup name gid=[nextgid]
+            users=""</userinput></para>
+          </sect2>
+
+          <sect2>
+            <title>file</title>
+
+            <para>Manipulate file names and attributes.</para>
+
+            <para>Usage: <userinput>file option name ?arg arg
+            ...?</userinput></para>
+
+            <para>Please see the Tcl documentation at <ulink
+                url="http://www.tcl.tk/man/tcl8.3/TclCmd/file.htm">The
+                Tcl/Tk Developer's Site.</ulink> for more on the options
+                and arguments for file.</para>
+          </sect2>
+
+          <sect2>
+            <title>reinplace</title>
+            <para>Provides "sed in place" functionality.</para>
+            <para>Usage: <userinput>reinplace   sed_patern
+            file</userinput></para>
+            <para>Where <userinput>sed_patern</userinput> is a sed
+            patern, and <userinput>file</userinput> is the name of the
+            file to run sed on.</para>
+          </sect2>
+          <sect2>
+            <title>system</title>
+            <para>Execute a system command.</para>
+            <para>Usage: <userinput>system  "command"</userinput></para>
+          </sect2>		
+	</sect1>
+        
+	<sect1>
+		<title>Other</title>
+		<para></para>
+		<sect2>
+			<title>Pre and post phase steps</title>
+			<variablelist>
+				<varlistentry>
+					<term>Pre-*</term>
+					<listitem>
+						<para></para>
+					</listitem>
+				</varlistentry>
+				
+				<varlistentry>
+					<term>Post-*</term>
+					<listitem>
+						<para></para>
+
+					</listitem>
+				</varlistentry>
+			</variablelist>
+		</sect2>
+		<sect2>
+			<title>Overriding a phase</title>
+			<para></para>
+
+		</sect2>
+			
+    </sect1>
+ </chapter>
+    	
+
+		
+		
Index: trunk/doc/guide/xml/portfiles/hier.xml
===================================================================
--- trunk/doc/guide/xml/portfiles/hier.xml	(revision 4478)
+++ trunk/doc/guide/xml/portfiles/hier.xml	(revision 4478)
@@ -0,0 +1,209 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id="heir">
+	<title>Ports Filesystem Layout</title>
+
+	<sect1>
+		<title>Overview</title>
+			
+		<para>Portfile authors are expected to make sure that a port, when
+		installed conforms to specific filesystem hierarchy guidelines.
+		These guidelines define where certain files should be installed in
+		the DarwinPorts filesystem.</para>
+	</sect1>
+	
+	<sect1>
+		<title>DarwinPorts Base, ${prefix}</title>
+
+		<variablelist>
+			<varlistentry>
+				<term><filename>/<variable>${prefix}</variable></filename></term>
+
+				<listitem>
+					<para>The base of the DarwinPorts filesystem
+					hierarchy.</para>
+
+					<para>Default: <filename>/opt/local</filename></para>
+
+					<variablelist>
+						<varlistentry>
+							<term><filename>bin/</filename></term>
+
+							<listitem>
+								<para>Common utilities, programming tools, and
+								applications.</para>
+							</listitem>
+						</varlistentry>
+
+						<varlistentry>
+							<term><filename>etc/</filename></term>
+
+							<listitem>
+								<para>System configuration files and scripts.</para>
+							</listitem>
+						</varlistentry>
+
+						<varlistentry>
+							<term><filename>games/</filename></term>
+
+							<listitem>
+								<para>Useful and semi-frivolous programs.</para>
+							</listitem>
+						</varlistentry>
+
+						<varlistentry>
+							<term><filename>include/</filename></term>
+
+							<listitem>
+								<para>Standard C include files.</para>
+							</listitem>
+						</varlistentry>
+
+						<varlistentry>
+							<term><filename>java/</filename></term>
+
+							<listitem>
+								<para>Applications based on Java.</para>
+							</listitem>
+						</varlistentry>
+
+						<varlistentry>
+							<term><filename>libexec/</filename></term>
+
+							<listitem>
+								<para>System daemons and system utilities (executed by
+								other programs).</para>
+							</listitem>
+						</varlistentry>
+
+						<varlistentry>
+							<term><filename>sbin/</filename></term>
+
+							<listitem>
+								<para>System programs and administration
+								utilities.</para>
+							</listitem>
+						</varlistentry>
+
+						<varlistentry>
+							<term><filename>share/</filename></term>
+
+							<listitem>
+								<para>Architecture-independent files.</para>
+							
+								<variablelist>
+									<varlistentry>
+										<term><filename>doc/</filename></term>
+
+										<listitem><para>Miscellaneous
+										documentation</para></listitem>
+									</varlistentry>
+
+									<varlistentry>
+										<term><filename>examples/</filename></term>
+
+										<listitem><para>Various examples for users and
+										programmers.</para></listitem>
+									</varlistentry>
+
+									<varlistentry>
+										<term><filename>info/</filename></term>
+
+										<listitem><para>GNU Info hypertext
+											system</para></listitem>
+									</varlistentry>
+
+									<varlistentry>
+										<term><filename>locale/</filename></term>
+
+										<listitem><para>Localization
+										files.</para></listitem>
+									</varlistentry>
+
+									<varlistentry>
+										<term><filename>man/</filename></term>
+
+										<listitem><para>Manual pages.</para></listitem>
+									</varlistentry>
+
+									<varlistentry>
+										<term><filename>misc/</filename></term>
+
+										<listitem><para>Misc. system-wide ASCII text
+										files.</para></listitem>
+									</varlistentry>
+								</variablelist>
+							</listitem>
+						</varlistentry>
+
+						<varlistentry>
+							<term><filename>var/</filename></term>
+
+							<listitem>
+								<para>Multi-purpose log, temporary, transient and
+								spool files.</para>
+								
+								<variablelist>
+
+									<varlistentry>
+										<term><filename>db/</filename></term>
+
+										<listitem>
+											<para>Misc. automatically generated
+											system-specific database files.</para>
+											<variablelist>
+												<varlistentry>
+													<term><filename>dports/</filename></term>
+
+													<listitem><para>DarwinPorts runtime
+													data.</para></listitem>
+												</varlistentry>
+											</variablelist>
+										</listitem>
+									</varlistentry>
+
+									<varlistentry>
+										<term><filename>spool/</filename></term>
+
+										<listitem>
+											<para>Directory containing output spool
+											files.</para>
+										</listitem>
+									</varlistentry>
+
+									<varlistentry>
+										<term><filename>log/</filename></term>
+
+										<listitem><para>Misc. system log
+										files.</para></listitem>
+									</varlistentry>
+
+									<varlistentry>
+										<term><filename>run/</filename></term>
+
+										<listitem><para>System information files
+										describing various info about system since it was
+										booted.</para></listitem>
+									</varlistentry>
+								</variablelist>
+							</listitem>
+						</varlistentry>
+				
+					</variablelist>
+
+				</listitem>
+			</varlistentry>
+
+			<varlistentry>
+				<term><filename>/Applications/DarwinPorts/</filename></term>
+
+				<listitem>
+					<para>Native Mac OS X applications.</para>
+				</listitem>
+			</varlistentry>
+		</variablelist>
+
+	</sect1>
+</chapter>
Index: trunk/doc/guide/xml/portfiles/quick.xml
===================================================================
--- trunk/doc/guide/xml/portfiles/quick.xml	(revision 4478)
+++ trunk/doc/guide/xml/portfiles/quick.xml	(revision 4478)
@@ -0,0 +1,683 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<chapter id="quickstart">
+  <chapterinfo>
+    <keywordset>
+      <keyword>
+	portfile
+      </keyword>
+    
+      <keyword>
+        introduction
+      </keyword>
+      
+      <keyword>
+        maintainer
+      </keyword>
+    </keywordset>
+  </chapterinfo>
+  
+  <title>Quick Start</title> 
+
+  <sect1 id="getting_started">
+    <title>Getting Stated With DarwinPorts</title>
+
+    <para>This document will provide a short guide to the basics of a
+      DarwinPorts <filename>Portfile</filename>.  A
+      <filename>Portfile</filename> is actually a Tcl script run by the
+      <command>port</command> system.  Despite this, the
+      <filename>Portfile</filename> syntax is very
+      straightforward.</para>
+    
+    <para>In order to work with DarwinPorts, you will need to download and
+      install it on your system.  The <link linkend='getting_dports'> 
+      Obtaining</link> and <link linkend='install_dports'>Installing  
+      DarwinPorts</link> sections of this guide describes the process in
+      detail. </para>
+
+    <para>Since you're interested in writing a
+      <filename>Portfile</filename>, you should invoke the
+      <command>port</command> with the <option>-v</option> (verbose
+      output) and the <option>-d</option> (debugging option) switches.
+      This will display useful messages that are usually suppressed
+      while running DarwinPorts.</para>
+  </sect1>
+
+  <sect1 id="basics">
+    <title>Basic Topics and Examples</title>
+
+    <sect2 id="fetching_sources">
+      <title>Fetching the Sources</title>
+
+      <para>The first step is to choose a piece of software to port.  
+      For this example, we'll be porting ircII, a popular Internet relay 
+      chat client.</para>
+
+      <para>We can start with a simple <filename>Portfile</filename>
+        describing the basic attributes of ircII, such as its name,
+        version, and the site where we can download the sources.  </para>
+        <para>Create a working directory named <filename>ircII</filename> 
+        and inside it create a file named <filename>Portfile</filename> 
+        with the following contents:</para>
+
+      <example id="ircii">
+        <title>ircII <filename>Portfile</filename></title> 
+          
+        <programlisting># &#x0024;Id: &#x0024;
+PortSystem        1.0
+name              ircii
+version           20020912
+categories        irc
+maintainers       kevin@opendarwin.org
+description       an IRC and ICB client
+long_description  The ircII program is a full screen, termcap based \
+                  interface to Internet Relay Chat. It gives full access \
+                  to all of the normal IRC functions, plus a variety of \
+                  additional options.
+homepage          http://www.eterna.com.au/ircii/
+master_sites      ftp://ircftp.au.eterna.com.au/pub/ircII/</programlisting>
+      </example>
+
+      <para>A <filename>Portfile</filename> consists of key/value pairs.
+        This example uses the following keys:</para>
+ 
+      <variablelist>
+        <varlistentry>
+          <term><varname># &#x0024;Id: &#x0024;</varname></term>
+          
+          <listitem>
+            <para>Every <filename>Portfile</filename> starts with
+              <varname>#&#x0024;Id: &#x0024;</varname>. This is a RCS
+              <varname>Id</varname> tag (commented out with the '#' character
+              so that DarwinPorts is not confused by the tag). </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>PortSystem</varname></term>
+
+          <listitem>
+            <para>Following the RCS <varname>Id</varname> tag comes the
+              <varname>PortSystem</varname> version declaration.  Currently the
+              only valid version declaration is <varname>PortSystem
+                1.0</varname>.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>name</varname> and
+            <varname>version</varname></term>
+
+          <listitem>
+            <para>The <varname>name</varname> and
+              <varname>version</varname> keys describe the name and
+              version of the software.</para>
+          </listitem>
+        </varlistentry>
+        
+        <varlistentry>
+          <term><varname>categories</varname></term>
+          
+          <listitem>
+            <para>The <varname>categories</varname> key is a list of the
+              logical categories to which the software belongs; this is
+              used for organizational purposes.  The first entry in
+              <varname>categories</varname> should match the directory
+              in which the port's directory resides in the ports
+              tree.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>maintainers</varname></term>
+
+          <listitem>
+            <para>The <varname>maintainers</varname> key should contain
+              the email address of the person or persons maintaining the port.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>description</varname> and
+            <varname>long_description</varname></term>
+
+          <listitem>
+            <para><varname>description</varname> provides a short (one line)
+              description of the port, while
+              <varname>long_description</varname> holds a more detailed
+              description of the software.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>homepage</varname></term>
+
+          <listitem>
+            <para>To refer to the main web site of the software, the
+              <varname>homepage</varname> key is used.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>master_sites</varname></term>
+          
+          <listitem>
+            <para>The <varname>master_sites</varname> key should contain
+              a list of sites where the distribution sources may be
+              downloaded by the port system. </para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+      
+      <para>DarwinPorts uses the terms 'keys' and 'options'
+        interchangeably since most keys are used as options of a
+        particular task in the porting process.</para>
+      
+      <para>At this point, the <filename>Portfile</filename> is complete
+        enough to download ircII.  By default, DarwinPorts will append
+        the <varname>version</varname> to <varname>name</varname> and
+        assume sources are in a gzipped tar archive with the 
+        <filename>.tar.gz</filename> suffix. </para>
+        <para>From your working directory, execute the following command:</para>
+      
+      <para><userinput>port -d -v checksum</userinput></para>
+
+      <para>The <command>port</command> command (when used without an explicit
+      port name operates on the <filename>Portfile</filename> in the current 
+      working directory. You should see the following output:</para>
+
+      <para><computeroutput><literallayout>DEBUG: Executing com.apple.main (ircii)
+DEBUG: Executing com.apple.fetch (ircii)
+--->  ircii-20020912.tar.gz doesn't seem to exist in /opt/local/var/db/dports/distfiles
+--->  Attempting to fetch ircii-20020912.tar.gz from ftp://ircftp.au.eterna.com.au/pub/ircII/
+DEBUG: Executing com.apple.checksum (ircii)
+Error: No checksums statement in Portfile.  File checksums are:
+ircii-20020912.tar.gz md5 2ae68c015698f58763a113e9bc6852cc
+Error: Target error: com.apple.checksum returned: No checksums statement in Portfile.
+</literallayout></computeroutput></para>
+    </sect2>
+
+    <sect2 id="checksums">
+      <title>Verifying the Downloaded File</title>
+
+      <para>Notice that DarwinPorts first checks for a local copy of
+        <filename>ircii-20020912.tar.gz</filename> and doesn't find it,
+        so it then downloads from the remove site.  The port doesn't
+        finish because of an error: <computeroutput>No checksums
+          statement in Portfile.</computeroutput>
+        Portfiles must contain an md5 checksum of all distribution
+        files--this allows DarwinPorts to verify the accuracy and
+        authenticity of the sources.  For convenience, an md5 checksum
+        of the downloaded files is printed when the
+        <varname>checksums</varname> argument is not specified.  Go back
+        and add the following to your
+        <filename>Portfile</filename>:</para>
+
+      <programlisting>checksums    md5 2ae68c015698f58763a113e9bc6852cc</programlisting>
+
+      <para>If you have more than one file being fetched you should
+        specify the checksum for each in the form:</para>
+
+      <programlisting>checksums    foo md5 ... \
+             bar md5 ...</programlisting>
+      
+    </sect2>
+
+    <sect2 id="extract">
+      <title>Extracting the Sources into a Working Directory</title>
+
+      <para>Now that we have a checksum and can verify our sources, we
+        can proceed to extracting the sources into our working
+        directory.  Execute the following:</para>
+
+      <para><userinput>port -d -v extract</userinput></para>
+
+      <para>Which should display the following output:</para>
+
+      <para><computeroutput><literallayout>DEBUG: Skipping completed com.apple.main (ircii)
+DEBUG: Skipping completed com.apple.fetch (ircii)
+DEBUG: Executing com.apple.checksum (ircii)
+--->  Checksum OK for ircii-20020912.tar.gz
+DEBUG: Executing com.apple.extract (ircii)
+--->  Extracting for ircii-20020912
+--->  Extracting ircii-20020912.tar.gz ... DEBUG: Assembled command: 'cd
+/Users/kevin/opendarwin/proj/darwinports/dports/irc/ircii/work &amp;&amp; gzip -dc /opt/local/var/db/dports/distfiles/ircii-20020912.tar.gz | tar -xf -'
+Done</literallayout></computeroutput></para>
+    </sect2>
+
+    <sect2 id="running_configure">
+      <title>Running a <filename>configure</filename> Script</title>
+
+      <para>Now that the sources have been extracted into a
+        <filename>work</filename> directory in the Portfile
+        directory, we can configure the sources to compile with the
+        desired options.  By default DarwinPorts assumes the software
+        you're porting uses an autoconf <filename>configure</filename>
+        script and  will pass the <option>--prefix=${prefix}</option> 
+        argument to <filename>configure</filename>, specifying that the 
+        software should be installed in the directory tree used by
+        DarwinPorts.</para>
+
+      <para>ircII's standard set of options is fine for a base
+        install on Darwin, so we won't add anything to the
+        <varname>configure</varname> phase and instead just
+        move on to the build phase.  Please look at the
+        later chapters in this Guide for more information about
+        the <link linkend='configure'>Configuration</link> phase.</para>
+    </sect2>
+
+    <sect2 id="building_sources">
+      <title>Building the Sources</title>
+
+      <para>To build, type the following:</para>
+      
+      <para><userinput>port build -v -d</userinput></para>
+
+      <para>By default, the build phase executes the system's
+        <command>make</command>(1) utility.  (This can be changed with
+        the <varname>build.type</varname> option which accepts an
+        argument of <varname>bsd</varname>, <varname>gnu</varname>, or
+        <varname>pbx</varname>.  Alternatively, the
+        <varname>build.cmd</varname> option may be used to specify an
+        arbitrary build command.)  The above step has started
+        compiling the sources, when it finishes we'll be ready to
+        install the software.</para>
+    </sect2>
+
+    <sect2 id="installing">
+      <title>Installing the Finished Product on the System</title>
+
+      <para>The former method of including a
+        <varname>contents</varname> list has been made obsolete by the
+        <varname>destroot</varname> mechanism.  With
+        <varname>destroot</varname> the software is installed into a
+        directory tree below in the <filename>work</filename>
+        directory.  While some software (like ircII) does not require
+        any special tweaks to be installed into the destroot, others
+        (like ncftp) need the <varname>install.destroot</varname>
+        option in order to correctly install into the
+        <varname>destroot</varname>.</para>
+
+      <programlisting>install.destroot     mandir=${destroot}${prefix}/man prefix=${destroot}${prefix}</programlisting>
+
+      <para>Take a look at some of our ports to see more examples on
+        how to use the <varname>install.destroot</varname>
+        option.</para>
+
+      <para>Now we have a complete <filename>Portfile</filename>.
+        Run the installation step to add your port to your own
+        registry. </para>
+      
+      <para><userinput>sudo port -d -v install</userinput></para>
+
+      <para>Which should finish with the output:</para>
+
+      <para><computeroutput><literallayout>
+--->  Adding ircii to registry, this may take a moment...</literallayout></computeroutput></para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="advanced">
+    <title>Advanced Topics</title>
+
+    <sect2 id="overriding_targets">
+      <title>Overriding Targets</title>
+
+      <para>It's possible to override the functionality of any build
+        target with Tcl code.  A common example is the following which
+        might be useful for a script without a configure script. 
+        <filename>configure</filename> script:</para>
+
+      <programlisting>configure    {}</programlisting>
+
+      <para>In the <filename>Portfile</filename>, this will replace
+        the functionality of the <varname>configure</varname> target,
+        thus skipping that step.  It is also possible to execute Tcl
+        code immediately before or after any of the standard targets.
+        This can be accomplished using pre--&lt;target&gt; or 
+        post-&lt;target&gt; in the following manner:</para>
+
+      <programlisting>post-configure {
+    reinplace "s|change.this.to.a.server|irc.openprojects.net|g" \
+              "${workdir}/${worksrcdir}/config.h"
+}</programlisting>
+
+      <para>This example replaces the occurrence of
+        <varname>change.this.to.a.server</varname> with
+        <varname>irc.freenode.net</varname> in the
+        <filename>config.h</filename> file that was generated during
+        the preceding <varname>configure</varname> phase.  Note this
+        is a somewhat contrived example, since the same could have
+        been accomplished by specifying
+        <varname>--with-default-server=irc.freenode.net</varname>
+        in <varname>configure.args</varname>, but the approach is
+        generally useful when such configure arguments aren't
+        present.</para>
+    </sect2>
+
+    <sect2 id="variants">
+      <title>Portfile Variants</title>
+
+      <para>Since Darwin 6.0 has ipv6, it would be possible to
+        configure with the <varname>--with-ipv6</varname> option.
+        This can be done by adding the following option to the
+        <filename>Portfile</filename>:</para>
+
+      <programlisting>configure.args      --disable-ipv6
+
+variant ipv6 {
+    configure.args-append  --enable-ipv6
+}</programlisting>
+
+      <para>Now the default build will not include ipv6 support, but
+        if the ipv6 variant is requested, ircII will have it.  Options
+        by themselves should be thought of as an assignment operator.
+        Since variants may be used in combination with one another,
+        it's good practice to only append to options instead of
+        overwriting them.  All options may be suffixed with
+        <varname>-append</varname> or <varname>-delete</varname> to
+        append or delete one term from the list.  You can specify
+        building with the ipv6 variant in the following way:</para>
+
+      <para><userinput>port build +ipv6</userinput></para>
+    </sect2>
+      
+    <sect2 id="mirror_sites">
+      <title>Mirror Site Lists</title>
+
+      <para>It is possible to use predefined lists of mirror sites in
+        your <filename>Portfile</filename>, such as SourceForge or GNU
+        mirrors.  The straight-forward usage is:</para>
+
+      <programlisting>master_sites                sourceforge http://distfiles.opendarwin.org/
+master_sites.mirror_subdir  ${name}</programlisting>
+
+      <para>In this example, <varname>sourceforge</varname> is the name
+        of the mirror site list (See Chapter 3, 'Fetch Phase' for a list
+        of all available mirror site lists),
+        <varname>http://distfiles.opendarwin.org/</varname> is a normal
+        <varname>master_sites</varname> URL, and
+        <varname>${name}</varname> (the value of the
+        <varname>name</varname> keyword in the
+        <filename>Portfile</filename>) is the subdirectory to append to
+        any mirror site lists specified.</para>
+
+      <para>This will search all of the mirror sites for SourceForge and
+        then http://distfiles.opendarwin.org, appending 
+        <varname>${name}</varname> to the end of each SoureForge mirror
+        site in the list.  This example will try to fetch from:</para>
+
+      <programlisting>http://us.dl.sourceforge.net/${name}/
+ftp://us.dl.sourceforge.net/pub/sourceforge/${name}/
+...
+http://distfiles.opendarwin.org/</programlisting>
+
+      <para>Note that the value of
+        <varname>master_sites.mirror_subdir</varname> is
+        <emphasis>not</emphasis> appended to
+        <varname>http://distfiles.opendarwin.org/</varname>, this URL is
+        treated normally.  In this example
+        <varname>master_sites.mirror_subdir</varname> is a required
+        key.</para>
+
+      <para>You can also use the mirror site lists in
+        <varname>patch_sites</varname> and use
+        <varname>patch_sites.mirror_subdir</varname> to specify the
+        subdirectory.  For more information and advanced usage of mirror
+        site lists (i.e. distfile tags, multiple lists with different
+        subdirectories), please see Chapter 3, 'Fetch Phase'.</para>
+    </sect2>
+
+    <sect2 id="additional options">
+      <title>Additional Options</title>
+
+      <para>There are additional options that are commonly used in
+        <filename>Portfile</filename>s.  The following are commonly
+        used options that may be useful:</para>
+
+      <variablelist>
+        <varlistentry>
+          <term><varname>distfile</varname></term>
+
+          <listitem>
+            <para><varname>distfile</varname> is the name and version
+              combined with the <varname>extract_sufx</varname> (by
+              default <filename>${name}-${version}.tar.gz</filename>) 
+              by default, and is used by DarwinPorts to fetch the 
+              distribution file.  If the name of the file on the server 
+              is not the same as <filename>${name}-${version}.tar.gz
+              </filename> you can use this option to override the default
+              <varname>distfile</varname> name. </para>
+          </listitem>
+        </varlistentry>
+        
+        <varlistentry>
+          <term><varname>depends_lib</varname></term>
+
+          <listitem>
+            <para><varname>depends_lib</varname> is used if the port
+              needs other libraries or binaries to be installed in order
+              to <varname>configure</varname> and run.  It takes three
+              terms, separated by colons.  The first term is
+              <varname>bin</varname> or <varname>lib</varname>.  This
+              defines the search path the port system will look for the
+              dependency in.  If <varname>bin</varname> is specified,
+              <varname>$PATH</varname> is searched for the dependency.
+              If <varname>lib</varname> is specified, the library path
+              is searched instead.  The second term is a regular
+              expression that is used to search the search path for the
+              dependency.  Usually the name of the library is good
+              enough.  The port system will append
+              <filename>.dylib</filename> to the reg-ex so only dynamic
+              libraries will be matched.  The third term is the name of
+              the port that can provide the dependency if it is not
+              satisfied by something already installed on the
+              system.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>patchfiles</varname></term>
+
+          <listitem>
+            <para><varname>patchfiles</varname> is a list of patches to
+              be applied to the port (needed for the software to
+              compile/run or install correctly).  Patches are usually
+              provided in a <filename>files/</filename> directory in the
+              same directory as the
+              <filename>Portfile</filename>.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+
+      <para>Please take a look at the other chapters in this
+        Guide for more detailed information about these and other
+        options.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="common_mistakes">
+    <title>Common Mistakes</title>
+
+    <sect2 id="dont_wrap_brackets">
+     <title>Don't quote or wrap items in '{}'.</title> 
+        
+      <para> Frequently people submit ports with the description or
+        configure arguments quoted, or wrapped in curly brackets. In
+        general this is not correct.  </para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="testing_hints">
+    <title>Testing <filename>Portfiles</filename>: Tips and Hints</title>
+
+    <sect2 id="debug_verbose_msgs">
+      <title>Debugging and Verbose Messages</title>
+
+      <para>You should use the <option>-d</option> and
+        <option>-v</option> switches to <command>port</command> to
+        enable debugging and verbose messages, respectively.</para>
+    </sect2>
+
+    <sect2 id="local_repository">
+      <title>Use a Local Portfile Repository</title>
+
+      <para> Enable a second local source
+        (<filename>Portfile</filename>) repository for your
+        uncommitted ports.  Edit
+        <filename>/etc/ports/sources.conf</filename> and
+        add:<userinput>file:///User/foo/dports-dev</userinput> (or
+        wherever your local dport tree is).</para>
+
+      <para> Create an index file from the local source repository
+        root. This will also perform a simple syntax check Portfiles
+        contained.</para>
+	
+      <para><userinput>portindex</userinput></para>
+    </sect2>
+
+    <sect2 id="testing_destroot">
+      <title>Testing Destroot</title>
+      
+      <para>First run port install without root privileges, this is a
+        good way to check that the port installs into the destroot and
+        not directly into the main prefix directory, or elsewhere in
+        the system.  This should succeed up to the point darwinports
+        attempts to copy the port from the destroot into the
+        darwinports prefix. Once you are confident the port is
+        correctly destrooted install the port into the darwinports
+        prefix using root privileges. </para>
+      
+      <para><userinput>sudo port install foo</userinput></para>
+
+      <para> Ensure the Port installs into the destroot and does not
+        install anything onto the system directly, most software that
+        uses autoconf should behave correctly automatically as
+        darwinports sets DESTDIR by default. If files are directly
+        installed to the system they will not be registered and
+        packaging will fail. </para>
+    </sect2>
+
+    <sect2 id="test_uninstall">
+      <title>Test Uninstall</title>
+
+      <para> Uninstall the port </para>
+       
+      <para><userinput>sudo port uninstall foo</userinput></para>
+    </sect2>
+
+    <sect2 id="try_clean_machine">
+      <title>Try the Port on a Clean Machine</title>
+
+      <para> Make sure the port builds, installs and uninstalls on 
+      a &quot;clean machine&quot;. A clean machine should have a 
+      clean install of the OS, to avoid missing dependencies.  
+      Using a chrooted version of the OS to install and test ports 
+      makes this much easier, see the chroot 
+      <ulink url="http://darwinports.gene-hacker.net/docs/howto/chroot_10.2/index.html">
+      HOWTO</ulink> for more details on how to set up the chroot. </para>
+    </sect2>
+        
+
+    <sect2 id="clean_workdir">
+      <title>Clean the Working Directory after an Error</title>
+
+      <para> Clean the working source directory for a port. This will
+        allow a clean reinstall if an error was encountered earlier in
+        the build process.</para>
+      
+      <para> <userinput> port clean foo </userinput> </para>
+    </sect2>
+        
+  </sect1>
+    
+  <sect1 id="advice">
+    <title>Where can I ask for advice?</title> 
+
+    <para>Either on the <email>darwinports@opendarwin.org</email>
+      mailing list, or on the #opendarwin channel on irc.freenode.net.
+      Don't be afraid to ask questions! You should also look at the
+      later sections of the <link linkend="details">guide</link>and the
+      <filename>portfile</filename>(7) and
+      <filename>portstyle</filename>(7) manpages for more information.</para>
+
+  </sect1>
+
+  <sect1 id="submit_ports">
+    <title>How do I submit my Ports</title>
+      
+    <para>See the <link linkend="submission">submission chapter</link> for 
+    all the information on how to submit a port properly.</para>
+  </sect1>
+
+  <sect1 id="more_examples">
+    <title>More Example <filename>Portfile</filename>s</title>
+
+    <example id="expat">
+      <title>Expat <filename>Portfile</filename></title>
+      <programlisting><![CDATA[
+# &dollar;Id: Portfile,v 1.14 2003/07/30 14:35:39 fkr Exp &dollar;
+
+PortSystem      1.0
+
+name            libxslt
+version         1.0.21
+homepage        http://www.xmlsoft.org/
+description     gnome xslt library and xsltproc
+categories      textproc
+platforms       darwin
+maintainers     mike+libxslt@gene-hacker.net
+master_sites    ftp://xmlsoft.org/ \
+                ftp://ftp.gnome.org/pub/GNOME/sources/libxslt/1.0/
+
+checksums       md5 9cc0491e2584788748eb7069ea1d5277
+depends_lib     lib:libxml2:libxml2
+patchfiles      patch-aclocal.m4 patch-configure patch-ltmain.sh
+
+long_description Gnome library for applying XSL stylesheet transformations to \
+ xml files, comes with several useful binaries.
+
+]]></programlisting>
+    </example>
+
+    <example id="neon">
+      <title>Neon <filename>Portfile</filename></title>
+
+<programlisting><![CDATA[
+# &dollar;Id: Portfile,v 1.14 2003/07/30 14:35:39 fkr Exp &dollar;
+          
+PortSystem 1.0 
+name            neon 
+version         0.23.4
+                         
+categories      www 
+maintainers     rooneg@electricjellyfish.net
+description     An HTTP and WebDAV client library with a C interface
+                          
+master_sites    http://www.webdav.org/neon/
+checksums       md5 56b380a7352c68d425b1d3d3d610f994 
+
+depends_lib     lib:libexpat.0.4:expat 
+configure.env   LDFLAGS='-L"${prefix}/lib"' CPPFLAGS='-I"${prefix}/include"'
+
+configure.args  --with-ssl \
+                --with-force-ssl \
+                --enable-xml \
+                --enable-shared \ 
+                --with-expat
+
+]]></programlisting>
+    </example>
+
+    <para>For more examples, you can browse the directory tree of
+      DarwinPorts' <filename>dports</filename> directory and have a look
+      at the <filename>Portfile</filename>s of your favorite
+      ports.</para>
+    
+    <para>For more information about some options used in these
+      <filename>Portfile</filename> examples that were not covered in
+      this chapter, please take a look at the following chapters of this
+      Guide.</para>
+  </sect1>
+</chapter>
Index: trunk/doc/guide/xml/portfiles/special.xml
===================================================================
--- trunk/doc/guide/xml/portfiles/special.xml	(revision 4478)
+++ trunk/doc/guide/xml/portfiles/special.xml	(revision 4478)
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id="considerations">
+    <title>Special considerations</title>
+    <sect1>
+    	<title>Mac OS X applications</title>
+    	<para></para>
+		<sect2>
+			<title>Installation</title>
+			<para>Mac OS X applications should install to
+                          <filename>/Applications/DarwinPorts/</filename>.
+                        </para>
+		</sect2>
+	</sect1>
+	<sect1>
+		<title>XFree86 servers</title>
+    	<para></para>
+		<sect2>
+			<title>Prefix</title>
+			<para></para>
+		</sect2>
+	</sect1>
+	<sect1>
+		<title>Perl modules and other language libraries and plug-ins</title>
+    	<para></para>
+		<sect2>
+			<title>Perl</title>
+			<para></para>
+		</sect2>
+		<sect2>
+			<title>TCL</title>
+			<para></para>
+		</sect2>
+		<sect2>
+			<title>Ruby</title>
+			<para></para>
+		</sect2>
+		<sect2>
+                  <title>Python</title>
+		  <sect3>
+                    <title>Zope</title>
+
+                    <para>Zope products should install to the Zope
+                      <varname>$SOFTWARE_HOME</varname> rather than
+                      <varname>$INSTANCE_HOME</varname> so that they do
+                      not conflict with any user-installed products that
+                      might be in
+                      <varname>$INSTANCE_HOME</varname>.</para>
+
+                    <para>Zope products should also be prefixed with
+                      <filename>zope-</filename> so that they do not
+                      create confusion.</para>
+                  </sect3>
+                </sect2>
+		<sect2>
+			<title>Others</title>
+			<para></para>
+		</sect2>
+	</sect1>
+	
+	
+</chapter>
Index: trunk/doc/guide/xml/portfiles/style.xml
===================================================================
--- trunk/doc/guide/xml/portfiles/style.xml	(revision 4478)
+++ trunk/doc/guide/xml/portfiles/style.xml	(revision 4478)
@@ -0,0 +1,119 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<chapter id="portstyle">
+	<title>Style guide</title> 
+	<sect1>
+		<title>Overview</title> 
+		<para>A port consists of a directory and its contents, within a 
+		category subdirectory of the root of the ports tree.  This document 
+		serves as a reference for the directory structure of a single port 
+		and the layout of the files within.</para>
+
+		<para>The only required file in a port is Portfile.  The port file 
+		should be thought of as a set of declarations rather than a piece 
+		of code.  It is best to format the port file is if it were a table 
+		consisting of keys and values.  In fact, the simplest of ports 
+		will only contain a small block of values.  Therefore, whitespace 
+		should not be strown about haphazardly. Nicely formatted compact 
+		tables will result in more values being visible at the same 
+		time. </para>
+
+		<para>Try to adhere to these guidelines, but remember that this 
+		is only a guide.  No set of rules can adequately cover all cases, 
+		and in some cases the best solution is to break the rules.</para>
+
+	</sect1>
+	
+	<sect1>
+		<title>Specifics</title> 
+		
+		<sect2>
+			<title>CVS ID tags</title> 
+			<para>On the first line of the Portfile you should put a cvs 
+			ID tag. This tag will be expanded by cvs when the Portfile is 
+			committed and allows people to see at a glance details like 
+			who was the last person to commit to a port and when the last 
+			commit was performed.</para>
+
+		</sect2>
+
+		<sect2>
+			<title>PortSystem</title> 
+			<para>At the top of the port file is the requirement statement. 
+			There is a single space between the "PortSystem" statement and 
+			the version number. </para>
+
+		</sect2>
+
+		<sect2>
+			<title>Variable assignments</title> 
+			<para>Variable assignments such as "set libver" can be 
+			considered a single word on the left side, with a single 
+			space between "set" and the variable name, followed by tabs to 
+			line up with the right side. </para>
+
+		</sect2>
+
+		<sect2>
+			<title>Categories</title> 
+			<para>The first category listed for a port is the port's 
+			primary category and should coincide with the subdirectory t
+			hat the port resides in. Additional categories can be listed, 
+			but should be descriptive and accurate. </para>
+
+		</sect2>
+
+		<sect2>
+			<title>Items across multiple lines</title> 
+			<para>When items require multiple lines, they can be separated 
+			from the previous and next items with a blank line. Indent the 
+			additional lines to the same column that the right side begins 
+			on in the first line. If a single statement needs to span 
+			multiple lines, use a 2 space indentation from the first line 
+			for all additional lines. </para>
+
+		</sect2>
+
+		<sect2>
+			<title>Braces or curly brackets "{}"</title> 
+			<para>the braces may appear on the first and last lines rather 
+			than on their own lines. This is done because the right side of 
+			the port file is already indented, and to make port file read 
+			like a table. Use a single space after the brace. Indent 
+			additional lines to this same column. </para>
+
+		</sect2>
+
+		<sect2>
+			<title>Variants</title> 
+			<para>Variants are like any other part of the port file. Space, 
+			indent, and format them the same way other sections are 
+			formatted. The actual variant statement, "variant" followed 
+			by the name of the variant, can be treated as a single 
+			statement and thus placed together on the left side and 
+			separated by a single space. </para>
+
+		</sect2>
+
+		<sect2>
+			<title>Patch files</title> 
+			<para>Patch files reside in the files/ directory in the port's 
+			base directory. There should be one patch file for every file 
+			that needs to be patched. It is perfectly reasonable to use 
+			provided patches that affect multiple files, but do not 
+			create new patches that do so. Their names should begin 
+			with "patch-". The rest of the name should come from the 
+			name of the file that they apply to. In many cases just the 
+			base name of the file being patched is enough. For files 
+			such as "Makefile" this may not be the case. In this case, 
+			use enough components of the file's path to uniquely 
+			distinguish the file. Separate the components with '-' 
+			characters. The patch should apply with "patch -p0" from the 
+			working source directory of the port. </para>
+
+		</sect2>
+
+	</sect1>
+
+</chapter>
Index: trunk/doc/guide/xml/portfiles/testing.xml
===================================================================
--- trunk/doc/guide/xml/portfiles/testing.xml	(revision 4478)
+++ trunk/doc/guide/xml/portfiles/testing.xml	(revision 4478)
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id="testing">
+    <title>Testing and troubleshooting</title>
+    <sect1>
+    	<title>Testing a Port</title>
+    	<para></para>
+		<sect2>
+			<title>Installation</title>
+			<para></para>
+		</sect2>
+		<sect2>
+			<title>Use</title>
+			<para></para>
+		</sect2>
+		<sect2>
+			<title>Uninstall</title>
+			<para></para>
+		</sect2>
+		<sect2>
+			<title>Package</title>
+			<para></para>
+		</sect2>
+	</sect1>
+	<sect1>
+		<title>Troubleshooting</title>
+    	<para></para>
+		<sect2>
+			<title>Uninstall failures</title>
+			<para></para>
+		</sect2>
+		<sect2>
+			<title>Hardcoding ${prefix}</title>
+			<para></para>
+		</sect2>
+	</sect1>
+</chapter>
Index: trunk/doc/guide/xml/portfiles/variants.xml
===================================================================
--- trunk/doc/guide/xml/portfiles/variants.xml	(revision 4478)
+++ trunk/doc/guide/xml/portfiles/variants.xml	(revision 4478)
@@ -0,0 +1,111 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<chapter id="variants">
+	<title>Variants</title> 
+	<sect1>
+		<title>What are variants?</title> 
+		<para>DarwinPorts allows multiple versions of a port to be specified in a single Portfile. For example, vim can be built with and without x11 support. Rather than duplicate the whole port and have vim-x11 vim-nox ports DarwinPorts supports "variants". </para>
+
+	</sect1>
+	<sect1>
+		<title>Syntax</title> 
+		<para>The variants syntax is largely identical to the syntax in the main part of the Portfile. </para>
+
+		<variablelist>
+			<varlistentry id='variant'>
+				<term>
+					variant 
+				</term>
+				<listitem>
+					<para>The key variant is used to begin the foo variant as shown in the example. 
+						<programlisting>
+<![CDATA[
+variant foo    { 
+			      [variant code]
+			      [more variant code]
+                 }
+]]> 
+						</programlisting></para>
+
+					<para>Within the variant block essentially all of the keys available in the main section are available. Using a key used in the main section will overwrite it. </para>
+
+				</listitem>
+			</varlistentry>
+			<varlistentry id='append'>
+				<term>
+					append 
+				</term>
+				<listitem>
+					<para>For most of the keys you can append additional terms. 
+						<programlisting>
+<![CDATA[
+variant foo    { configure.args-append --with-x}
+
+]]> 
+						</programlisting></para>
+
+				</listitem>
+			</varlistentry>
+			<varlistentry id='delete'>
+				<term>
+					delete 
+				</term>
+				<listitem>
+					<para>For most of the keys you can delete terms. The item being deleted should match a string in the option being deleted exactly. 
+						<programlisting>
+<![CDATA[
+variant gnome    { configure.args-delete --without-gnome}
+
+]]> 
+						</programlisting></para>
+
+				</listitem>
+			</varlistentry>
+		</variablelist>
+	</sect1>
+	<sect1>
+		<title>Advanced variants</title> 
+		<para>For the most part, variants are quite straightforward to use. Several more advanced features of variants are also available. </para>
+
+		<variablelist>
+			<varlistentry id='default_variants'>
+				<term>
+					default_variants 
+				</term>
+				<listitem>
+					<para>In some cases you may want a variant or variants to be executed by default. For example w3m is distributed with a patch to add international text support. This is a vendor provided patch, but not a core part of the program. In this case it makes sense to make the internationalised version the default, but keep the vanilla w3m as the main port. The default_variants key is used in the main section of a Portfile, not in a variant. </para>
+
+					<para><userinput>
+							default_variants +foo +bar 
+						</userinput></para>
+
+				</listitem>
+			</varlistentry>
+			<varlistentry id='platform_variants'>
+				<term>
+					platform_variants 
+				</term>
+				<listitem>
+					<para>Platform specific variants are automatically executed on that platform, without needing any intervention from the user. Currently available platforms are: 
+						<simplelist>
+							<member>
+								darwin
+							</member>
+							<member>
+								freebsd
+							</member>
+							<member>
+								linux
+							</member>
+						</simplelist></para>
+
+					<para><userinput>
+							variant foo darwin {[variant code]} 
+						</userinput></para>
+
+				</listitem>
+			</varlistentry>
+		</variablelist>
+	</sect1>
+</chapter>
Index: trunk/doc/guide/xml/project/policies.xml
===================================================================
--- trunk/doc/guide/xml/project/policies.xml	(revision 4478)
+++ trunk/doc/guide/xml/project/policies.xml	(revision 4478)
@@ -0,0 +1,163 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<chapter id="policies">
+  <chapterinfo>
+    <keywordset>
+      <keyword>
+      </keyword>
+    </keywordset>
+  </chapterinfo>
+  
+  <title>DarwinPorts Policies</title> 
+
+  <sect1>
+    <title>About this Chapter</title>
+
+		<para>This chapter contains policies and procedures, as well as
+		responsbilities for the DarwinPorts Project.</para>
+  </sect1>
+
+  <sect1>
+    <title>Commiter's Category Responsibility List</title>
+
+		<para>DarwinPorts has at least one commiter responsible for each
+		category of ports (<filename>www</filename>,
+		<filename>textproc</filename>, etc).  This is a list of those
+		commiters.</para>
+
+		<table frame="all">
+			<title>Commiter's Category Responsibility List</title>
+			<tgroup cols="3" align="left" colsep="1" rowsep="1">
+				<colspec colname="category"/>
+				<colspec colname="commitera"/>
+				<colspac colname="commiterb"/>
+				<thead>
+					<row>
+						<entry>Category</entry>
+						<entry>Commiter A</entry>
+						<entry>Commiter B</entry>
+					</row>
+				</thead>
+				<tbody>
+					<row>
+						<entry>archives</entry>
+						<entry>waqar [at] opendarwin.org</entry>
+						<entry></entry>
+					</row>
+					<row>
+						<entry>audio</entry>
+						<entry>macdome [at] opendarwin.org</entry>
+						<entry/>
+					</row>
+					<row>
+						<entry>comms</entry>
+						<entry>fenner [at] opendarwin.org</entry>
+						<entry/>
+					</row>
+					<row>
+						<entry>databases</entry>
+						<entry>cms [at] opendarwin.org</entry>
+						<entry>macdome [at] opendarwin.org</entry>
+					</row>
+					<row>
+						<entry>devel</entry>
+						<entry>fkr [at] opendarwin.org</entry>
+						<entry/>
+					</row>
+					<row>
+						<entry>editors</entry>
+						<entry>waqar [at] opendarwin.org</entry>
+						<entry>olegb [at] opendarwin.org</entry>
+					</row>
+					<row>
+						<entry>emulators</entry>
+						<entry>fkr [at] opendarwin.org</entry>
+						<entry/>
+					</row>
+					<row>
+						<entry>games</entry>
+						<entry>wbb4 [at] opendarwin.org</entry>
+						<entry/>
+					</row>
+					<row>
+						<entry>gnome</entry>
+						<entry>olegb [at] opendarwin.org</entry>
+						<entry>fkr [at] opendarwin.org</entry>
+					</row>
+					<row>
+						<entry>graphics</entry>
+						<entry>jkh [at] opendarwin.org</entry>
+						<entry>fkr [at] opendarwin.org</entry>
+					</row>
+					<row>
+						<entry>irc</entry>
+						<entry>fkr [at] opendarwin.org</entry>
+						<entry/>
+					</row>
+					<row>
+						<entry>lang</entry>
+						<entry>gwright [at] opendarwin.org</entry>
+						<entry/>
+					</row>
+					<row>
+						<entry>mail</entry>
+						<entry>cms [at] opendarwin.org</entry>
+						<entry/>
+					</row>
+					<row>
+						<entry>math</entry>
+						<entry>gwright [at] opendarwin.org</entry>
+						<entry>macdome [at] opendarwin.org</entry>
+					</row>
+					<row>
+						<entry>net</entry>
+						<entry>fenner [at] opendarwin.org</entry>
+						<entry>fkr [at] opendarwin.org</entry>
+					</row>
+					<row>
+						<entry>print</entry>
+						<entry>cms [at] opendarwin.org</entry>
+						<entry/>
+					</row>
+					<row>
+						<entry>python</entry>
+						<entry>mww [at ] opendarwin.org</entry>
+						<entry>rshaw [at] opendarwin.org</entry>
+					</row>
+					<row>
+						<entry>science</entry>
+						<entry>wbb4 [at] opendarwin.org</entry>
+						<entry/>
+					</row>
+					<row>
+						<entry>shells</entry>
+						<entry>waqar [at] opendarwin.org</entry>
+						<entry/>
+					</row>
+					<row>
+						<entry>sysutils</entry>
+						<entry>ssen [at] opendarwin.org</entry>
+						<entry/>
+					</row>
+					<row>
+						<entry>textproc</entry>
+						<entry>wbb4 [at] opendarwin.org</entry>
+						<entry/>
+					</row>
+					<row>
+						<entry>www</entry>
+						<entry>cms [at] opendarwin.org</entry>
+						<entry>wbb4 [at] opendarwin.org</entry>
+					</row>
+					<row>
+						<entry>x11</entry>
+						<entry>jkh [at] opendarwin.org</entry>
+						<entry>olegb [at] opendarwin.org</entry>
+					</row>
+				</tbody>
+			</tgroup>
+		</table>
+
+  </sect1>
+</chapter>
Index: trunk/doc/guide/xml/project/roadmap.xml
===================================================================
--- trunk/doc/guide/xml/project/roadmap.xml	(revision 4478)
+++ trunk/doc/guide/xml/project/roadmap.xml	(revision 4478)
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<chapter id="roadmap">
+  <chapterinfo>
+    <keywordset>
+      <keyword>
+      </keyword>
+    </keywordset>
+  </chapterinfo>
+  
+  <title>DarwinPorts Roadmap</title> 
+
+  <sect1>
+    <title>About this Chapter</title>
+
+    <para>This is the DarwinPorts roadmap for future development.  This
+      chapter will contain a verbose TODO list for the project, as well
+      as (once these goals are acheived) a place where new features
+      and/or changes will be documented prior to their incorporation
+      into the Guide as a whole.</para>
+  </sect1>
+
+  <sect1>
+    <title>Remove cruft from DarwinPorts API</title>
+
+    <para>Most of the DarwinPorts API (<function>dportsearch</function>,
+      etc) is intended for use by external applications, such as Ports
+      Manager and <command>port</command>(1).  However, the DarwinPorts
+      "API" has grown organically, and there is a lot of cruft and clean
+      up that could be done. One piece of low hanging fruit would be to
+      use Tcl namespaces to properly remove the DarwinPorts API from the
+      global namespace, and only namespace export the dport*
+      procedures.</para>
+  </sect1>
+</chapter>
Index: trunk/doc/guide/xml/project/submission.xml
===================================================================
--- trunk/doc/guide/xml/project/submission.xml	(revision 4478)
+++ trunk/doc/guide/xml/project/submission.xml	(revision 4478)
@@ -0,0 +1,283 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<chapter id="submission">
+	<chapterinfo>
+		<keywordset>
+			<keyword>
+				portfile
+			</keyword>
+			<keyword>
+				submissions
+			</keyword>
+			<keyword>
+				maintainer
+			</keyword>
+		</keywordset>
+	</chapterinfo>
+	<title>DarwinPorts submissions</title> 
+	<sect1>
+		<title>Submitting a Port</title> 
+		
+		<para>Using a standardised approach to submitting the Portfiles and 
+		associated patches scripts, etc allows us to keep track of port 
+		submissions, process them efficiently and get them submitted as 
+		quickly as possible to our dports CVS tree. The following sections 
+		will describe the standard port submission procedures. </para>
+		
+		<sect2>
+			<title>Where to submit</title>
+			
+			<para> All ports should be submitted via the DarwinPorts 
+			<ulink url="http://www.opendarwin.org/bugzilla/">bugzilla tool
+			</ulink>. Your submission will be automatically emailled to the 
+			members of the 
+			<ulink url="http://www.opendarwin.org/mailman/listinfo/darwinports-bugs/">
+			darwinports-bugs</ulink> mailing list. If you are uncertain about 
+			any aspect of your port, you may also want to email it with your 
+			questions and the bug number to  
+			<ulink url="mailto:darwinports@opendarwin.org">DarwinPorts</ulink> 
+			mailing list.</para>
+			
+			<para>If you are submitting a modification, or an update to an 
+			existing port, please assign the port to the current maintainer 
+			in your bugzilla submission, so that the automatic email is 
+			directed to the maintainer, who will be best suited to deal 
+			with your submission.</para>
+			
+			<para>Updates and modifications should be submitted as diffs. See 
+			updating a port below</para>
+			
+		</sect2>
+		
+		<sect2>
+		
+			<title>Using bugzilla to submit a Port</title>
+			
+			<para>The following section describes in some more detail how to 
+			use Bugzilla to submit your port.</para>
+			
+			<sect3>
+				<title>Submission parameters</title>
+				
+				<variablelist>
+					<varlistentry id='Project'>
+						<term>
+							Project:
+						</term>
+						<listitem>
+							<para>Make sure you select the DarwinPorts 
+							project.</para>
+
+						</listitem>
+					</varlistentry>
+					
+					<varlistentry id='Component'>
+						<term>
+							Component:
+						</term>
+						<listitem>
+							<para>Select "dports" as the component. </para>
+
+						</listitem>
+					</varlistentry>
+					
+					<varlistentry id='Assigned_to'>
+						<term>
+							Assigned to: 
+						</term>
+						<listitem>
+							<para>Please assign UPDATEs and COMMENTs on 
+							existing ports to the maintainer. Otherwise, if 
+							this is a NEW port or an RFC, please leave 
+							blank. </para>
+
+						</listitem>
+					</varlistentry>
+					<varlistentry id='URL'>
+						<term>
+							URL:
+						</term>
+						<listitem>
+							<para>You may use this field to point to the 
+							portfile if it is available online, or to point 
+							to the homepage of the program project.</para>
+
+						</listitem>
+					</varlistentry>
+					<varlistentry id='Summary'>
+						<term>
+							Summary:
+						</term>
+						<listitem>
+							<para>The summary field should one of a number 
+							of standardised elements, </para>
+
+								<variablelist>
+									<varlistentry id='NEW_portname'>
+										<term>NEW: portname-1.2.3
+										</term>
+										<listitem>
+											<para>Please use this format for 
+											the submission of new ports.</para>
+
+										</listitem>	
+									</varlistentry>
+									<varlistentry id='UPDATE_portname'>
+										<term>UPDATE portname-1.2.3
+										</term>
+										<listitem>
+											<para>Please use this format for 
+											the submission of updates to ports. 
+											Please use diffs!</para>
+
+										</listitem>	
+									</varlistentry>
+									<varlistentry id='REVISION_portname'>
+										<term>REVISION: portname-1.2.3
+										</term>
+										<listitem>
+											<para>Please use this format for the 
+											submission of changes to a current, 
+											uncommitted port submission</para>
+
+										</listitem>	
+									</varlistentry>
+									<varlistentry id='RFC_portname'>
+										<term>RFC: portname-1.2.3
+										</term>
+										<listitem>
+											<para>Please use this format for 
+											the submission of Request for 
+											Comments on a Portfile.</para>
+
+										</listitem>	
+									</varlistentry>
+									<varlistentry id='ATTACHMENT_portname'>
+										<term>ATTACHMENT: portname-1.2.3
+										</term>
+										<listitem>
+											<para>to add an attachment you 
+											will have use the query tool. 
+											Once you have selected the correct 
+											port, please use this format in the 
+											summary field for your 
+											submission. </para>
+
+										</listitem>	
+									</varlistentry>
+									<varlistentry id='COMMENT_portname'>
+										<term>COMMENT: portname-1.2.3
+										</term>
+										<listitem>
+											<para>Please use this format for 
+											the submission of comments on 
+											existing ports or submissions. 
+											Most comments should be directed 
+											to the maintainer, or the mailing 
+											lists. Some comments are of a 
+											critical nature and should be 
+											logged.</para>
+
+										</listitem>	
+									</varlistentry>
+								</variablelist>
+								
+						</listitem>
+					</varlistentry>
+					<varlistentry id='Description'>
+						<term>
+							Description:
+						</term>
+						<listitem>
+							<para>The description field should contain the 
+							following information as per the example given 
+							here here. </para>
+
+								<programlisting>
+<![CDATA[
+Portname-1.2.3
+
+the portfile can be found here: URL or ATTACHED or INLINE
+
+Description: What does this program do in a nutshell,
+briefly what changes were made, or what files you are attaching in the tarball.
+
+Homepage: URL of project or program itself, not the portfile
+
+Comments: Any comments you have about your port, concerns, lookouts, 
+dependencies that you may want to mention
+
+================INLINE CONTENT================
+-- 
+your sig if you'd like
+]]> 
+						</programlisting>
+								
+						</listitem>
+					</varlistentry>
+				</variablelist>
+				
+			</sect3>
+			
+			<sect3>
+				<title>Final comments on Port submission</title>
+			
+				<para>The following general points should also be borne in 
+				mind when submitting to bugzilla:
+					<simplelist type="vert">
+						<member>Small changes or portfiles should be 
+						inlined. </member>
+						<member>Larger changes should be attached as a 
+						single file, tar works wonderfully for this. </member>
+						
+						<member>Multiple patched files should be bundled 
+						together using tar and attached to the submission</member>
+						
+						<member>Currently attachments must be sent in 
+						using the current bug number, remeber to query 
+						bugzilla to find out the current bug number, select
+						 that bug and use the 'Create a New Attachment' 
+						 link.</member>
+						 
+					</simplelist></para>
+
+			</sect3>
+		</sect2>
+		<sect2>
+			<title>Updating a port</title>
+			<para>The following guidelines are for submitting updates to 
+			ports that are currently in the tree</para>
+
+			<para>All updates and modifications to existing ports should 
+			be sent in as diffs.</para>
+			<para>There are a couple of ways to obtain correct diff 
+			formats</para>
+			<para>Using diff:
+				<simplelist type="vert">
+					<member>Obtain the original file (oldfile)</member>
+					
+					<member>cp oldfile oldfile.new</member>
+					
+					<member>edit oldfile.new and save your changes</member>
+					
+					<member>diff -u oldfile oldfile.new > oldfile.diff</member>
+					
+					<member>Use bugzilla to submit your port UDPATE</member>
+					
+				</simplelist></para>
+
+			<para>Or using cvs diff:
+				<simplelist type="vert">
+					<member>checkout the original source using cvs</member>
+					<member>edit the files and save your changes</member>
+					<member>cvs diff -u sourcefile > sourcefile.diff</member>
+					<member>use bugzilla to submit your port UPDATE</member>
+				</simplelist></para>
+
+			<para>Lastly, if your update consists of several files, use tar 
+			to bundle them into one file for submission</para>
+
+		</sect2>
+	</sect1>
+</chapter>
Index: trunk/doc/guide/xml/user/dp_manager.xml
===================================================================
--- trunk/doc/guide/xml/user/dp_manager.xml	(revision 4478)
+++ trunk/doc/guide/xml/user/dp_manager.xml	(revision 4478)
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<chapter id="dp_manager">
+  <chapterinfo>
+    <keywordset>
+      <keyword>
+	usage
+      </keyword>
+      
+      <keyword>
+	introduction
+      </keyword>
+		      
+      <keyword>
+        user
+      </keyword>
+      
+      <keyword>
+	manual
+      </keyword>
+    </keywordset>
+  </chapterinfo>
+  
+  <title>DarwinPorts Manager</title> 
+  
+  <sect1>
+    <title>About this chapter</title>
+
+    <para>This chapter provides an overview of the DarwinPorts Manager
+      application and how to use it as an alternative to the command-line 
+      tools for DarwinPorts.</para>
+
+  </sect1>
+	
+  <sect1 id='darwinportsmanager'>
+    <title>DarwinPorts Manager.app</title>
+    
+    <para>DarwinPorts Manager.app is a Cocoa GUI for the DarwinPorts
+      project.  It will allow users to browse through available ports and
+      their descriptions and to download, install, and uninstall the
+      software.  DarwinPorts Manager.app is currently under development,
+      and is based on the older Ports Manager.app.  There is a Port for
+      the older Ports Manager.app, and will be in the future for
+      DarwinPorts Manager.app, so you can use DarwinPorts to install it
+      for you!  <userinput>sudo port install PortsManager</userinput>.
+      Ports Manager.app will be installed in your
+      <filename>/Applications/Utilities</filename> folder.  A <ulink
+      url='http://www.opendarwin.org/~fkr/portsmanager.png'>screen shot
+      is available</ulink> of Ports Manager.app in action.</para>
+
+    <para>We will also be providing a binary installer (a '.pkg') file in
+      the near future for DarwinPorts Manager.app.</para>
+  </sect1>
+</chapter>
Index: trunk/doc/guide/xml/user/user.xml
===================================================================
--- trunk/doc/guide/xml/user/user.xml	(revision 4478)
+++ trunk/doc/guide/xml/user/user.xml	(revision 4478)
@@ -0,0 +1,623 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<chapter id="user_info">
+	<chapterinfo>
+		<keywordset>
+			<keyword>
+				usage
+			</keyword>
+			<keyword>
+				introduction
+			</keyword>
+			<keyword>
+				user
+			</keyword>
+			<keyword>
+				manual
+			</keyword>
+		</keywordset>
+	</chapterinfo>
+	<title>Using DarwinPorts</title> 
+	
+	
+	<sect1>
+		<title>About this chapter</title>
+		 
+		<para>This document provides a short guide to the basics of the 
+		DarwinPorts system. The first section provides a short description 
+		of the goals of the project and a brief comparison with other systems. 
+		Subsequent sections describe how to get, install, and use DarwinPorts 
+		on your own machines. </para>
+
+		
+	</sect1>
+	
+	
+	<sect1 id='about_dports'>
+		<title>About DarwinPorts</title> 
+		
+		<para>The aim of the DarwinPorts project is to develop a second-
+		generation system for the building, installation and management of 
+		third party software. DarwinPorts is mainly developed on Mac OS X, 
+		however by design it is quite portable and is intended to work on 
+		other UNIX-like systems, especially *BSD and hopefully Linux-based 
+		systems.  </para>
+
+		
+		<para>DarwinPorts is probably best described by comparison:  It's sort 
+		of like the <ulink url='http://www.freebsd.org/ports'>FreeBSD ports 
+		collection</ulink> or <ulink url='http://fink.sf.org/'>Fink</ulink> 
+		in that it automates the process of building third party software for 
+		Mac OS X and other operating systems.  DarwinPorts also tracks all 
+		dependency information for a given piece of software. In other words, 
+		it knows what it needs to build and install and in what order for the 
+		piece of software you want to work properly. DarwinPorts knows how to 
+		make, build and install the software to a specific location, meaning 
+		that software installed via DarwinPorts doesn't simply scatter itself 
+		all over the system or require user knowledge of dependencies in what 
+		order. </para>
+
+		
+		<para>The FreeBSD Ports Collection is a large set of software packages 
+		ported to FreeBSD. The ports collection is also used on the other "free"
+		BSDs. The FreeBSD Ports Collection is based on a large tree of ports 
+		where each software has a directory within a category (like mail or 
+		graphics). That directory contains the information needed to build the 
+		piece of software. DarwinPorts also uses a directory structure like this,
+		although unlike FreeBSD ports the intention is to avoid requiring a 
+		complete copy of the 'Ports Tree' on every user's machine.  The FreeBSD 
+		Ports Collection is essentially implemented as some very impressive but
+		hairy BSD make(1)'s macros and can be  opaque and non-extensible from 
+		the perspective of someone looking to extend or refactor parts of the 
+		system.  Given that makefiles aren't the easiest thing to parse or for
+		non-developers to understand, it is also harder to "mine" the FreeBSD
+		ports collection for data to use for other purposes such as 
+		generating documentation indexes or arbitrary front-ends for 
+		creating or managing ports. </para>
+
+
+		<para>A ports collection can be considered an 'expert system' that 
+		knows the sources, dependencies, and other information necessary to 
+		*build* a given Open Source project.  A package management system relies 
+		on similar dependency information, but is focused on safely installing 
+		(and de-installing) software.   Before DarwinPorts, most systems did 
+		both at once; DarwinPorts, however, is explicitly designed as a pure 
+		ports collection which can use various package management systems.
+		</para>
+
+		
+		<para>Even discounting some of the limitations of The FreeBSD Ports 
+		Collection described above, creating automated build systems is rather 
+		more complex than it looks at first glance and there's always room for 
+		fresh approaches to the problem.  Which is what we have set out to do 
+		with DarwinPorts. There are certainly other systems, some of which have 
+		already been mentioned, which have made their own attempts at solving 
+		this problem. There will likely be many more such systems in the future 
+		since trying to find a single solution which pleases everyone is rather 
+		like trying to find a single programming language which pleases everyone 
+		- it's more or less impossible. </para>
+
+		
+		<para>DarwinPorts is mostly written in Tcl, with some components written 
+		in C. Tcl was chosen to allow DarwinPorts to be readily embedded in other 
+		applications (e.g. a Cocoa GUI) and to allow flexible, but easy to read 
+		Portfiles. </para>
+
+		
+		<para>Even though DarwinPorts is written in Tcl, users do not need to know 
+		Tcl in order to use the system or even to add new ports.  Port description 
+		files, though they are actually full Tcl programs in their own right, are 
+		designed to look like a simple list of key/value pairs. </para>
+
+	</sect1>
+	
+	
+	<sect1 id='setup'>
+		<title>Installing DarwinPorts</title>
+		
+		<sect2 id='prerequisites'>
+			<title>What you need</title>
+			
+			<para>Currently DarwinPorts is only supported on Mac OS X 10.2 or later 
+			(i.e., Darwin 6.0 or later).   However, these instructions should also 
+			enable it to  work on FreeBSD and NetBSD, at least most of the time; 
+			not every build of DarwinPorts is tested on those platforms, so some 
+			minor breakage may creep in from time to time.</para>
+
+
+			<para>To install and use DarwinPorts you must install the Developer 
+			tools (gcc, autoconf etc on other platforms). All the other 
+			prerequisites are pre-installed on Mac OS X 10.2 and later. On other 
+			platforms you will need to ensure you have installed Tcl (8.3 or 
+			later). </para>
+
+			
+		</sect2>
+		
+		<sect2 id='getting_dports'>
+			<title>Obtaining DarwinPorts</title>	
+			
+			<para>Currently the main way to get DarwinPorts is by using the Concurrent 
+			Versioning System (cvs). CVS is installed with the Developers Tools on Mac 
+			OS X. To download DarwinPorts using cvs you should use the following 
+			Terminal commands. At this time you must keep the darwinports directoy 
+			that is downloaded on your machine, even after installation as it also 
+			contains all the port description files (Portfiles). In the future these 
+			will be automatically downloaded as they are needed so you won't need to 
+			keep the directory. Choose a location for DarwinPorts where you won't 
+			want/need to move it. For the rest of the document I will assume the user 
+			name is 'mike' and the DarwinPorts infrastructure is going to be 
+			downloaded to a directory (folder) called darwinports in your home 
+			directory (i.e. /Users/mike/darwinports/) you should replace the username 
+			with your own username and edit the commands I give so they work 
+			correctly on your installation. <programlisting><![CDATA[
+ 
+% cd ~/
+% cvs -d :pserver:anonymous@anoncvs.opendarwin.org:/Volumes/src/cvs/od login
+% cvs -d :pserver:anonymous@anoncvs.opendarwin.org:/Volumes/src/cvs/od co -P darwinports 
+]]>
+				</programlisting></para>
+	
+			
+			<para>These commands first ensure you are currently in your home 
+			directory, then log onto the opendarwin cvs server and finally 
+			'checkout' (download) DarwinPorts. </para>
+
+			<para>There is also a <ulink 
+			url='http://www.opendarwin.org/~fkr/snapshots/'> cvs snapshot</ulink> 
+			available that is made from cvs every 6 hours. The tarball is made 
+			from a anonymous checkout of DarwinPorts so you can still use the 
+			commands below for <link linkend='updating_dports'>updating</link>. 
+			</para>
+	
+			<para>In the near future we will provide a binary installer for 
+			DarwinPorts and the source files downloadable directly from the 
+			website rather than requiring users to use cvs. CVS is likely to 
+			remain important for users who want to closely track the latest 
+			ports as it can be used to update your port descriptions (and 
+			is currently the only way to do so). </para>
+
+			
+		</sect2>
+		
+		<sect2 id='install_dports'>
+			<title>Installing DarwinPorts</title>
+			
+			<para>To install DarwinPorts execute the following commands from the 
+			darwinports/base directory.<programlisting><![CDATA[
+
+% ./configure 
+% make
+% sudo make install
+
+]]>
+			</programlisting>
+			This will compile and install all the necessary software. In order 
+			to install DarwinPorts on *BSD the default group-ownership must be 
+			passed to each make command: <userinput>make DSTGRP=wheel
+			</userinput>.</para>
+
+			
+			<para>To configure DarwinPorts you should edit 
+			/etc/ports/sources.conf. The sources.conf lists the location of 
+			both local and remote port software hierarchies (Currently there is 
+			not a remote repository). Add an entry for your local ports tree: 
+			<userinput>file:///Users/mike/darwinports/dports</userinput>. To 
+			edit the file you must use a command line text editor like pico 
+			or vi. </para>
+
+			
+			<para>You should add /opt/local/bin (or wherever you chose to 
+			install DarwinPorts) to your path. If you aren't sure how, add 
+			<userinput>set path=($path /opt/local/bin)</userinput> to your 
+			.cshrc file. You may need to create the file first if you 
+			haven't set one up before. Then close the Terminal window and 
+			open a new one so the new path setting takes effect.</para>
+
+			
+			<para>Once you have got this far, you should have a working 
+			installation of DarwinPorts, you have installed the 'port' 
+			command (by default this installed as /opt/local/bin/port) 
+			and the libraries it needs (in /opt/local/share/darwinports 
+			and /System/Library/Tcl/8.3/darwinports1.0 by default. 
+			</para>
+
+			
+		</sect2>
+	</sect1>
+	
+	
+	<sect1>
+		<title>Using DarwinPorts</title>
+		
+		<sect2 id='port'>
+			<title>The port command</title>
+
+			<!--
+
+			<para>Using DarwinPorts is very straightforward, most of the time 
+			all you need to do is execute a single command to install a port. 
+			For example, if you want to install the text editor vile, you'd 
+			simply execute the command <userinput>sudo port install vile
+			</userinput>. That will fetch, build and install vim and anything 
+			else vim needs to work. All of the examples below use the vile 
+			port as an example, you should use whatever port you actually 
+			want to install.</para>
+			
+			<para>If you aren't sure of the exact name of your port you can 
+			use the search feature. For example, if you wanted to find out 
+			if there was anything called vile in the ports you could do: 
+			<userinput>port search 'vile'</userinput>. The search facility 
+			uses standard regular expression syntax, so you can list all 
+			the ports by doing: <userinput>port search '.+'</userinput>.</para>
+			
+			<para>You can see more detail of what is happening when you 
+			install a port by using the verbose (-v), or debug (-d) flags 
+			when using the port install command, to see all the possible 
+			output use them both together: <userinput>port -v -d install 
+			vile</userinput>. </para>
+
+			<para>You may break up the installation of a port into a number of 
+			steps, fetch, checksum, configure, build, and finally install. Each 
+			of these steps performs a part of the process to install a port, 
+			using the steps individually is however not normally needed unless 
+			you are developing a new port or are trying to diagnose a 
+			problem. </para>
+
+			<para>Once the port has been installed, you may want to delete 
+			all the intermediate files that DarwinPorts has created while 
+			building the port, to do this you should enter: 
+			<userinput>port clean vile</userinput>.</para>
+			-->
+
+			<para>Using the DarwinPorts <userinput>port</userinput> command is
+			very straight-forward.  Most of the time all you need to do is
+			execute a single command to install a port.  For example, if you
+			want to install the text editor vile, you would simply
+			type:</para>
+
+			<para><userinput>sudo port install vile</userinput></para>
+
+			<para>That will fetch, build and install vile and anything else it
+			needs to work.  All of the examples below use the vile for as an
+			example.  You should use whatever port you actually want
+			to install.</para>
+
+			<para>The <userinput>port</userinput> command provides several
+			other 'actions' that can be performed:</para>
+
+			<variablelist>
+				<varlistentry>
+					<term>Searching</term>
+					
+					<listitem>
+						<para>If you aren't sure the exact name of the port you
+						want, you can use the <userinput>search</userinput> option.
+						For example, if you wanted to find out if there was anything
+						called vile in in the ports, you could do:</para>
+
+						<para><userinput>port search 'vile'</userinput></para>
+
+						<para>The search facility uses standard regular expression
+						syntax, so you can also do much more complex
+						searches.</para>
+					</listitem>
+				</varlistentry>
+
+				<varlistentry>
+					<term>Additional Steps: fetch, configure, build, destroot,
+					install</term>
+						
+					<listitem>
+						<para>You may want to break up the installation of a port
+						into a number of steps.  <userinput>fetch</userinput>,
+						<userinput>configure</userinput>,
+						<userinput>build</userinput>,
+						<userinput>destroot</userinput> and finally
+						<userinput>install</userinput> are all available and perform
+						part of the build or install process.  Using the steps
+						individually is not normally needeed unless you are
+						developing a new port or trying to diagnose a
+						problem.</para>
+					</listitem>
+				</varlistentry>
+
+				<varlistentry>
+					<term>Cleaning a Port</term>
+
+					<listitem>
+						<para>Once the port has been installed, you may want to
+						delete all the intermediate files that DarwinPorts has
+						created while building the port.  To do this, simply use the
+						<userinput>clean</userinput> option:</para>
+
+						<para><userinput>port clean vile</userinput></para>
+					</listitem>
+				</varlistentry>
+
+				<varlistentry>
+					<term>Listing Ports</term>
+
+					<listitem>
+						<para>You may want a list of all the ports that are
+						available.  You can do this two ways, first by using the
+						<userinput>search</userinput> option:</para>
+
+						<para><userinput>port search '.+'</userinput></para>
+
+						<para>Or, by using the <userinput>list</userinput>
+						option:</para>
+
+						<para><userinput>port list</userinput></para>
+					</listitem>
+				</varlistentry>
+
+				<varlistentry>
+					<term>Contents of a Port</term>
+
+					<listitem>
+						<para>Once the port has been installed, you might want to
+						check what files are associated with that port.  The
+						<userinput>contents</userinput> option will list all of the
+						files that were installed by the port:</para>
+
+						<para><userinput>port contents vile</userinput></para>
+					</listitem>
+				</varlistentry>
+
+				<varlistentry>
+					<term>Variants and Dependencies</term>
+
+					<listitem>
+						<para>Before you install a port, you may want to check what
+						variations of that port are available to use.  Variants
+						provide additional configuration options for a port.  To see
+						what variations a port has, use the
+						<userinput>variants</userinput> option:</para>
+
+						<para><userinput>port variants vile</userinput></para>
+
+						<para>You also may want to see what dependencies a port has.
+						You can use the <userinput>deps</userinput> option to
+						check:</para>
+
+						<para><userinput>port deps vile</userinput></para>
+					</listitem>
+				</varlistentry>
+			</variablelist>
+
+			<para>For more information you should look at the port manpage 
+			by entering: <userinput>man port</userinput>.</para>
+
+		</sect2>
+		
+		<sect2 id='portindex'>
+			<title>The portindex command</title>
+			
+			<para>Most of the time you won't need to use this command as 
+			it is used to build the index of all the available ports, but 
+			sometimes the index you have is out of date or innacurate for 
+			some reason. When this occurs you will get an error message 
+			like 'port search failed: expected integer but got "PortIndex"'.
+			You can fix problem by moving to the dports directory 
+			(/Users/mike/darwinports/dports in our examples) and 
+			executing: <userinput>portindex</userinput>. This will go 
+			through all the available ports in the dport directory and 
+			build an index file called PortIndex.</para>
+
+			
+		</sect2>
+		
+		<sect2  id='updating_dports'>
+			<title>Updating DarwinPorts</title>
+			
+			<para>New ports are always being added to the DarwinPorts dports 
+			tree, you should regularly update your tree to get access to new 
+			ports, and (hopefully) improved versions of current ports. Currently 
+			the simplest way you can update the dports tree is to use cvs. You 
+			should change directory to the dports directory and then execute: 
+			<userinput>cvs -z3 update -dP</userinput>. You should see a set of 
+			lines printed out in the terminal as the update progresses. You 
+			may need to update your PortIndex as mentioned previously: 
+			<userinput>portindex</userinput>. </para>
+
+			
+			<para>You can also use cvs to fetch an new version of the 
+			DarwinPorts infrastructure (eg the port command and associated 
+			libraries). To do this you should change directories to the 
+			darwinports/base directory and execute the following commands:
+			<programlisting><![CDATA[
+ 
+% cvs -z3 update -dP
+% ./configure
+% make clean && make
+% sudo make install
+]]>
+				</programlisting>This will build and install the new version 
+				of DarwinPorts. You don't need to do this very often, although 
+				DarwinPorts is a young project and continually improving so we 
+				encourage you to keep up to date. </para>
+
+			
+		</sect2>
+		
+		<sect2 id='uninstall_dports'>
+			<title>Removing ports</title>
+			
+			<para>Ports are removed using the port command described above, 
+			simply execute the command: 
+			<userinput>sudo port uninstall vile</userinput></para>
+
+		</sect2>
+		
+		<sect2 id='upgrade_dports'>
+			<title>Upgrading ports</title>
+			
+			<para>At the moment there is not a 'port upgrade' command so 
+			to upgrade a port you must uninstall and then install it again. 
+			<programlisting><![CDATA[
+ 
+% sudo port uninstall vile
+% sudo port install vile
+]]>
+				</programlisting></para>
+
+			
+		</sect2>
+	</sect1>
+	
+	
+	<sect1 id='troubleshooting_use'>
+		<title>Troubleshooting</title>
+		
+		<para>There are a number of common problems so before you report a 
+		problem (details on how to <link linkend='user_bugs'>report problems</link>
+		 follow) check that the problem is described here, or in the 
+		 <ulink url='http://www.opendarwin.org/projects/darwinports/en/faq.php'>
+		 FAQ</ulink> first.</para>
+
+		<sect2>
+			<title>Common errors and problems</title>
+					
+			<sect3 id='E_port_search'>
+				<title>port search failed: expected integer but got 
+				"PortIndex"</title>
+	
+				<para>This means your PortIndex file is incorrect or 
+				potentially corrupted, run the <link linkend='portindex'>
+				portindex</link> command</para>
+
+				
+			</sect3>
+		</sect2>
+		
+		<sect2 id='user_bugs'>
+			<title>Bug reports</title>
+			<para>If the you have updated your ports tree, searched the 
+			darwinports@opendarwin.org mailling list archives and read the 
+			common problems and the FAQ and you still can't find the answer 
+			to the problem, you should submit a bug report via bugzilla.</para>
+
+
+			<para>The following section describes in some more detail how 
+			to use Bugzilla to submit your port.</para>
+
+			<sect3>
+				<title>Submission parameters</title>
+				
+				<variablelist>
+					<varlistentry id='Project'>
+						<term>
+							Project:
+						</term>
+						<listitem>
+							<para>Make sure you select the DarwinPorts 
+							project.</para>
+
+						</listitem>
+					</varlistentry>
+
+					<varlistentry id='Component'>
+						<term>
+							Component:
+						</term>
+						<listitem>
+							<para>Select "dports" as the component. </para>
+
+						</listitem>
+					</varlistentry>
+					<varlistentry id='Assigned_to'>
+						<term>
+							Assigned to: 
+						</term>
+						<listitem>
+							<para>Please assign updates, bug reports and 
+							comments on existing ports to the maintainer. 
+							Otherwise, if this is a new port or an RFC, 
+							please leave blank</para>
+
+						</listitem>
+					</varlistentry>
+
+					<varlistentry id='URL'>
+						<term>
+							URL:
+						</term>
+						<listitem>
+							<para>You may use this field to point to the 
+							port output if it is available online.</para>
+
+						</listitem>
+					</varlistentry>
+
+					<varlistentry id='Summary'>
+						<term>
+							Summary:
+						</term>
+						<listitem>
+						<para>Please use this format 
+						<userinput>BUG: portname-1.2.3</userinput> for 
+						the submission of port installation failures. </para>
+
+						</listitem>	
+					</varlistentry>
+
+					<varlistentry id='Description'>
+						<term>
+							Description:
+						</term>
+						<listitem>
+							<para>The description field should contain the 
+							following information as per the example given 
+							here here. </para>
+
+								<programlisting>
+<![CDATA[
+Portname-1.2.3
+
+the error log can be found here: URL or ATTACHED or INLINE
+
+Description: What the problem was in a nutshell,
+
+Comments: Any comments you have about the port, bug diagnosis steps, 
+concerns, lookouts, dependencies that you may want to mention.
+
+================INLINE CONTENT================
+-- 
+your sig if you'd like
+]]> 
+						</programlisting>
+								
+						</listitem>
+					</varlistentry>
+				</variablelist>
+			</sect3>
+		</sect2>
+	</sect1>
+	
+	
+	<sect1 id='portsmanager'>
+		<title>Ports Manager.app</title>
+		
+		<para>Ports Manager.app is a Cocoa GUI for the DarwinPorts project, 
+		it allows users to browse through available ports and their 
+		descriptions and to download, install and uninstall the software. 
+		Ports Manager.app is currently under development and is less 
+		reliable in use than the command line tools. There is a Port for 
+		the application so you can actually use DarwinPorts to install 
+		it for you! <userinput>sudo port install 'PortsManager'</userinput>. 
+		Ports Manager.app will be installed in your /Applications/Utilities 
+		folder. You must have the DarwinPorts Tcl libraries installed to 
+		use the Ports Manager.app. A 
+		<ulink url='http://www.opendarwin.org/~fkr/portsmanager.png'>
+		screen shot is available</ulink> of Ports Manager.app in 
+		action. </para>
+
+		
+		<para>We will also be providing a binary installer (a '.pkg') file in
+		 the near future for Ports Manager.app.</para>
+
+		
+	</sect1>
+</chapter>
