From 6bd8306f08b3a837bbc451eb1f3e8c9cf9e4f5b4 Mon Sep 17 00:00:00 2001
From: Mark Linimon <linimon@FreeBSD.org>
Date: Sun, 23 May 2010 04:11:34 +0000
Subject: [PATCH] Document the rest of the options of the build command.  Fix
 up the example of the packagebuild command.  Add some text about cleaning up
 builds.  Finally, remove some cruft.

---
 .../articles/portbuild/article.sgml           | 85 +++++++++++++++----
 1 file changed, 69 insertions(+), 16 deletions(-)

diff --git a/en_US.ISO8859-1/articles/portbuild/article.sgml b/en_US.ISO8859-1/articles/portbuild/article.sgml
index b054eb3cc7..e6605f1df4 100644
--- a/en_US.ISO8859-1/articles/portbuild/article.sgml
+++ b/en_US.ISO8859-1/articles/portbuild/article.sgml
@@ -471,16 +471,10 @@
 
       <para>You may need to manipulate the build data before starting it,
 	especially for experimental builds.  This is done with
-	<command>build</command> command.</para>
+	the <command>build</command> command.  Here are the useful
+	options for creation:</para>
 
       <itemizedlist>
-	<listitem>
-	  <para><literal>build list <replaceable>arch</replaceable>
-	    <replaceable>branch</replaceable></literal> - Shows the current set
-	    of build ids.
-	  </para>
-	</listitem>
-
 	<listitem>
 	  <para><literal>build create <replaceable>arch</replaceable>
 	    <replaceable>branch</replaceable>
@@ -529,7 +523,7 @@
 	package set.  This can be accomplished with the following
 	invocation:</para>
 
-      <para><command>/var/portbuild/evil/qmanager/packagebuild <replaceable>amd64</replaceable> <replaceable>7-exp</replaceable> <replaceable>20080904212103</replaceable> <replaceable>aclock-0.2.3_2</replaceable></command></para>
+      <para><command>/var/portbuild/evil/qmanager/packagebuild <replaceable>amd64</replaceable> <replaceable>7-exp</replaceable> <replaceable>20080904212103</replaceable> <replaceable>aclock-0.2.3_2.tbz</replaceable></command></para>
     </sect2>
   </sect1>
 
@@ -620,10 +614,33 @@
     </para>
   </sect1>
 
-  <sect1 id="interrupting">
+  <sect1 id="build-maintenance">
+    <title>Build Maintenance</title>
+
+    <para>There are several cases where you will need to manually clean
+      up a build:
+    </para>
+
+    <orderedlist>
+      <listitem>
+	<para>You have manually interrupted it.</para>
+      </listitem>
+
+      <listitem>
+	<para><hostid>pointyhat</hostid> has been rebooted while
+	  a build was running.</para>
+      </listitem>
+
+      <listitem>
+	<para><filename>qmanager</filename> has crashed and
+	  has been restarted.</para>
+      </listitem>
+      </orderedlist>
+
+  <sect2 id="interrupting">
     <title>Interrupting a Build</title>
 
-    <para>Interrupting a build is a bit messy.  First you need to
+    <para>Manually interrupting a build is a bit messy.  First you need to
       identify the tty in which it's running (either record the output
       of &man.tty.1; when you start the build, or use <command>ps x</command>
       to identify it.  You need to make sure that nothing else important
@@ -646,6 +663,11 @@
      processes, they'll keep going (or respawn) until they've built their
      package.</para>
 
+  </sect2>
+
+  <sect2 id="cleanup">
+    <title>Cleaning up a Build</title>
+
     <para>To free up resources, you will need to clean up client machines by
       running <command>build cleanup</command> command.  For example:
       <screen>&prompt.user; <userinput>/var/portbuild/scripts/build cleanup i386 8-exp 20080714120411 -full</userinput></screen>
@@ -697,13 +719,44 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
       <filename>dopackages</filename> will simply exit.
     </para>
 
-    <!-- XXX MCL the Makefile part is obsolete? -->
     <para>If you have to do a ports tree update before
       restarting, you may have to rebuild either <filename>duds</filename>,
-      <filename>INDEX</filename>, or both.  If you are doing the latter
-      manually, you will also have to rebuild
-      <filename>packages/All/Makefile</filename> via the
-      <command>makeparallel</command> script.</para>
+      <filename>INDEX</filename>, or both.</para>
+
+    </sect2>
+
+    <sect2 id="build-command-2">
+      <title>Maintaining builds with the <command>build</command>
+	 command</title>
+
+      <para>Here are the rest of the options for the <command>build</command>
+	command:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para><literal>build destroy <replaceable>arch</replaceable>
+	    <replaceable>branch</replaceable></literal> - Destroy the
+	    build id.
+	  </para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>build list <replaceable>arch</replaceable>
+	    <replaceable>branch</replaceable></literal> - Shows the current set
+	    of build ids.
+	  </para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>build upload <replaceable>arch</replaceable>
+	    <replaceable>branch</replaceable></literal> - not yet
+	    implemented.
+	  </para>
+	</listitem>
+      </itemizedlist>
+
+    </sect2>
+
   </sect1>
 
   <sect1 id="monitoring">