Improve markup. Describe MASTER_SITE_BACKUP and MASTER_SITE_LOCAL.

Document NO_INSTALL_MANPAGES. Describe "The package phase".
Add section about "Cleaning up". Document DEPENDS_TARGET.
Document the bin-install target. Improve UPDATE_TARGET description.
Use &rprompt; and &cprompt; instead of <prompt>.</prompt>.
Document replace and index targets.

Reindent and break lines for 80 characters.

1 files changed, 847 insertions, 649 deletions

diff --git a/doc/guide/files/build.xml b/doc/guide/files/build.xml
index 31356416bdb..272c1a42255 100644
--- a/doc/guide/files/build.xml
+++ b/doc/guide/files/build.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: build.xml,v 1.34 2006/09/10 19:51:49 wiz Exp $ -->
+<!-- $NetBSD: build.xml,v 1.35 2006/09/13 23:23:00 wiz Exp $ -->
 
 <chapter id="build">
   <title>The build process</title>
@@ -37,7 +37,7 @@
     where all files of the final program shall be installed. It is
     usually set to <varname>LOCALBASE</varname>
     (<filename>/usr/pkg</filename>), or <varname>CROSSBASE</varname>
-    for pkgs in the <quote>cross</quote> category.  The value of
+    for pkgs in the <filename>cross</filename> category.  The value of
     <varname>PREFIX</varname> needs to be put
     into the various places in the program's source where paths to
     these files are encoded.  See <xref
@@ -49,16 +49,17 @@
 
     <itemizedlist>
       <listitem>
-	<para><varname>PREFIX</varname> always points to the location where the current
-	pkg will be installed.  When referring to a pkg's own installation path,
-	use <quote>${PREFIX}</quote>.</para>
+	<para><varname>PREFIX</varname> always points to the location
+	where the current pkg will be installed.  When referring to a
+	pkg's own installation path, use
+	<quote>${PREFIX}</quote>.</para>
       </listitem>
 
       <listitem>
-	<para><varname>LOCALBASE</varname> is where all non-X11 pkgs are installed.
-	If you need to construct a -I or -L argument to the compiler to find
-	includes and libraries installed by another non-X11 pkg, use
-	<quote>${LOCALBASE}</quote>. The name
+	<para><varname>LOCALBASE</varname> is where all non-X11 pkgs
+	are installed.  If you need to construct a -I or -L argument
+	to the compiler to find includes and libraries installed by
+	another non-X11 pkg, use <quote>${LOCALBASE}</quote>. The name
 	<varname>LOCALBASE</varname> stems from FreeBSD, which
 	installed all packages in <filename>/usr/local</filename>. As
 	pkgsrc leaves <filename>/usr/local</filename> for the system
@@ -66,21 +67,23 @@
       </listitem>
 
       <listitem>
-	<para><varname>X11BASE</varname> is where the actual X11 distribution (from
-	xsrc, etc.) is installed. When looking for
-	<emphasis>standard</emphasis> X11 includes (not
-	those installed by a pkg), use <quote>${X11BASE}</quote>.</para>
+	<para><varname>X11BASE</varname> is where the actual X11
+	distribution (from xsrc, etc.) is installed. When looking for
+	<emphasis>standard</emphasis> X11 includes (not those
+	installed by a package), use <quote>${X11BASE}</quote>.</para>
       </listitem>
 
       <listitem>
-	<para>X11-based packages are special in that they may be installed in
-	either <varname>X11BASE</varname> or <varname>LOCALBASE</varname>.</para>
+	<para>X11-based packages are special in that they may be
+	installed in either <varname>X11BASE</varname> or
+	<varname>LOCALBASE</varname>.</para>
 
 	<para>Usually, X11 packages should be installed under
-	<varname>LOCALBASE</varname> whenever possible.  Note that you will
-	need to include <filename>../../mk/x11.buildlink3.mk</filename>
-	in them to request the
-	presence of X11 and to get the right compilation flags.</para>
+	<varname>LOCALBASE</varname> whenever possible.  Note that you
+	will need to include
+	<filename>../../mk/x11.buildlink3.mk</filename> in them to
+	request the presence of X11 and to get the right compilation
+	flags.</para>
 
 	<para>Even though, there are some packages that cannot be installed
 	under <varname>LOCALBASE</varname>: those that come with app-defaults
@@ -101,21 +104,25 @@
       </listitem>
 
       <listitem>
-	<para><varname>X11PREFIX</varname> should be used to refer to the installed
-	location of an X11 package. <varname>X11PREFIX</varname> will be set to
-	<varname>X11BASE</varname> if xpkgwedge is not installed,
-	and to <varname>LOCALBASE</varname> if xpkgwedge is installed.</para>
+	<para><varname>X11PREFIX</varname> should be used to refer to
+	the installed location of an X11
+	package. <varname>X11PREFIX</varname> will be set to
+	<varname>X11BASE</varname> if xpkgwedge is not installed, and
+	to <varname>LOCALBASE</varname> if xpkgwedge is
+	installed.</para>
       </listitem>
 
       <listitem>
-	<para>If xpkgwedge is installed, it is possible to have some packages installed
-	in <varname>X11BASE</varname> and some in <varname>LOCALBASE</varname>.
-	To determine the prefix of an installed package, the
-	<varname>EVAL_PREFIX</varname> definition can be used. It takes pairs in the
-	format <quote>DIRNAME=&lt;package&gt;</quote>, and the &man.make.1; variable
-	<varname>DIRNAME</varname> will be set to the prefix of the installed
-	package &lt;package&gt;, or <quote>${X11PREFIX}</quote> if the package is
-	not installed.</para>
+	<para>If xpkgwedge is installed, it is possible to have some
+	packages installed in <varname>X11BASE</varname> and some in
+	<varname>LOCALBASE</varname>.  To determine the prefix of an
+	installed package, the <varname>EVAL_PREFIX</varname>
+	definition can be used. It takes pairs in the format
+	<quote>DIRNAME=&lt;package&gt;</quote>, and the &man.make.1;
+	variable <varname>DIRNAME</varname> will be set to the prefix
+	of the installed package &lt;package&gt;, or
+	<quote>${X11PREFIX}</quote> if the package is not
+	installed.</para>
 
 	<para>This is best illustrated by example.</para>
 
@@ -129,8 +136,9 @@
 	  CONFIGURE_ARGS+=        --enable-multibyte
 	</programlisting>
 
-	<para>Specific defaults can be defined for the packages evaluated using
-	<varname>EVAL_PREFIX</varname>, by using a definition of the form:</para>
+	<para>Specific defaults can be defined for the packages
+	evaluated using <varname>EVAL_PREFIX</varname>, by using a
+	definition of the form:</para>
 
 	<programlisting>
 	  GTKDIR_DEFAULT= ${LOCALBASE}
@@ -207,457 +215,520 @@
   <sect1 id="build.fetch">
     <title>The <emphasis>fetch</emphasis> phase</title>
 
-	<para>The first step in building a package is to fetch the
-	distribution files (distfiles) from the sites that are providing
-	them. This is the task of the <emphasis>fetch</emphasis>
-	phase.</para>
-
-<sect2 id="build.fetch.what">
-<title>What to fetch and where to get it from</title>
-
-	<para>In simple cases, <varname>MASTER_SITES</varname> defines
-	all URLs from where the distfile, whose name is derived from the
-	<varname>DISTNAME</varname> variable, is fetched. The more
-	complicated cases are described below.</para>
-
-	<para>The variable <varname>DISTFILES</varname> specifies the
-	list of distfiles that have to be fetched. Its value defaults to
-	<literal>${DISTNAME}${EXTRACT_SUFX}</literal>, so that most
-	packages don't need to define it at all.
-	<varname>EXTRACT_SUFX</varname> is <literal>.tar.gz</literal> by
-	default, but can be changed freely. Note that if your package
-	requires additional distfiles to the default one, you cannot
-	just append the additional filenames using the
-	<literal>+=</literal> operator, but you have write for
-	example:</para>
-
-<programlisting>
-    DISTFILES=      ${DISTNAME}${EXTRACT_SUFX} additional-files.tar.gz
-</programlisting>
-
-	<para>Each of the distfiles is fetched from a list of sites,
-	usually <varname>MASTER_SITES</varname>. If the package has
-	multiple <varname>DISTFILES</varname> or multiple
-	<varname>PATCHFILES</varname> from different sites, you can set
-	<varname>SITES.<replaceable>distfile</replaceable></varname> to
-	the list of URLs where the file
-	<filename><replaceable>distfile</replaceable></filename>
-	(including the suffix) can be found.</para>
-
-<programlisting>
-    DISTFILES=      ${DISTNAME}${EXTRACT_SUFX}
-    DISTFILES+=     foo-file.tar.gz
-    SITES.foo-file.tar.gz= \
-            http://www.somewhere.com/somehow/ \
-            http://www.somewhereelse.com/mirror/somehow/
-</programlisting>
-
-	<para>When actually fetching the distfiles, each item from
-	<varname>MASTER_SITES</varname> or <varname>SITES.*</varname>
-	gets the name of each distfile appended to it, without an
-	intermediate slash. Therefore, all site values have to end with
-	a slash or other separator character. This allows for example to
-	set <varname>MASTER_SITES</varname> to a URL of a CGI script
-	that gets the name of the distfile as a parameter. In this case,
-	the definition would look like:</para>
-
-<programlisting>
-    MASTER_SITES=   http://www.example.com/download.cgi?file=
-</programlisting>
-
-	<para>There are some predefined values for
-	<varname>MASTER_SITES</varname>, which can be used in packages.
-	The names of the variables should speak for themselves.</para>
-
-<!-- sort mk/fetch/sites.mk | sed -n 's/\(^MA[A-Z_]*\).*/    ${\1}/p' -->
-<programlisting>
-    ${MASTER_SITE_APACHE}
-    ${MASTER_SITE_BACKUP}
-    ${MASTER_SITE_CYGWIN}
-    ${MASTER_SITE_DEBIAN}
-    ${MASTER_SITE_FREEBSD}
-    ${MASTER_SITE_FREEBSD_LOCAL}
-    ${MASTER_SITE_GNOME}
-    ${MASTER_SITE_GNU}
-    ${MASTER_SITE_GNUSTEP}
-    ${MASTER_SITE_IFARCHIVE}
-    ${MASTER_SITE_KDE}
-    ${MASTER_SITE_MOZILLA}
-    ${MASTER_SITE_MYSQL}
-    ${MASTER_SITE_OPENOFFICE}
-    ${MASTER_SITE_PERL_CPAN}
-    ${MASTER_SITE_PGSQL}
-    ${MASTER_SITE_R_CRAN}
-    ${MASTER_SITE_SOURCEFORGE}
-    ${MASTER_SITE_SOURCEFORGE_JP}
-    ${MASTER_SITE_SUNSITE}
-    ${MASTER_SITE_SUSE}
-    ${MASTER_SITE_TEX_CTAN}
-    ${MASTER_SITE_XCONTRIB}
-    ${MASTER_SITE_XEMACS}
-</programlisting>
-
-	<para>If you choose one of these predefined sites, you may want
-	to specify a subdirectory of that site. Since these macros may
-	expand to more than one actual site, you
-	<emphasis>must</emphasis> use the following construct to specify
-	a subdirectory:</para>
-
-<programlisting>
-    MASTER_SITES=   ${MASTER_SITE_GNU:=subdirectory/name/}
-    MASTER_SITES=   ${MASTER_SITE_SOURCEFORGE:=project_name/}
-</programlisting>
-
-	<para>Note the trailing slash after the subdirectory
-	name.</para>
-
-</sect2>
-<sect2 id="build.fetch.how">
-<title>How are the files fetched?</title>
-
-	<para>The <emphasis>fetch</emphasis> phase makes sure that all
-	the distfiles exist in a local directory
-	(<varname>DISTDIR</varname>), which can be set by the pkgsrc
-	user). If the files do not exist, they are fetched using
-	commands of the form
-
-<programlisting>
-    ${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS}
-</programlisting>
-
-	where <literal>${site}</literal> varies through several
-	possibilities in turn: first,
-	<varname>MASTER_SITE_OVERRIDE</varname> is tried, then the sites
-	specified in either <varname>SITES.file</varname> if defined,
-	else <varname>MASTER_SITES</varname> or
-	<varname>PATCH_SITES</varname>, as applies, then finally the
-	value of <varname>MASTER_SITE_BACKUP</varname>. The order of all
-	except the first can be optionally sorted by the user, via
-	setting either <varname>MASTER_SORT_AWK</varname> or
-	<varname>MASTER_SORT_REGEX</varname>.</para>
-
-</sect2>
-</sect1>
-
-<sect1 id="build.checksum">
-<title>The <emphasis>checksum</emphasis> phase</title>
-
-	  <para>After the distfile(s) are fetched, their checksum is generated and
-	    compared with the checksums stored in the distinfo file. If the
-	    checksums don't match, the build is aborted. This is to ensure the same
-	    distfile is used for building, and that the distfile wasn't changed,
-	    e.g. by some malign force, deliberately changed distfiles on the master
-	    distribution site or network lossage.</para>
-
-</sect1>
-
-<sect1 id="build.extract">
-<title>The <emphasis>extract</emphasis> phase</title>
-
-	<para>When the distfiles are present on the local system, they
-	need to be extracted, as they usually come in the form of some
-	compressed archive format.</para>
-
-	<para>By default, all <varname>DISTFILES</varname> are
-	extracted. If you only need some of them, you can set the
-	<varname>EXTRACT_ONLY</varname> variable to the list of those
-	files.</para>
-
-	<para>Extracting the files is usually done by a little program,
-	<filename>mk/scripts/extract</filename>, which already knows how
-	to extract various archive formats, so most likely you will not
-	need to change anything here. But if you need, the following
-	variables may help you:</para>
-
-	<variablelist>
-
-	<varlistentry><term><varname>EXTRACT_OPTS_{BIN,LHA,PAX,RAR,TAR,ZIP,ZOO}</varname></term>
-	<listitem><para>Use these variables to override the default
-	options for an extract command, which are defined in
-	<filename>mk/scripts/extract</filename>.</para></listitem></varlistentry>
-
-	<varlistentry><term><varname>EXTRACT_USING</varname></term>
-	<listitem><para>This variable can be set to
-	<literal>pax</literal>, <literal>tar</literal> or an absolute
-	pathname pointing to the command with which tar archives should
-	be extracted.</para></listitem></varlistentry>
-
-	</variablelist>
-
-	<para>If the <filename>extract</filename> program doesn't serve
-	your needs, you can also override the
-	<varname>EXTRACT_CMD</varname> variable, which holds the command
-	used for extracting the files. This command is executed in the
-	<filename>${WRKSRC}</filename> directory. During execution of
-	this command, the shell variable <varname>extract_file</varname>
-	holds the absolute pathname of the file that is going to be
-	extracted.</para>
-
-	<para>And if that still does not suffice, you can override the
-	<varname>do-extract</varname> target in the package
-	Makefile.</para>
-
-
-</sect1>
-
-<sect1 id="build.patch">
-<title>The <emphasis>patch</emphasis> phase</title>
-
-	  <para>After extraction, all the patches named by the
-	    <varname>PATCHFILES</varname>, those present in the patches
-	    subdirectory of the package as well as in $LOCALPATCHES/$PKGPATH (e.g.
-	    <filename>/usr/local/patches/graphics/png</filename>) are applied.
-	    Patchfiles ending in <filename>.Z</filename> or
-	    <filename>.gz</filename> are uncompressed before they are applied,
-	    files ending in <filename>.orig</filename> or
-	    <filename>.rej</filename> are ignored. Any special options to &man.patch.1;
-	    can be handed in <varname>PATCH_DIST_ARGS</varname>.
-	    See <xref linkend="components.patches"/> for more details.</para>
-
-	  <para>By default &man.patch.1; is given special args to make it fail if the
-	    patches apply with some lines of fuzz. Please fix (regen) the patches
-	    so that they apply cleanly. The rationale behind this is that
-	    patches that don't apply cleanly may end up being applied in the wrong
-	    place, and cause severe harm there.</para>
-
-</sect1>
-
-<sect1 id="build.tools">
-<title>The <emphasis>tools</emphasis> phase</title>
-
-<para>This is covered in
-<xref linkend="tools"/>.
-</para>
-
-</sect1>
-
-<sect1 id="build.wrapper">
-<title>The <emphasis>wrapper</emphasis> phase</title>
-
-	<para>This phase creates wrapper programs for the compilers and
-	linkers. The following variables can be used to tweak the
-	wrappers.</para>
-
-	<variablelist>
-
-	<varlistentry><term><varname>ECHO_WRAPPER_MSG</varname></term>
-		<listitem><para>The command used to print progress
-		messages. Does nothing by default. Set to
-		<literal>${ECHO}</literal> to see the progress
-		messages.</para></listitem></varlistentry>
-
-	<varlistentry><term><varname>WRAPPER_DEBUG</varname></term>
-		<listitem><para>This variable can be set to
-		<literal>yes</literal> (default) or
-		<literal>no</literal>, depending on whether you want
-		additional information in the wrapper log
-		file.</para></listitem></varlistentry>
-
-	<varlistentry><term><varname>WRAPPER_UPDATE_CACHE</varname></term>
-		<listitem><para>This variable can be set to
-		<literal>yes</literal> or <literal>no</literal>,
-		depending on whether the wrapper should use its cache,
-		which will improve the speed. The default value is
-		<literal>yes</literal>, but is forced to
-		<literal>no</literal> if the platform does not support
-		it.</para></listitem></varlistentry>
-
-	<varlistentry><term><varname>WRAPPER_REORDER_CMDS</varname></term>
-
-		<listitem><para>A list of reordering commands. A
-		reordering command has the form
-		<literal>reorder:l:<replaceable>lib1</replaceable>:<replaceable>lib2</replaceable></literal>.
-		It ensures that that
-		<literal>-l<replaceable>lib1</replaceable></literal>
-		occurs before
-		<literal>-l<replaceable>lib2</replaceable></literal>.
-		</para></listitem></varlistentry>
-
-	<varlistentry><term><varname>WRAPPER_TRANSFORM_CMDS</varname></term>
-		<listitem><para>A list of transformation commands. [TODO:
-		investigate further]</para></listitem></varlistentry>
-
-<!-- These should probably be internal variables
-	<varlistentry><term><varname>WRAPPEES</varname></term>
-		<listitem><para></para></listitem></varlistentry>
-	<varlistentry><term><varname>UNWRAP_PATTERNS</varname></term>
-		<listitem><para></para></listitem></varlistentry>
-	<varlistentry><term><varname>UNWRAP_FILES</varname></term>
-		<listitem><para></para></listitem></varlistentry>
--->
-
-	</variablelist>
-</sect1>
-
-<sect1 id="build.configure">
-<title>The <emphasis>configure</emphasis> phase</title>
-
-<para>Most pieces of software need information on the header files,
-system calls, and library routines which are available on the platform
-they run on. The process of determining this information is known as
-configuration, and is usually automated. In most cases, a script is
-supplied with the distfiles, and its invocation results in generation of
-header files, Makefiles, etc.</para>
-
-<para>If the package contains a configure script, this can be invoked by
-setting <varname>HAS_CONFIGURE</varname> to <quote>yes</quote>. If the
-configure script is a GNU autoconf script, you should set
-<varname>GNU_CONFIGURE</varname> to <quote>yes</quote> instead. What
-happens in the <emphasis>configure</emphasis> phase is roughly:</para>
-
-<programlisting>
-    .for d in ${CONFIGURE_DIRS}
-            cd ${WRKSRC} &amp;&amp; cd ${d} &amp;&amp; env ${CONFIGURE_ENV} \
-                ${CONFIGURE_SCRIPT} ${CONFIGURE_ARGS}
-    .endfor
-</programlisting>
-
-<para><varname>CONFIGURE_DIRS</varname> (default: <quote>.</quote>) is a
-list of pathnames relative to <varname>WRKSRC</varname>. In each of
-these directories, the configure script is run with the environment
-<varname>CONFIGURE_ENV</varname> and arguments
-<varname>CONFIGURE_ARGS</varname>. The variables
-<varname>CONFIGURE_ENV</varname>, <varname>CONFIGURE_SCRIPT</varname>
-(default: <quote>./configure</quote>) and
-<varname>CONFIGURE_ARGS</varname> may all be changed by the
-package.</para>
-
-<para>If the program uses an <filename>Imakefile</filename> for
-configuration, the appropriate steps can be invoked by setting
-<varname>USE_IMAKE</varname> to <quote>yes</quote>. (If you only want
-the package installed in <varname>${X11PREFIX}</varname> but xmkmf not
-being run, set <varname>USE_X11BASE</varname> instead.)</para>
-
-</sect1>
-
-<sect1 id="build.build">
-<title>The <emphasis>build</emphasis> phase</title>
-
-<para>For building a package, a rough equivalent of the following code
-is executed.</para>
-
-<programlisting>
-    .for d in ${BUILD_DIRS}
-            cd ${WRKSRC} &amp;&amp; cd ${d} &amp;&amp; env ${MAKE_ENV} \
-                ${MAKE_PROGRAM} ${BUILD_MAKE_FLAGS} \
-                    -f ${MAKE_FILE} ${BUILD_TARGET}
-    .endfor
-</programlisting>
-
-<para><varname>BUILD_DIRS</varname> (default: <quote>.</quote>) is a
-list of pathnames relative to <varname>WRKSRC</varname>. In each of
-these directories, <varname>MAKE_PROGRAM</varname> is run with the
-environment <varname>MAKE_ENV</varname> and arguments
-<varname>BUILD_MAKE_FLAGS</varname>. The variables
-<varname>MAKE_ENV</varname>, <varname>BUILD_MAKE_FLAGS</varname>,
-<varname>MAKE_FILE</varname> and <varname>BUILD_TARGET</varname> may all
-be changed by the package.</para>
-
-<para>The default value of <varname>MAKE_PROGRAM</varname> is
-<quote>gmake</quote> if <varname>USE_TOOLS</varname> contains
-<quote>gmake</quote>, <quote>make</quote> otherwise. The default value
-of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
-<varname>BUILD_TARGET</varname> defaults to <quote>all</quote>.</para>
-
-</sect1>
-
-<sect1 id="build.test">
-<title>The <emphasis>test</emphasis> phase</title>
-
-<para>[TODO]</para>
-
-</sect1>
-
-<sect1 id="build.install">
-<title>The <emphasis>install</emphasis> phase</title>
-
-	<para>Once the build stage has completed, the final step is to
-	install the software in public directories, so users can access
-	the programs and files.</para>
-
-	<para>In the <emphasis>install</emphasis> phase, a rough
-	equivalent of the following code is executed. Additionally,
-	before and after this code, much magic is performed to do
-	consistency checks, registering the package, and so on.</para>
-
-<programlisting>
-    .for d in ${INSTALL_DIRS}
-            cd ${WRKSRC} &amp;&amp; cd ${d} &amp;&amp; env ${MAKE_ENV} \
-                ${MAKE_PROGRAM} ${INSTALL_MAKE_FLAGS} \
-                    -f ${MAKE_FILE} ${BUILD_TARGET}
-    .endfor
-</programlisting>
-
-	<para>The variable's meanings are analogous to the ones in the
-	<emphasis>build</emphasis> phase.
-	<varname>INSTALL_DIRS</varname> defaults to
-	<varname>BUILD_DIRS</varname>. <varname>INSTALL_TARGET</varname>
-	is <quote>install</quote> by default, plus
-	<quote>install.man</quote> if <varname>USE_IMAKE</varname> is
-	defined.</para>
-
-	<para>In the <emphasis>install</emphasis> phase, the following
-	variables are useful. They are all variations of the
-	&man.install.1; command that have the owner, group and
-	permissions preset. <varname>INSTALL</varname> is the plain
-	install command. The specialized variants, together with their
-	intended use, are:</para>
-
-	<variablelist>
-	<varlistentry><term><varname>INSTALL_PROGRAM_DIR</varname></term>
-		<listitem><para>directories that contain binaries</para></listitem></varlistentry>
-	<varlistentry><term><varname>INSTALL_SCRIPT_DIR</varname></term>
-		<listitem><para>directories that contain scripts</para></listitem></varlistentry>
-	<varlistentry><term><varname>INSTALL_LIB_DIR</varname></term>
-		<listitem><para>directories that contain shared and static libraries</para></listitem></varlistentry>
-	<varlistentry><term><varname>INSTALL_DATA_DIR</varname></term>
-		<listitem><para>directories that contain data files</para></listitem></varlistentry>
-	<varlistentry><term><varname>INSTALL_MAN_DIR</varname></term>
-		<listitem><para>directories that contain man pages</para></listitem></varlistentry>
-	<varlistentry><term><varname>INSTALL_PROGRAM</varname></term>
-		<listitem><para>binaries that can be stripped from debugging symbols</para></listitem></varlistentry>
-	<varlistentry><term><varname>INSTALL_SCRIPT</varname></term>
-		<listitem><para>binaries that cannot be stripped</para></listitem></varlistentry>
-	<varlistentry><term><varname>INSTALL_GAME</varname></term>
-		<listitem><para>game binaries</para></listitem></varlistentry>
-	<varlistentry><term><varname>INSTALL_LIB</varname></term>
-		<listitem><para>shared and static libraries</para></listitem></varlistentry>
-	<varlistentry><term><varname>INSTALL_DATA</varname></term>
-		<listitem><para>data files</para></listitem></varlistentry>
-	<varlistentry><term><varname>INSTALL_GAME_DATA</varname></term>
-		<listitem><para>data files for games</para></listitem></varlistentry>
-	<varlistentry><term><varname>INSTALL_MAN</varname></term>
-		<listitem><para>man pages</para></listitem></varlistentry>
-	</variablelist>
-
-	<para>Some other variables are:</para>
-
-	<variablelist>
-	<varlistentry><term><varname>INSTALLATION_DIRS</varname></term>
-
-		<listitem><para>A list of directories relative to
-		<varname>PREFIX</varname> that are created by pkgsrc at
-		the beginning of the <emphasis>install</emphasis> phase.
-		If this variable is set,
-		<varname>NO_MTREE</varname>=<quote>yes</quote> is
-		assumed, which means that the package claims to create
-		all needed directories itself before installing files to
-		it. Therefore this variable should only be set in
-		<filename>Makefile</filename>s that are under control of
-		the package's author. The directories are created with
-		the correct ownership, depending on their
-		name.</para></listitem></varlistentry>
-
-	</variablelist>
+    <para>The first step in building a package is to fetch the
+    distribution files (distfiles) from the sites that are providing
+    them. This is the task of the <emphasis>fetch</emphasis>
+    phase.</para>
+
+    <sect2 id="build.fetch.what">
+      <title>What to fetch and where to get it from</title>
+
+      <para>In simple cases, <varname>MASTER_SITES</varname>
+      defines all URLs from where the distfile, whose name is
+      derived from the <varname>DISTNAME</varname> variable, is
+      fetched. The more complicated cases are described
+      below.</para>
+
+      <para>The variable <varname>DISTFILES</varname> specifies
+      the list of distfiles that have to be fetched. Its value
+      defaults to <literal>${DISTNAME}${EXTRACT_SUFX}</literal>,
+      so that most packages don't need to define it at all.
+      <varname>EXTRACT_SUFX</varname> is
+      <literal>.tar.gz</literal> by default, but can be changed
+      freely. Note that if your package requires additional
+      distfiles to the default one, you cannot just append the
+      additional filenames using the <literal>+=</literal>
+      operator, but you have write for example:</para>
+
+      <programlisting>
+	DISTFILES=      ${DISTNAME}${EXTRACT_SUFX} additional-files.tar.gz
+      </programlisting>
+
+      <para>Each distfile is fetched from a list of sites, usually
+      <varname>MASTER_SITES</varname>. If the package has multiple
+      <varname>DISTFILES</varname> or multiple
+      <varname>PATCHFILES</varname> from different sites, you can
+      set
+      <varname>SITES.<replaceable>distfile</replaceable></varname>
+      to the list of URLs where the file
+      <filename><replaceable>distfile</replaceable></filename>
+      (including the suffix) can be found.</para>
+
+      <programlisting>
+	DISTFILES=      ${DISTNAME}${EXTRACT_SUFX}
+	DISTFILES+=     foo-file.tar.gz
+	SITES.foo-file.tar.gz= \
+	http://www.somewhere.com/somehow/ \
+	http://www.somewhereelse.com/mirror/somehow/
+      </programlisting>
+      
+      <para>When actually fetching the distfiles, each item from
+      <varname>MASTER_SITES</varname> or
+      <varname>SITES.*</varname> gets the name of each distfile
+      appended to it, without an intermediate slash. Therefore,
+      all site values have to end with a slash or other separator
+      character. This allows for example to set
+      <varname>MASTER_SITES</varname> to a URL of a CGI script
+      that gets the name of the distfile as a parameter. In this
+      case, the definition would look like:</para>
+
+      <programlisting>
+	MASTER_SITES=   http://www.example.com/download.cgi?file=
+      </programlisting>
+
+      <para>There are some predefined values for
+      <varname>MASTER_SITES</varname>, which can be used in
+      packages.  The names of the variables should speak for
+      themselves.</para>
+
+      <!-- sort mk/fetch/sites.mk | sed -n 's/\(^MA[A-Z_]*\).*/    ${\1}/p' -->
+
+      <programlisting>
+	${MASTER_SITE_APACHE}
+	${MASTER_SITE_BACKUP}
+	${MASTER_SITE_CYGWIN}
+	${MASTER_SITE_DEBIAN}
+	${MASTER_SITE_FREEBSD}
+	${MASTER_SITE_FREEBSD_LOCAL}
+	${MASTER_SITE_GNOME}
+	${MASTER_SITE_GNU}
+	${MASTER_SITE_GNUSTEP}
+	${MASTER_SITE_IFARCHIVE}
+	${MASTER_SITE_KDE}
+	${MASTER_SITE_MOZILLA}
+	${MASTER_SITE_MYSQL}
+	${MASTER_SITE_OPENOFFICE}
+	${MASTER_SITE_PERL_CPAN}
+	${MASTER_SITE_PGSQL}
+	${MASTER_SITE_R_CRAN}
+	${MASTER_SITE_SOURCEFORGE}
+	${MASTER_SITE_SOURCEFORGE_JP}
+	${MASTER_SITE_SUNSITE}
+	${MASTER_SITE_SUSE}
+	${MASTER_SITE_TEX_CTAN}
+	${MASTER_SITE_XCONTRIB}
+	${MASTER_SITE_XEMACS}
+      </programlisting>
+
+      <para>Some explanations for the less self-explaining ones:
+      <varname>MASTER_SITE_BACKUP</varname> contains backup sites
+      for packages that are maintained in <ulink
+      url="ftp://ftp.NetBSD.org:/pub/NetBSD/packages/distfiles/${DIST_SUBDIR}"
+      />.  <varname>MASTER_SITE_LOCAL</varname> contains local
+      package source distributions that are maintained in <ulink
+      url="ftp://ftp.NetBSD.org:/pub/NetBSD/packages/distfiles/LOCAL_PORTS/"
+      />.</para>
+
+      <para>If you choose one of these predefined sites, you may
+      want to specify a subdirectory of that site. Since these
+      macros may expand to more than one actual site, you
+      <emphasis>must</emphasis> use the following construct to
+      specify a subdirectory:</para>
+
+      <programlisting>
+	MASTER_SITES=   ${MASTER_SITE_GNU:=subdirectory/name/}
+	MASTER_SITES=   ${MASTER_SITE_SOURCEFORGE:=project_name/}
+      </programlisting>
+
+      <para>Note the trailing slash after the subdirectory
+      name.</para>
+
+    </sect2>
+    <sect2 id="build.fetch.how">
+      <title>How are the files fetched?</title>
+
+      <para>The <emphasis>fetch</emphasis> phase makes sure that
+      all the distfiles exist in a local directory
+      (<varname>DISTDIR</varname>), which can be set by the pkgsrc
+      user). If the files do not exist, they are fetched using
+      commands of the form</para>
+
+      <programlisting>
+	${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS}
+      </programlisting>
+
+      <para>where <literal>${site}</literal> varies through
+      several possibilities in turn: first,
+      <varname>MASTER_SITE_OVERRIDE</varname> is tried, then the
+      sites specified in either <varname>SITES.file</varname> if
+      defined, else <varname>MASTER_SITES</varname> or
+      <varname>PATCH_SITES</varname>, as applies, then finally the
+      value of <varname>MASTER_SITE_BACKUP</varname>. The order of
+      all except the first can be optionally sorted by the user,
+      via setting either <varname>MASTER_SORT_AWK</varname> or
+      <varname>MASTER_SORT_REGEX</varname>.</para>
+    </sect2>
 
+  </sect1>
+
+  <sect1 id="build.checksum">
+    <title>The <emphasis>checksum</emphasis> phase</title>
+
+    <para>After the distfile(s) are fetched, their checksum is
+    generated and compared with the checksums stored in the
+    distinfo file. If the checksums don't match, the build is
+    aborted. This is to ensure the same distfile is used for
+    building, and that the distfile wasn't changed, e.g. by some
+    malign force, deliberately changed distfiles on the master
+    distribution site or network lossage.</para>
+
+  </sect1>
+
+  <sect1 id="build.extract">
+    <title>The <emphasis>extract</emphasis> phase</title>
+
+    <para>When the distfiles are present on the local system, they
+    need to be extracted, as they usually come in the form of some
+    compressed archive format.</para>
+
+    <para>By default, all <varname>DISTFILES</varname> are
+    extracted. If you only need some of them, you can set the
+    <varname>EXTRACT_ONLY</varname> variable to the list of those
+    files.</para>
+
+    <para>Extracting the files is usually done by a little
+    program, <filename>mk/scripts/extract</filename>, which
+    already knows how to extract various archive formats, so most
+    likely you will not need to change anything here. But if you
+    need, the following variables may help you:</para>
+
+    <variablelist>
+
+      <varlistentry><term><varname>EXTRACT_OPTS_{BIN,LHA,PAX,RAR,TAR,ZIP,ZOO}</varname></term>
+      <listitem><para>Use these variables to override the default
+      options for an extract command, which are defined in
+      <filename>mk/scripts/extract</filename>.</para></listitem></varlistentry>
+
+      <varlistentry><term><varname>EXTRACT_USING</varname></term>
+      <listitem><para>This variable can be set to
+      <literal>pax</literal>, <literal>tar</literal> or an
+      absolute pathname pointing to the command with which tar
+      archives should be
+      extracted.</para></listitem></varlistentry>
+
+    </variablelist>
+
+    <para>If the <filename>extract</filename> program doesn't
+    serve your needs, you can also override the
+    <varname>EXTRACT_CMD</varname> variable, which holds the
+    command used for extracting the files. This command is
+    executed in the <filename>${WRKSRC}</filename>
+    directory. During execution of this command, the shell
+    variable <varname>extract_file</varname> holds the absolute
+    pathname of the file that is going to be extracted.</para>
+
+    <para>And if that still does not suffice, you can override the
+    <varname>do-extract</varname> target in the package
+    Makefile.</para>
+
+  </sect1>
+
+  <sect1 id="build.patch">
+    <title>The <emphasis>patch</emphasis> phase</title>
+
+    <para>After extraction, all the patches named by the
+    <varname>PATCHFILES</varname>, those present in the patches
+    subdirectory of the package as well as in
+    $LOCALPATCHES/$PKGPATH (e.g.
+    <filename>/usr/local/patches/graphics/png</filename>) are
+    applied.  Patchfiles ending in <filename>.Z</filename> or
+    <filename>.gz</filename> are uncompressed before they are
+    applied, files ending in <filename>.orig</filename> or
+    <filename>.rej</filename> are ignored. Any special options to
+    &man.patch.1; can be handed in
+    <varname>PATCH_DIST_ARGS</varname>.  See <xref
+    linkend="components.patches"/> for more details.</para>
+
+    <para>By default &man.patch.1; is given special args to make
+    it fail if the patches apply with some lines of fuzz. Please
+    fix (regen) the patches so that they apply cleanly. The
+    rationale behind this is that patches that don't apply cleanly
+    may end up being applied in the wrong place, and cause severe
+    harm there.</para>
 
   </sect1>
 
+  <sect1 id="build.tools">
+    <title>The <emphasis>tools</emphasis> phase</title>
+
+    <para>This is covered in <xref linkend="tools"/>.
+    </para>
+
+  </sect1>
+
+  <sect1 id="build.wrapper">
+    <title>The <emphasis>wrapper</emphasis> phase</title>
+
+    <para>This phase creates wrapper programs for the compilers and
+    linkers. The following variables can be used to tweak the
+    wrappers.</para>
+
+    <variablelist>
+
+      <varlistentry><term><varname>ECHO_WRAPPER_MSG</varname></term>
+      <listitem><para>The command used to print progress
+      messages. Does nothing by default. Set to
+      <literal>${ECHO}</literal> to see the progress
+      messages.</para></listitem></varlistentry>
+
+      <varlistentry><term><varname>WRAPPER_DEBUG</varname></term>
+      <listitem><para>This variable can be set to
+      <literal>yes</literal> (default) or <literal>no</literal>,
+      depending on whether you want additional information in the
+      wrapper log file.</para></listitem></varlistentry>
+
+      <varlistentry><term><varname>WRAPPER_UPDATE_CACHE</varname></term>
+      <listitem><para>This variable can be set to
+      <literal>yes</literal> or <literal>no</literal>, depending
+      on whether the wrapper should use its cache, which will
+      improve the speed. The default value is
+      <literal>yes</literal>, but is forced to
+      <literal>no</literal> if the platform does not support
+      it.</para></listitem></varlistentry>
+
+      <varlistentry><term><varname>WRAPPER_REORDER_CMDS</varname></term>
+
+      <listitem><para>A list of reordering commands. A reordering
+      command has the form
+      <literal>reorder:l:<replaceable>lib1</replaceable>:<replaceable>lib2</replaceable></literal>.
+      It ensures that that
+      <literal>-l<replaceable>lib1</replaceable></literal> occurs
+      before <literal>-l<replaceable>lib2</replaceable></literal>.
+      </para></listitem></varlistentry>
+
+      <varlistentry><term><varname>WRAPPER_TRANSFORM_CMDS</varname></term>
+      <listitem><para>A list of transformation commands. [TODO:
+      investigate further]</para></listitem></varlistentry>
+
+      <!-- These should probably be internal variables
+	   <varlistentry><term><varname>WRAPPEES</varname></term>
+	   <listitem><para></para></listitem></varlistentry>
+	   <varlistentry><term><varname>UNWRAP_PATTERNS</varname></term>
+	   <listitem><para></para></listitem></varlistentry>
+	   <varlistentry><term><varname>UNWRAP_FILES</varname></term>
+	   <listitem><para></para></listitem></varlistentry>
+      -->
+
+    </variablelist>
+  </sect1>
+
+  <sect1 id="build.configure">
+    <title>The <emphasis>configure</emphasis> phase</title>
+
+    <para>Most pieces of software need information on the header
+    files, system calls, and library routines which are available
+    on the platform they run on. The process of determining this
+    information is known as configuration, and is usually
+    automated. In most cases, a script is supplied with the
+    distfiles, and its invocation results in generation of header
+    files, Makefiles, etc.</para>
+
+    <para>If the package contains a configure script, this can be
+    invoked by setting <varname>HAS_CONFIGURE</varname> to
+    <quote>yes</quote>. If the configure script is a GNU autoconf
+    script, you should set <varname>GNU_CONFIGURE</varname> to
+    <quote>yes</quote> instead. What happens in the
+    <emphasis>configure</emphasis> phase is roughly:</para>
+
+    <programlisting>
+      .for d in ${CONFIGURE_DIRS}
+      cd ${WRKSRC} &amp;&amp; cd ${d} &amp;&amp; env ${CONFIGURE_ENV} \
+      ${CONFIGURE_SCRIPT} ${CONFIGURE_ARGS}
+      .endfor
+    </programlisting>
+
+    <para><varname>CONFIGURE_DIRS</varname> (default:
+    <quote>.</quote>) is a list of pathnames relative to
+    <varname>WRKSRC</varname>. In each of these directories, the
+    configure script is run with the environment
+    <varname>CONFIGURE_ENV</varname> and arguments
+    <varname>CONFIGURE_ARGS</varname>. The variables
+    <varname>CONFIGURE_ENV</varname>,
+    <varname>CONFIGURE_SCRIPT</varname> (default:
+    <quote>./configure</quote>) and
+    <varname>CONFIGURE_ARGS</varname> may all be changed by the
+    package.</para>
+
+    <para>If the program uses an <filename>Imakefile</filename>
+    for configuration, the appropriate steps can be invoked by
+    setting <varname>USE_IMAKE</varname> to
+    <quote>yes</quote>. (If you only want the package installed in
+    <varname>${X11PREFIX}</varname> but xmkmf not being run, set
+    <varname>USE_X11BASE</varname> instead.)</para>
+
+  </sect1>
+
+  <sect1 id="build.build">
+    <title>The <emphasis>build</emphasis> phase</title>
+
+    <para>For building a package, a rough equivalent of the
+    following code is executed.</para>
+
+    <programlisting>
+      .for d in ${BUILD_DIRS}
+      cd ${WRKSRC} &amp;&amp; cd ${d} &amp;&amp; env ${MAKE_ENV} \
+      ${MAKE_PROGRAM} ${BUILD_MAKE_FLAGS} \
+      -f ${MAKE_FILE} ${BUILD_TARGET}
+      .endfor
+    </programlisting>
+
+    <para><varname>BUILD_DIRS</varname> (default:
+    <quote>.</quote>) is a list of pathnames relative to
+    <varname>WRKSRC</varname>. In each of these directories,
+    <varname>MAKE_PROGRAM</varname> is run with the environment
+    <varname>MAKE_ENV</varname> and arguments
+    <varname>BUILD_MAKE_FLAGS</varname>. The variables
+    <varname>MAKE_ENV</varname>,
+    <varname>BUILD_MAKE_FLAGS</varname>,
+    <varname>MAKE_FILE</varname> and
+    <varname>BUILD_TARGET</varname> may all be changed by the
+    package.</para>
+
+    <para>The default value of <varname>MAKE_PROGRAM</varname> is
+    <quote>gmake</quote> if <varname>USE_TOOLS</varname> contains
+    <quote>gmake</quote>, <quote>make</quote> otherwise. The
+    default value of <varname>MAKE_FILE</varname> is
+    <quote>Makefile</quote>, and <varname>BUILD_TARGET</varname>
+    defaults to <quote>all</quote>.</para>
+
+  </sect1>
+
+  <sect1 id="build.test">
+    <title>The <emphasis>test</emphasis> phase</title>
+
+    <para>[TODO]</para>
+
+  </sect1>
+
+  <sect1 id="build.install">
+    <title>The <emphasis>install</emphasis> phase</title>
+
+    <para>Once the build stage has completed, the final step is to
+    install the software in public directories, so users can
+    access the programs and files.</para>
+
+    <para>In the <emphasis>install</emphasis> phase, a rough
+    equivalent of the following code is executed. Additionally,
+    before and after this code, much magic is performed to do
+    consistency checks, registering the package, and so on.</para>
+
+    <programlisting>
+      .for d in ${INSTALL_DIRS}
+      cd ${WRKSRC} &amp;&amp; cd ${d} &amp;&amp; env ${MAKE_ENV} \
+      ${MAKE_PROGRAM} ${INSTALL_MAKE_FLAGS} \
+      -f ${MAKE_FILE} ${BUILD_TARGET}
+      .endfor
+    </programlisting>
+
+    <para>The variable's meanings are analogous to the ones in the
+    <emphasis>build</emphasis> phase.
+    <varname>INSTALL_DIRS</varname> defaults to
+    <varname>BUILD_DIRS</varname>. <varname>INSTALL_TARGET</varname>
+    is <quote>install</quote> by default, plus
+    <quote>install.man</quote> if <varname>USE_IMAKE</varname> is
+    defined and <varname>NO_INSTALL_MANPAGES</varname> is not
+    defined.</para>
+
+    <para>In the <emphasis>install</emphasis> phase, the following
+    variables are useful. They are all variations of the
+    &man.install.1; command that have the owner, group and
+    permissions preset. <varname>INSTALL</varname> is the plain
+    install command. The specialized variants, together with their
+    intended use, are:</para>
+
+    <variablelist>
+      <varlistentry><term><varname>INSTALL_PROGRAM_DIR</varname></term>
+      <listitem><para>directories that contain
+      binaries</para></listitem></varlistentry>
+
+      <varlistentry><term><varname>INSTALL_SCRIPT_DIR</varname></term>
+      <listitem><para>directories that contain
+      scripts</para></listitem></varlistentry>
+
+      <varlistentry><term><varname>INSTALL_LIB_DIR</varname></term>
+      <listitem><para>directories that contain shared and static
+      libraries</para></listitem></varlistentry>
+
+      <varlistentry><term><varname>INSTALL_DATA_DIR</varname></term>
+      <listitem><para>directories that contain data
+      files</para></listitem></varlistentry>
+
+      <varlistentry><term><varname>INSTALL_MAN_DIR</varname></term>
+      <listitem><para>directories that contain man
+      pages</para></listitem></varlistentry>
+      
+      <varlistentry><term><varname>INSTALL_PROGRAM</varname></term>
+      <listitem><para>binaries that can be stripped from debugging
+      symbols</para></listitem></varlistentry>
+      
+      <varlistentry><term><varname>INSTALL_SCRIPT</varname></term>
+      <listitem><para>binaries that cannot be
+      stripped</para></listitem></varlistentry>
+      
+      <varlistentry><term><varname>INSTALL_GAME</varname></term>
+      <listitem><para>game
+      binaries</para></listitem></varlistentry>
+      
+      <varlistentry><term><varname>INSTALL_LIB</varname></term>
+      <listitem><para>shared and static
+      libraries</para></listitem></varlistentry>
+      
+      <varlistentry><term><varname>INSTALL_DATA</varname></term>
+      <listitem><para>data files</para></listitem></varlistentry>
+      
+      <varlistentry><term><varname>INSTALL_GAME_DATA</varname></term>
+      <listitem><para>data files for
+      games</para></listitem></varlistentry>
+
+      <varlistentry><term><varname>INSTALL_MAN</varname></term>
+      <listitem><para>man pages</para></listitem></varlistentry>
+    </variablelist>
+
+    <para>Some other variables are:</para>
+
+    <variablelist>
+      <varlistentry><term><varname>INSTALLATION_DIRS</varname></term>
+
+      <listitem><para>A list of directories relative to
+      <varname>PREFIX</varname> that are created by pkgsrc at the
+      beginning of the <emphasis>install</emphasis> phase.  If
+      this variable is set,
+      <varname>NO_MTREE</varname>=<quote>yes</quote> is assumed,
+      which means that the package claims to create all needed
+      directories itself before installing files to it. Therefore
+      this variable should only be set in
+      <filename>Makefile</filename>s that are under control of the
+      package's author. The directories are created with the
+      correct ownership, depending on their
+      name.</para></listitem></varlistentry>
+
+    </variablelist>
+  </sect1>
+
   <sect1 id="build.package">
     <title>The <emphasis>package</emphasis> phase</title>
 
-    <para>[TODO]</para>
+    <para>Once the install stage has completed, a binary package of
+    the installed files can be built.  These binary packages can be
+    used for quick installation without previous compilation, e.g. by
+    the <command>make bin-install</command> or by using
+    <command>pkg_add</command>.</para>
+
+    <para>By default, the binary packages are created in
+    <filename>${PACKAGES}/All</filename> and symlinks are created in
+    <filename>${PACKAGES}/<replaceable>category</replaceable></filename>,
+    one for each category in the <varname>CATEGORIES</varname>
+    variable.  <varname>PACKAGES</varname> defaults to
+    <filename>pkgsrc/packages</filename>.</para>
+  </sect1>
+
+  <sect1 id="build.clean">
+    <title>Cleaning up</title>
 
+    <para>Once you're finished with a package, you can clean the work
+    directory by running <command>make clean</command>.  If you want
+    to clean the work directories of all dependencies too, use
+    <command>make clean-depends</command>.</para>
   </sect1>
 
   <sect1 id="build.helpful-targets">
@@ -668,14 +739,15 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	<term>pre/post-*</term>
 
 	<listitem>
-	  <para>For any of the main targets described in the previous
-	  section, two auxiliary targets exist with
+	  <para>For any of the main targets described in the
+	  previous section, two auxiliary targets exist with
 	  <quote>pre-</quote> and <quote>post-</quote> used as a
 	  prefix for the main target's name.  These targets are
-	  invoked before and after the main target is called, allowing
-	  extra configuration or installation steps be performed from
-	  a package's Makefile, for example, which a program's
-	  configure script or install target omitted.</para>
+	  invoked before and after the main target is called,
+	  allowing extra configuration or installation steps be
+	  performed from a package's Makefile, for example, which
+	  a program's configure script or install target
+	  omitted.</para>
 	</listitem>
       </varlistentry>
 
@@ -683,12 +755,13 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	<term>do-*</term>
 
 	<listitem>
-	  <para>Should one of the main targets do the wrong thing, and
-	  should there be no variable to fix this, you can redefine it
-	  with the do-* target.  (Note that redefining the target
-	  itself instead of the do-* target is a bad idea, as the
-	  pre-* and post-* targets won't be called anymore, etc.) You
-	  will not usually need to do this.</para>
+	  <para>Should one of the main targets do the wrong thing,
+	  and should there be no variable to fix this, you can
+	  redefine it with the do-* target.  (Note that redefining
+	  the target itself instead of the do-* target is a bad
+	  idea, as the pre-* and post-* targets won't be called
+	  anymore, etc.) You will not usually need to do
+	  this.</para>
 	</listitem>
       </varlistentry>
 
@@ -696,10 +769,17 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	<term>reinstall</term>
 
 	<listitem>
-	  <para>If you did a <command>make install</command> and you
-	  noticed some file was not installed properly, you can repeat
-	  the installation with this target, which will ignore the
-	  <quote>already installed</quote> flag.</para>
+	  <para>If you did a <command>make install</command> and
+	  you noticed some file was not installed properly, you
+	  can repeat the installation with this target, which will
+	  ignore the <quote>already installed</quote> flag.</para>
+
+	  <para>This is the default value of
+	  <varname>DEPENDS_TARGET</varname> except in the case of
+	  <command>make update</command> and <command>make
+	  package</command>, where the defaults are
+	  <quote>package</quote> and <quote>update</quote>,
+	  respectively.</para>
 	</listitem>
       </varlistentry>
 
@@ -707,9 +787,10 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	<term>deinstall</term>
 
 	<listitem>
-	  <para>This target does a &man.pkg.delete.1; in the current directory,
-	  effectively de-installing the package. The following variables can
-	  be used to tune the behaviour:</para>
+	  <para>This target does a &man.pkg.delete.1; in the
+	  current directory, effectively de-installing the
+	  package. The following variables can be used to tune the
+	  behaviour:</para>
 
 	  <variablelist>
 	    <varlistentry>
@@ -724,12 +805,15 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	      <term><varname>DEINSTALLDEPENDS</varname></term>
 
 	      <listitem>
-		<para>Remove all packages that require (depend on) the given package.
-		This can be used to remove any packages that may have been pulled in
-		by a given package, e.g. if <command>make deinstall
+		<para>Remove all packages that require (depend on)
+		the given package.  This can be used to remove any
+		packages that may have been pulled in by a given
+		package, e.g. if <command>make deinstall
 		DEINSTALLDEPENDS=1</command> is done in
-		<filename>pkgsrc/x11/kde</filename>, this is likely to remove whole
-		KDE. Works by adding <quote>-R</quote> to the &man.pkg.delete.1; command line.</para>
+		<filename>pkgsrc/x11/kde</filename>, this is
+		likely to remove whole KDE. Works by adding
+		<quote>-R</quote> to the &man.pkg.delete.1;
+		command line.</para>
 	      </listitem>
 	    </varlistentry>
 	  </variablelist>
@@ -737,43 +821,71 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
       </varlistentry>
 
       <varlistentry>
+	<term>bin-install</term>
+
+	<listitem>
+	  <para>Install a binary package from local disk and via FTP
+	  from a list of sites (see the
+	  <varname>BINPKG_SITES</varname> variable), and do a
+	  <command>make package</command> if no binary package is
+	  available anywhere.  The arguments given to
+	  <command>pkg_add</command> can be set via
+	  <varname>BIN_INSTALL_FLAGS</varname> e.g., to do verbose
+	  operation, etc.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
 	<term>update</term>
 
 	<listitem>
-	  <para>This target causes the current package to be updated to the latest
-	  version.  The package and all depending packages first get de-installed,
-	  then current versions of the corresponding packages get compiled and
-	  installed.  This is similar to manually noting which packages are
-	  currently installed, then performing a series of <command>make
-	  deinstall</command> and <command>make install</command> (or whatever
-	  <varname>UPDATE_TARGET</varname> is set to) for these packages.</para>
-
-	  <para>You can use the <quote>update</quote> target to resume package
-	  updating in case a previous <command>make update</command> was interrupted
-	  for some reason.  However, in this case, make sure you don't call
-	  <command>make clean</command> or otherwise remove the list of dependent
-	  packages in <varname>WRKDIR</varname>.  Otherwise, you lose the
-	  ability to automatically update the current package along with the
-	  dependent packages you have installed.</para>
-
-	  <para>Resuming an interrupted <command>make update</command> will only work as
-	  long as the package tree remains unchanged.  If the source code for
-	  one of the packages to be updated has been changed, resuming
-	  <command>make update</command> will most certainly fail!</para>
-
-	  <para>The following variables can be used either on the command line or in
-	  <filename>/etc/mk.conf</filename> to alter the behaviour of
-	  <command>make update</command>:</para>
+	  <para>This target causes the current package to be
+	  updated to the latest version.  The package and all
+	  depending packages first get de-installed, then current
+	  versions of the corresponding packages get compiled and
+	  installed.  This is similar to manually noting which
+	  packages are currently installed, then performing a
+	  series of <command>make deinstall</command> and
+	  <command>make install</command> (or whatever
+	  <varname>UPDATE_TARGET</varname> is set to) for these
+	  packages.</para>
+
+	  <para>You can use the <quote>update</quote> target to
+	  resume package updating in case a previous <command>make
+	  update</command> was interrupted for some reason.
+	  However, in this case, make sure you don't call
+	  <command>make clean</command> or otherwise remove the
+	  list of dependent packages in <varname>WRKDIR</varname>.
+	  Otherwise, you lose the ability to automatically update
+	  the current package along with the dependent packages
+	  you have installed.</para>
+
+	  <para>Resuming an interrupted <command>make
+	  update</command> will only work as long as the package
+	  tree remains unchanged.  If the source code for one of
+	  the packages to be updated has been changed, resuming
+	  <command>make update</command> will most certainly
+	  fail!</para>
+
+	  <para>The following variables can be used either on the
+	  command line or in <filename>/etc/mk.conf</filename> to
+	  alter the behaviour of <command>make
+	  update</command>:</para>
 
 	  <variablelist>
 	    <varlistentry>
 	      <term><varname>UPDATE_TARGET</varname></term>
 
 	      <listitem>
-		<para>Install target to recursively use for the updated package and the
-		dependent packages.  Defaults to <varname>DEPENDS_TARGET</varname> if set,
-		<quote>install</quote> otherwise for <command>make update</command>.
-		e.g. <command>make update UPDATE_TARGET=package</command></para>
+		<para>Install target to recursively use for the
+		updated package and the dependent packages.
+		Defaults to <varname>DEPENDS_TARGET</varname> if
+		set, <quote>install</quote> otherwise for
+		<command>make update</command>.  Other good
+		targets are <quote>package</quote> or
+		<quote>bin-install</quote>.  Do not set this to
+		<quote>update</quote> or you will get stuck in an
+		endless loop!</para>
 	      </listitem>
 	    </varlistentry>
 
@@ -781,12 +893,15 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	      <term><varname>NOCLEAN</varname></term>
 
 	      <listitem>
-		<para>Don't clean up after updating.  Useful if you want to leave the
-		work sources of the updated packages around for inspection or
-		other purposes.  Be sure you eventually clean up the source
-		tree (see the <quote>clean-update</quote> target below) or you may
-		run into troubles with old source code still lying around on your
-		next <command>make</command> or <command>make update</command>.</para>
+		<para>Don't clean up after updating.  Useful if
+		you want to leave the work sources of the updated
+		packages around for inspection or other purposes.
+		Be sure you eventually clean up the source tree
+		(see the <quote>clean-update</quote> target below)
+		or you may run into troubles with old source code
+		still lying around on your next
+		<command>make</command> or <command>make
+		update</command>.</para>
 	      </listitem>
 	    </varlistentry>
 
@@ -794,10 +909,12 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	      <term><varname>REINSTALL</varname></term>
 
 	      <listitem>
-		<para>Deinstall each package before installing (making
-		<varname>DEPENDS_TARGET</varname>). This may be necessary if the
-		<quote>clean-update</quote> target (see below) was called after
-		interrupting a running <command>make update</command>.</para>
+		<para>Deinstall each package before installing
+		(making <varname>DEPENDS_TARGET</varname>). This
+		may be necessary if the
+		<quote>clean-update</quote> target (see below) was
+		called after interrupting a running <command>make
+		update</command>.</para>
 	      </listitem>
 	    </varlistentry>
 
@@ -805,13 +922,17 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	      <term><varname>DEPENDS_TARGET</varname></term>
 
 	      <listitem>
-		<para>Allows you to disable recursion and hardcode the target for
-		packages.  The default is <quote>update</quote> for the update target,
-		facilitating a recursive update of prerequisite packages.
-		Only set <varname>DEPENDS_TARGET</varname> if you want to disable
-		recursive updates. Use <varname>UPDATE_TARGET</varname> instead to just
-		set a specific target for each package to be installed during
-		<command>make update</command> (see above).</para>
+		<para>Allows you to disable recursion and hardcode
+		the target for packages.  The default is
+		<quote>update</quote> for the update target,
+		facilitating a recursive update of prerequisite
+		packages.  Only set
+		<varname>DEPENDS_TARGET</varname> if you want to
+		disable recursive updates. Use
+		<varname>UPDATE_TARGET</varname> instead to just
+		set a specific target for each package to be
+		installed during <command>make update</command>
+		(see above).</para>
 	      </listitem>
 	    </varlistentry>
 	  </variablelist>
@@ -822,44 +943,52 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	<term>clean-update</term>
 
 	<listitem>
-	  <para>Clean the source tree for all packages that would get updated if
-	  <command>make update</command> was called from the current directory.
-	  This target should not be used if the current package (or any of its
-	  depending packages) have already been de-installed (e.g., after calling
-	  <command>make update</command>) or you may lose some packages you intended
-	  to update. As a rule of thumb: only use this target
-	  <emphasis>before</emphasis> the first time you run
-	  <command>make update</command> and only if you have a dirty package tree
-	  (e.g., if you used <varname>NOCLEAN</varname>).</para>
-
-	  <para>If you are unsure about whether your tree is clean, you can either
-	  perform a <command>make clean</command> at the top of the tree, or use
-	  the following sequence of commands from the directory of the package
-	  you want to update (<emphasis>before</emphasis> running
-	  <command>make update</command> for the first time, otherwise you lose
-	  all the packages you wanted to update!):</para>
+	  <para>Clean the source tree for all packages that would
+	  get updated if <command>make update</command> was called
+	  from the current directory.  This target should not be
+	  used if the current package (or any of its depending
+	  packages) have already been de-installed (e.g., after
+	  calling <command>make update</command>) or you may lose
+	  some packages you intended to update. As a rule of
+	  thumb: only use this target <emphasis>before</emphasis>
+	  the first time you run <command>make update</command>
+	  and only if you have a dirty package tree (e.g., if you
+	  used <varname>NOCLEAN</varname>).</para>
+
+	  <para>If you are unsure about whether your tree is
+	  clean, you can either perform a <command>make
+	  clean</command> at the top of the tree, or use the
+	  following sequence of commands from the directory of the
+	  package you want to update (<emphasis>before</emphasis>
+	  running <command>make update</command> for the first
+	  time, otherwise you lose all the packages you wanted to
+	  update!):</para>
 
 	  <screen>
-<prompt>#</prompt> <userinput>make clean-update</userinput>
-<prompt>#</prompt> <userinput>make clean CLEANDEPENDS=YES</userinput>
-<prompt>#</prompt> <userinput>make update</userinput>
+&rprompt; <userinput>make clean-update</userinput>
+&rprompt; <userinput>make clean CLEANDEPENDS=YES</userinput>
+&rprompt; <userinput>make update</userinput>
 	  </screen>
 
-	  <para>The following variables can be used either on the command line or in
-	  <filename>/etc/mk.conf</filename> to alter the behaviour of
-	  <command>make clean-update</command>:</para>
+	  <para>The following variables can be used either on the
+	  command line or in <filename>/etc/mk.conf</filename> to
+	  alter the behaviour of <command>make
+	  clean-update</command>:</para>
 
 	  <variablelist>
 	    <varlistentry>
 	      <term><varname>CLEAR_DIRLIST</varname></term>
 
 	      <listitem>
-		<para>After <command>make clean</command>, do not reconstruct the list of
-		directories to update for this package.  Only use this if <command>make
-		update</command> successfully installed all packages you wanted to
-		update.  Normally, this is done automatically on <command>make
-		update</command>, but may have been suppressed by the
-		<varname>NOCLEAN</varname> variable (see above).</para>
+		<para>After <command>make clean</command>, do not
+		reconstruct the list of directories to update for
+		this package.  Only use this if <command>make
+		update</command> successfully installed all
+		packages you wanted to update.  Normally, this is
+		done automatically on <command>make
+		update</command>, but may have been suppressed by
+		the <varname>NOCLEAN</varname> variable (see
+		above).</para>
 	      </listitem>
 	    </varlistentry>
 	  </variablelist>
@@ -867,35 +996,88 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
       </varlistentry>
 
       <varlistentry>
+	<term>replace</term>
+
+	<listitem>
+	  <para>Update the installation of the current package.  This
+	  differs from update in that it does not replace dependent
+	  packages.  You will need to install <filename
+	  role="pkg">pkgsrc/pkgtools/pkg_tarup</filename> for this
+	  target to work.</para>
+
+	  <para><emphasis>Be careful when using this
+	  target!</emphasis> There are no guarantees that dependent
+	  packages will still work, in particular they will most
+	  certainly break if you <command>make replace</command> a
+	  library package whose shared library major version changed
+	  between your installed version and the new one.  For this
+	  reason, this target is not officially supported and only
+	  recommended for advanced users.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
 	<term>info</term>
 
 	<listitem>
 	  <para>This target invokes &man.pkg.info.1; for the current
-	  package. You can use this to check which version of a package is
-	  installed.</para>
+	  package. You can use this to check which version of a
+	  package is installed.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
+	<term>index</term>
+
+	<listitem>
+	  <para>This is a top-level command, i.e. it should be used in
+	  the <filename>pkgsrc</filename> directory.  It creates a
+	  database of all packages in the local pkgsrc tree, including
+	  dependencies, comment, maintainer, and some other useful
+	  information.  Individual entries are created by running
+	  <command>make describe</command> in the packages'
+	  directories.  This index file is saved as
+	  <filename>pkgsrc/INDEX</filename>.  It can be displayed in
+	  verbose format by running <command>make
+	  print-index</command>.  You can search in it with
+	  <command>make search
+	  key=<replaceable>something</replaceable></command>.  You can
+	  extract a list of all packages that depend on a particular
+	  one by running <command>make show-deps
+	  PKG=<replaceable>somepackage</replaceable></command>.</para>
+
+	  <para>Running this command takes a very long time, some
+	  hours even on fast machines!</para>
+	</listitem>
+      </varlistentry>
+
+
+      <varlistentry>
 	<term>readme</term>
 
 	<listitem>
-	  <para>This target generates a <filename>README.html</filename> file, which
-	    can be viewed using a browser such as
-	    <filename role="pkg">www/firefox</filename> or
-	    <filename role="pkg">www/links</filename>.
-	    The generated files contain references to any
-	    packages which are in the <varname>PACKAGES</varname> directory on
-	    the local host. The generated files can be made to refer to URLs based on
-	    <varname>FTP_PKG_URL_HOST</varname> and
-	    <varname>FTP_PKG_URL_DIR</varname>. For example, if I wanted to generate
-	    <filename>README.html</filename> files which pointed to binary packages
-	    on the local machine, in the directory
-	    <filename>/usr/packages</filename>, set
-	    <varname>FTP_PKG_URL_HOST=file://localhost</varname> and
-	    <varname>FTP_PKG_URL_DIR=/usr/packages</varname>. The
-	    <varname>${PACKAGES}</varname> directory and its subdirectories will be
-	    searched for all the binary packages.</para>
+	  <para>This target generates a
+	  <filename>README.html</filename> file, which can be
+	  viewed using a browser such as <filename
+	  role="pkg">www/firefox</filename> or <filename
+	  role="pkg">www/links</filename>.  The generated files
+	  contain references to any packages which are in the
+	  <varname>PACKAGES</varname> directory on the local
+	  host. The generated files can be made to refer to URLs
+	  based on <varname>FTP_PKG_URL_HOST</varname> and
+	  <varname>FTP_PKG_URL_DIR</varname>. For example, if I
+	  wanted to generate <filename>README.html</filename>
+	  files which pointed to binary packages on the local
+	  machine, in the directory
+	  <filename>/usr/packages</filename>, set
+	  <varname>FTP_PKG_URL_HOST=file://localhost</varname> and
+	  <varname>FTP_PKG_URL_DIR=/usr/packages</varname>. The
+	  <varname>${PACKAGES}</varname> directory and its
+	  subdirectories will be searched for all the binary
+	  packages.</para>
+
+	  <para>The target can be run at the toplevel or in category
+	  directories, in which case it descends recursively.</para>
 	</listitem>
       </varlistentry>
 
@@ -903,12 +1085,15 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	<term>readme-all</term>
 
 	<listitem>
-	  <para>Use this target to create a file <filename>README-all.html</filename>
-	  which contains a list of all packages currently available in the &os;
-	  Packages Collection, together with the category they belong to and a
-	  short description. This file is compiled from the
-	  <filename>pkgsrc/*/README.html</filename> files, so be sure to run
-	  this <emphasis>after</emphasis> a <command>make readme</command>.</para>
+	  <para>This is a top-level command, run it in
+	  <filename>pkgsrc</filename>.  Use this target to create a
+	  file <filename>README-all.html</filename> which contains a
+	  list of all packages currently available in the &os;
+	  Packages Collection, together with the category they belong
+	  to and a short description. This file is compiled from the
+	  <filename>pkgsrc/*/README.html</filename> files, so be sure
+	  to run this <emphasis>after</emphasis> a <command>make
+	  readme</command>.</para>
 	</listitem>
       </varlistentry>
 
@@ -916,11 +1101,13 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	<term>cdrom-readme</term>
 
 	<listitem>
-	  <para>This is very much the same as the <quote>readme</quote> target (see
-	  above), but is to be used when generating a pkgsrc tree to be written
-	  to a CD-ROM.  This target also produces
-	  <filename>README.html</filename> files, and can be made to refer
-	  to URLs based on <varname>CDROM_PKG_URL_HOST</varname> and
+	  <para>This is very much the same as the
+	  <quote>readme</quote> target (see above), but is to be
+	  used when generating a pkgsrc tree to be written to a
+	  CD-ROM.  This target also produces
+	  <filename>README.html</filename> files, and can be made
+	  to refer to URLs based on
+	  <varname>CDROM_PKG_URL_HOST</varname> and
 	  <varname>CDROM_PKG_URL_DIR</varname>.</para>
 	</listitem>
       </varlistentry>
@@ -929,9 +1116,10 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	<term>show-distfiles</term>
 
 	<listitem>
-	  <para>This target shows which distfiles and patchfiles are
-	  needed to build the package (<varname>ALLFILES</varname>,
-	  which contains all <varname>DISTFILES</varname> and
+	  <para>This target shows which distfiles and patchfiles
+	  are needed to build the package
+	  (<varname>ALLFILES</varname>, which contains all
+	  <varname>DISTFILES</varname> and
 	  <varname>PATCHFILES</varname>, but not
 	  <filename>patches/*</filename>).</para>
 	</listitem>
@@ -941,11 +1129,13 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	<term>show-downlevel</term>
 
 	<listitem>
-	  <para>This target shows nothing if the package is not installed. If a version
-	  of this package is installed, but is not the version provided in this
-	  version of pkgsrc, then a warning message is displayed. This target can
-	  be used to show which of your installed packages are downlevel, and so
-	  the old versions can be deleted, and the current ones added.</para>
+	  <para>This target shows nothing if the package is not
+	  installed. If a version of this package is installed,
+	  but is not the version provided in this version of
+	  pkgsrc, then a warning message is displayed. This target
+	  can be used to show which of your installed packages are
+	  downlevel, and so the old versions can be deleted, and
+	  the current ones added.</para>
 	</listitem>
       </varlistentry>
 
@@ -953,11 +1143,13 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	<term>show-pkgsrc-dir</term>
 
 	<listitem>
-	  <para>This target shows the directory in the pkgsrc hierarchy from which the
-	  package can be built and installed. This may not be the same directory
-	  as the one from which the package was installed. This target is intended
-	  to be used by people who may wish to upgrade many packages on a single
-	  host, and can be invoked from the top-level pkgsrc Makefile by using the
+	  <para>This target shows the directory in the pkgsrc
+	  hierarchy from which the package can be built and
+	  installed. This may not be the same directory as the one
+	  from which the package was installed. This target is
+	  intended to be used by people who may wish to upgrade
+	  many packages on a single host, and can be invoked from
+	  the top-level pkgsrc Makefile by using the
 	  <quote>show-host-specific-pkgs</quote> target.</para>
 	</listitem>
       </varlistentry>
@@ -966,9 +1158,10 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	<term>show-installed-depends</term>
 
 	<listitem>
-	  <para>This target shows which installed packages match the current package's
-	  <varname>DEPENDS</varname>. Useful if out of date dependencies are
-	  causing build problems.</para>
+	  <para>This target shows which installed packages match
+	  the current package's <varname>DEPENDS</varname>. Useful
+	  if out of date dependencies are causing build
+	  problems.</para>
 	</listitem>
       </varlistentry>
 
@@ -976,9 +1169,10 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	<term>check-shlibs</term>
 
 	<listitem>
-	  <para>After a package is installed, check all its binaries and (on ELF
-	  platforms) shared libraries to see if they find the shared libs they need.
-	  Run by default if <varname>PKG_DEVELOPER</varname> is set in
+	  <para>After a package is installed, check all its
+	  binaries and (on ELF platforms) shared libraries to see
+	  if they find the shared libs they need.  Run by default
+	  if <varname>PKG_DEVELOPER</varname> is set in
 	  <filename>/etc/mk.conf</filename>.</para>
 	</listitem>
       </varlistentry>
@@ -988,19 +1182,19 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 
 	<listitem>
 	  <para>After a <quote>make install</quote> from a new or
-	  upgraded pkg, this prints out an attempt to generate a new
-	  <filename>PLIST</filename> from a <command>find -newer
-	  work/.extract_done</command>.  An attempt is made to care
-	  for shared libs etc., but it is
+	  upgraded pkg, this prints out an attempt to generate a
+	  new <filename>PLIST</filename> from a <command>find
+	  -newer work/.extract_done</command>.  An attempt is made
+	  to care for shared libs etc., but it is
 	  <emphasis>strongly</emphasis> recommended to review the
 	  result before putting it into
 	  <filename>PLIST</filename>. On upgrades, it's useful to
 	  diff the output of this command against an already
 	  existing <filename>PLIST</filename> file.</para>
 
-	  <para>If the package installs files via &man.tar.1; or other
-	  methods that don't update file access times, be sure to
-	  add these files manually to your
+	  <para>If the package installs files via &man.tar.1; or
+	  other methods that don't update file access times, be
+	  sure to add these files manually to your
 	  <filename>PLIST</filename>, as the <quote>find
 	  -newer</quote> command used by this target won't catch
 	  them!</para>
@@ -1014,16 +1208,17 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	<term>bulk-package</term>
 
 	<listitem>
-	  <para>Used to do bulk builds. If an appropriate binary package already exists,
-	  no action is taken. If not, this target will compile, install and
-	  package it (and its depends, if <varname>PKG_DEPENDS</varname> is
-	  set properly. See <xref linkend="binary.configuration"/>).
-	  After creating the binary
-	  package, the sources, the just-installed package and its required
-	  packages are removed, preserving free disk space.</para>
-
-	  <para><emphasis>Beware that this target may deinstall all
-	  packages installed on a system!</emphasis></para>
+	  <para>Used to do bulk builds. If an appropriate binary
+	  package already exists, no action is taken. If not, this
+	  target will compile, install and package it (and its
+	  depends, if <varname>PKG_DEPENDS</varname> is set
+	  properly. See <xref linkend="binary.configuration"/>).
+	  After creating the binary package, the sources, the
+	  just-installed package and its required packages are
+	  removed, preserving free disk space.</para>
+
+	  <para><emphasis>Beware that this target may deinstall
+	  all packages installed on a system!</emphasis></para>
 	</listitem>
       </varlistentry>
 
@@ -1031,28 +1226,31 @@ of <varname>MAKE_FILE</varname> is <quote>Makefile</quote>, and
 	<term>bulk-install</term>
 
 	<listitem>
-	  <para>Used during bulk-installs to install required packages. If an
-	  up-to-date binary package is available, it will be installed via
-	  &man.pkg.add.1;. If not, <command>make bulk-package</command> will be executed,
+	  <para>Used during bulk-installs to install required
+	  packages. If an up-to-date binary package is available,
+	  it will be installed via &man.pkg.add.1;. If not,
+	  <command>make bulk-package</command> will be executed,
 	  but the installed binary won't be removed.</para>
 
-	  <para>A binary package is considered <quote>up-to-date</quote> to be
-	  installed via &man.pkg.add.1; if:</para>
+	  <para>A binary package is considered
+	  <quote>up-to-date</quote> to be installed via
+	  &man.pkg.add.1; if:</para>
 
 	  <itemizedlist>
 	    <listitem>
-	      <para>None of the package's files (<filename>Makefile</filename>,
-	      ...) were modified since it was built.</para>
+	      <para>None of the package's files
+	      (<filename>Makefile</filename>, ...) were modified
+	      since it was built.</para>
 	    </listitem>
 
 	    <listitem>
-	      <para>None of the package's required (binary) packages were
-	      modified since it was built.</para>
+	      <para>None of the package's required (binary)
+	      packages were modified since it was built.</para>
 	    </listitem>
 	  </itemizedlist>
 
-	  <para><emphasis>Beware that this target may deinstall all
-	  packages installed on a system!</emphasis></para>
+	  <para><emphasis>Beware that this target may deinstall
+	  all packages installed on a system!</emphasis></para>
 	</listitem>
       </varlistentry>
     </variablelist>