- add some initial notes about recently added support for parallel builds

Roughly reviewed by: pav, jmallett, rwatson

en_US.ISO8859-1/books/porters-handbook/book.sgml

@@ -4464,6 +4464,32 @@ PORTVERSION=   1.0</programlisting>
     <sect1 id="building">
       <title>Building mechanisms</title>
 
+      <sect2 id="parallel-builds">
+	<title>Parallel ports building</title>
+
+	<para>The &os; ports framework supports parallel building using
+	  multiple <command>make</command> sub-processes, which allows
+	  <acronym>SMP</acronym> systems to utilize all of their available
+	  <acronym>CPU</acronym> power, allowing port builds to be faster
+	  and more effective.</para>
+
+	<para>This is achieved by passing <makevar>-jX</makevar> flag to
+	  &man.make.1; running on vendor code.  Unfortunately, not all
+	  ports handle parallel building well.  Therefore it is required
+	  to explicitly enable this feature by adding
+	  <literal>MAKE_JOBS_SAFE=yes</literal> somewhere below the
+	  dependency declaration section of the
+	  <filename>Makefile</filename>.</para>
+
+	<para>Another option for controlling this feature from the
+	  maintainer's point of view is the
+	  <makevar>MAKE_JOBS_UNSAFE=yes</makevar> variable.  It is used
+	  when a port is known to be broken with <makevar>-jX</makevar>
+	  and a user forces the use of multi processor compilations for
+	  all ports in <filename>/etc/make.conf</filename> with the
+	  <literal>FORCE_MAKE_JOBS=yes</literal> variable.</para>
+      </sect2>
+
       <sect2 id="using-make">
 	<title><command>make</command>, <command>gmake</command>, and
 	  <command>imake</command></title>