Add a stub for a section to explain the new pointyhat configuation files.

While here, reformat the introduction, and add some other notes.

en_US.ISO8859-1/articles/portbuild/article.sgml

@@ -35,7 +35,7 @@
   </articleinfo>
 
   <sect1 id="intro">
-    <title>Introduction and Conventions</title>
+    <title>Introduction</title>
 
     <para>In order to provide pre-compiled binaries of third-party
       applications for &os;, the Ports Collection is regularly
@@ -43,6 +43,18 @@
       Currently, the main cluster in use is at
       <ulink url="http://pointyhat.FreeBSD.org"></ulink>.</para>
 
+    <para>This article documents the internal workings of the
+     cluster.</para>
+
+    <note>
+      <para>Many of the details will be of interest only to
+      those on the <ulink url="&url.base/portmgr">Ports Management</ulink>
+      team.</para>
+    </note>
+
+    <sect2 id="codebase">
+      <title>The codebase</title>
+
     <para>Most of the package building magic occurs under the
       <filename>/var/portbuild</filename> directory.  Unless
       otherwise specified, all paths will be relative to
@@ -78,6 +90,8 @@
       <listitem><para>for experimental builds</para></listitem>
     </itemizedlist>
 
+    </sect2>
+
     <sect2 id="codebase-notes">
       <title>Notes on the codebase</title>
 
@@ -92,8 +106,8 @@
 
 	<listitem><para>factoring out all configuration constants (which
 	  were previously scattered throughout the code) into configuration
-	  files</para></listitem>
-	  <!-- XXX MCL TODO add an href to a new section on how they work -->
+	  files (see <link linkend="new-head-node">below</link>)
+	  </para></listitem>
 
 	<listitem><para>appending the hostname to the directories
 	  specified by <literal>buildid</literal> (this will allow
@@ -963,7 +977,9 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
     <note>
       <para>To avoid build errors with ports that need to be manually
 	fetched, put the distfiles into
-	<filename>~ftp/pub/FreeBSD/distfiles</filename>.</para>
+	<filename>~ftp/pub/FreeBSD/distfiles</filename>.
+	Access restrictions are in place to make sure that only the
+	build clients can access this directory.</para>
     </note>
   </sect1>
 
@@ -2233,6 +2249,12 @@ ln -s ../<replaceable>arch</replaceable>/archive/errorlogs <replaceable>arch</re
     </itemizedlist>
   </sect1>
 
+  <sect1 id="new-head-node">
+    <title>How to configure a new head node (pointyhat instance)</title>
+
+    <para>This section is in progress.</para>
+  </sect1>
+
   <sect1 id="disk-failure">
     <title>Procedures for dealing with disk failures</title>