Use &cprompt;. Do not mention not-existing INET_COUNTRY.

Describe MASTER_SORT and MASTER_SORT_REGEX.

1 files changed, 515 insertions, 499 deletions

diff --git a/doc/guide/files/using.xml b/doc/guide/files/using.xml
index 2a3178234eb..9f51f39ebf3 100644
--- a/doc/guide/files/using.xml
+++ b/doc/guide/files/using.xml
@@ -1,516 +1,532 @@
-<!-- $NetBSD: using.xml,v 1.25 2006/09/10 19:33:05 wiz Exp $ -->
+<!-- $NetBSD: using.xml,v 1.26 2006/09/13 23:39:07 wiz Exp $ -->
 
 <chapter id="using"> <?dbhtml filename="using.html"?>
 <title>Using pkgsrc</title>
 
-	<para>Basically, there are two ways of using pkgsrc. The first
-	is to only install the package tools and to use binary packages
-	that someone else has prepared. This is the <quote>pkg</quote>
-	in pkgsrc. The second way is to install the <quote>src</quote>
-	of pkgsrc, too. Then you are able to build your own packages,
-	and you can still use binary packages from someone else.</para>
+<para>Basically, there are two ways of using pkgsrc. The first
+is to only install the package tools and to use binary packages
+that someone else has prepared. This is the <quote>pkg</quote>
+in pkgsrc. The second way is to install the <quote>src</quote>
+of pkgsrc, too. Then you are able to build your own packages,
+and you can still use binary packages from someone else.</para>
 
 <sect1 id="using-pkg">
-<title>Using binary packages</title>
-
-	<para>To use binary packages, you need some tools to manage
-	them. On NetBSD, these tools are already installed. On all other
-	operating systems, you need to install them first. For the
-	following platforms, prebuilt versions of the package tools
-	are available and can simply be downloaded and unpacked in the
-	<filename>/</filename> directory:</para>
-
-	<informaltable id="binary-bootstrap-kits">
-	<tgroup cols="2">
-	<thead><row><entry>Platform</entry><entry>URL</entry></row></thead>
-	<tbody>
+  <title>Using binary packages</title>
+
+  <para>To use binary packages, you need some tools to manage
+  them. On NetBSD, these tools are already installed. On all other
+  operating systems, you need to install them first. For the
+  following platforms, prebuilt versions of the package tools
+  are available and can simply be downloaded and unpacked in the
+  <filename>/</filename> directory:</para>
+
+  <informaltable id="binary-bootstrap-kits">
+    <tgroup cols="2">
+      <thead><row><entry>Platform</entry><entry>URL</entry></row></thead>
+      <tbody>
 	<row><entry>Solaris 9</entry><entry><filename>ftp://ftp0.mh.bbc.co.uk/pub/pkgsrc/packages/bootstrap-pkgsrc/</filename></entry></row>
 	<row><entry>Solaris 10</entry><entry><filename>http://public.enst.fr/pkgsrc/packages/bootstrap-pkgsrc/</filename></entry></row>
-	</tbody>
-	</tgroup>
-	</informaltable>
-
-	<para>These pre-built package tools use
-	<filename>/usr/pkg</filename> for the base directory, and
-	<filename>/var/db/pkg</filename> for the database of installed
-	packages. If you cannot use these directories for whatever
-	reasons (maybe because you're not root), you have to build the
-	package tools yourself, which is explained in <xref
-	linkend="bootstrapping-pkgsrc" />.</para>
-
-<sect2 id="finding-binary-packages">
-<title>Finding binary packages</title>
-
-	<para>To install binary packages, you first need to know from
-	where to get them. You can get them on CD-ROMs, DVDs, or via FTP
-	or HTTP.</para>
-
-	<para>The binary packages can be found at the following
-	locations.</para>
-
-	<informaltable id="binary-packages">
-	<tgroup cols="2">
+      </tbody>
+    </tgroup>
+  </informaltable>
+
+  <para>These pre-built package tools use
+  <filename>/usr/pkg</filename> for the base directory, and
+  <filename>/var/db/pkg</filename> for the database of installed
+  packages. If you cannot use these directories for whatever
+  reasons (maybe because you're not root), you have to build the
+  package tools yourself, which is explained in <xref
+  linkend="bootstrapping-pkgsrc" />.</para>
+
+  <sect2 id="finding-binary-packages">
+    <title>Finding binary packages</title>
+
+    <para>To install binary packages, you first need to know from
+    where to get them. You can get them on CD-ROMs, DVDs, or via FTP
+    or HTTP.</para>
+
+    <para>The binary packages can be found at the following
+    locations.</para>
+
+    <informaltable id="binary-packages">
+      <tgroup cols="2">
 	<thead><row><entry>Platform</entry><entry>URL</entry></row></thead>
 	<tbody>
-	<row><entry>NetBSD</entry><entry><filename>ftp://ftp.NetBSD.org/pub/NetBSD/packages/</filename></entry></row>
-	<row><entry>Solaris 9</entry><entry><filename>ftp://ftp0.mh.bbc.co.uk/pub/pkgsrc/packages/</filename></entry></row>
-	<row><entry>Solaris 10</entry><entry><filename>http://public.enst.fr/pkgsrc/packages/</filename></entry></row>
+	  <row><entry>NetBSD</entry><entry><filename>ftp://ftp.NetBSD.org/pub/NetBSD/packages/</filename></entry></row>
+	  <row><entry>Solaris 9</entry><entry><filename>ftp://ftp0.mh.bbc.co.uk/pub/pkgsrc/packages/</filename></entry></row>
+	  <row><entry>Solaris 10</entry><entry><filename>http://public.enst.fr/pkgsrc/packages/</filename></entry></row>
 	</tbody>
-	</tgroup>
-	</informaltable>
-
-	<para>Most of these directories contain binary packages for
-	multiple platforms. Select the appropriate subdirectories,
-	according to your machine architecture and operating system,
-	until you find a directory called <filename>All</filename>. This
-	directory contains all the binary packages. Further, there are
-	subdirectories for categories that contain symbolic links that
-	point to the actual binary package in
-	<filename>../All</filename>. This directory layout is used for
-	all package repositories, no matter if they are accessed via
-	HTTP, FTP, NFS, CD-ROM, or the local filesystem.</para>
-
-</sect2>
-<sect2 id="installing-binary-packages">
-<title>Installing binary packages</title>
-
-      <para>If you have the files on a CD-ROM or downloaded them to
-        your hard disk, you can install them with the following command
-        (be sure to <command>su</command> to root first):</para>
-
-        <screen><prompt>#</prompt> <userinput>pkg_add /path/to/package.tgz</userinput></screen>
-
-      <para>If you have FTP access and you don't want to download the
-        packages via FTP prior to installation, you can do this
-        automatically by giving <command>pkg_add</command> an FTP URL:</para>
-
-      <screen><prompt>#</prompt> <userinput>pkg_add ftp://ftp.NetBSD.org/pub/NetBSD/packages/&lt;OSVERSION&gt;/&lt;ARCH&gt;/All/package</userinput></screen>
-
-      <para>Note that any prerequisite packages needed to run the
-        package in question will be installed, too, assuming they are
-        present where you install from.</para>
-
-      <para>To save some typing, you can set the
-        <varname>PKG_PATH</varname> environment variable to a semicolon-separated
-	list of paths (including remote URLs); trailing slashes are not allowed.
-	</para>
-
-      <para>Additionally to the <filename>All</filename> directory
-        there exists a <filename>vulnerable</filename> directory to
-        which binary packages with known vulnerabilities are
-        moved, since removing them could cause missing dependencies. To
-        use these packages, add the <filename>vulnerable</filename>
-        directory to your <varname>PKG_PATH</varname>. However, you should run
-        <filename role="pkg">security/audit-packages</filename> regularly,
-	especially after installing new packages, and verify that the
-	vulnerabilities are acceptable for your configuration. An example
-        <varname>PKG_PATH</varname> would be:
-      <filename>ftp://ftp.NetBSD.org/pub/NetBSD/packages/&lt;OSVERSION&gt;/&lt;ARCH&gt;/All;ftp://ftp.NetBSD.org/pub/NetBSD/packages/&lt;OSVERSION&gt;/&lt;ARCH&gt;/vulnerable</filename>
-        Please note that semicolon (';') is a shell meta-character, so
-        you'll probably have to quote it.</para>
-
-      <para>After you've installed packages, be sure to have
-        <filename>/usr/pkg/bin</filename> and <filename>/usr/pkg/sbin</filename> in your
-        <varname>PATH</varname> so you can actually start the just
-        installed program.</para>
-    </sect2>
-
-<sect2 id="using.pkg_delete">
-<title>Deinstalling packages</title>
-
-	<para>To deinstall a package, it does not matter whether it was
-	installed from source code or from a binary package. The
-	<command>pkg_delete</command> command does not know it anyway.
-	To delete a package, you can just run <command>pkg_delete
-	<replaceable>package-name</replaceable></command>. The package
-	name can be given with or without version number. Wildcards can
-	also be used to deinstall a set of packages, for example
-	<literal>*emacs*</literal>. Be sure to include them in quotes,
-	so that the shell does not expand them before
-	<literal>pkg_delete</literal> sees them.</para>
-
-	<para>The <option>-r</option> option is very powerful: it
-	removes all the packages that require the package in question
-	and then removes the package itself. For example:
-
-<screen>
-    &rprompt; <userinput>pkg_delete -r jpeg</userinput>
-</screen>
-
-	will remove jpeg and all the packages that used it; this allows
-	upgrading the jpeg package.</para>
-
-</sect2>
-
-<sect2 id="using.pkg_info">
-<title>Getting information about installed packages</title>
-
-	<para>The <command>pkg_info</command> shows information about
-	installed packages or binary package files.</para>
-
-</sect2>
-
-<sect2 id="vulnerabilities">
-<title>Checking for security vulnerabilities in installed packages</title>
-
-<para>
-The NetBSD Security-Officer and Packages Groups maintain a list of
-known security vulnerabilities to packages which are (or have been)
-included in pkgsrc.  The list is available from the NetBSD
-FTP site at <ulink url="ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/vulnerabilities"/>.
-</para>
-
-<para>
-Through <filename role="pkg">security/audit-packages</filename>, 
-this list can be downloaded
-automatically, and a security audit of all packages installed on a system
-can take place.
-</para>
-
-<para>
-There are two components to 
-<filename role="pkg">security/audit-packages</filename>.  The first
-component, <quote>download-vulnerability-list</quote>, is for downloading
-the list of vulnerabilities from the NetBSD FTP site.  The second
-component, <quote>audit-packages</quote>, checks to see if any of your
-installed packages are vulnerable.  If a package is vulnerable, you
-will see output similar to the following:
-</para>
-
-<screen>Package samba-2.0.9 has a local-root-shell vulnerability, see
-http://www.samba.org/samba/whatsnew/macroexploit.html</screen>
-
-<para>
-One can set up <filename 
-role="pkg">security/audit-packages</filename> to download the
-<ulink url="ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/vulnerabilities">vulnerabilities</ulink>
-file daily, and include a package audit in the daily security script.
-Details on this are located in the <ulink
-url="http://cvsweb.NetBSD.org/bsdweb.cgi/pkgsrc/security/audit-packages/MESSAGE?rev=HEAD&amp;content-type=text/x-cvsweb-markup">MESSAGE</ulink>
-file for <filename role="pkg">security/audit-packages</filename>.
-</para>
-</sect2>
-
-<sect2 id="pkg_versions">
-<title>Finding if newer versions of your installed packages are in pkgsrc</title>
-<para>
-Install <filename role="pkg">pkgtools/pkglint</filename> and run 
-<command>lintpkgsrc</command> with the <quote>-i</quote>
-argument to check if your packages are up-to-date, e.g.
-</para>
-<screen><prompt>%</prompt> <userinput>lintpkgsrc -i</userinput>
+      </tgroup>
+    </informaltable>
+
+    <para>Most of these directories contain binary packages for
+    multiple platforms. Select the appropriate subdirectories,
+    according to your machine architecture and operating system,
+    until you find a directory called <filename>All</filename>. This
+    directory contains all the binary packages. Further, there are
+    subdirectories for categories that contain symbolic links that
+    point to the actual binary package in
+    <filename>../All</filename>. This directory layout is used for
+    all package repositories, no matter if they are accessed via
+    HTTP, FTP, NFS, CD-ROM, or the local filesystem.</para>
+
+  </sect2>
+  <sect2 id="installing-binary-packages">
+    <title>Installing binary packages</title>
+
+    <para>If you have the files on a CD-ROM or downloaded them to
+    your hard disk, you can install them with the following command
+    (be sure to <command>su</command> to root first):</para>
+
+    <screen>&rprompt; <userinput>pkg_add /path/to/package.tgz</userinput></screen>
+
+    <para>If you have FTP access and you don't want to download the
+    packages via FTP prior to installation, you can do this
+    automatically by giving <command>pkg_add</command> an FTP URL:</para>
+
+    <screen>&rprompt; <userinput>pkg_add ftp://ftp.NetBSD.org/pub/NetBSD/packages/&lt;OSVERSION&gt;/&lt;ARCH&gt;/All/package</userinput></screen>
+
+    <para>Note that any prerequisite packages needed to run the
+    package in question will be installed, too, assuming they are
+    present where you install from.</para>
+
+    <para>To save some typing, you can set the
+    <varname>PKG_PATH</varname> environment variable to a semicolon-separated
+    list of paths (including remote URLs); trailing slashes are not allowed.
+    </para>
+
+    <para>Additionally to the <filename>All</filename> directory
+    there exists a <filename>vulnerable</filename> directory to
+    which binary packages with known vulnerabilities are
+    moved, since removing them could cause missing dependencies. To
+    use these packages, add the <filename>vulnerable</filename>
+    directory to your <varname>PKG_PATH</varname>. However, you should run
+    <filename role="pkg">security/audit-packages</filename> regularly,
+    especially after installing new packages, and verify that the
+    vulnerabilities are acceptable for your configuration. An example
+    <varname>PKG_PATH</varname> would be:
+    <filename>ftp://ftp.NetBSD.org/pub/NetBSD/packages/&lt;OSVERSION&gt;/&lt;ARCH&gt;/All;ftp://ftp.NetBSD.org/pub/NetBSD/packages/&lt;OSVERSION&gt;/&lt;ARCH&gt;/vulnerable</filename>
+    Please note that semicolon (';') is a shell meta-character, so
+    you'll probably have to quote it.</para>
+
+    <para>After you've installed packages, be sure to have
+    <filename>/usr/pkg/bin</filename> and <filename>/usr/pkg/sbin</filename> in your
+    <varname>PATH</varname> so you can actually start the just
+    installed program.</para>
+  </sect2>
+
+  <sect2 id="using.pkg_delete">
+    <title>Deinstalling packages</title>
+
+    <para>To deinstall a package, it does not matter whether it was
+    installed from source code or from a binary package. The
+    <command>pkg_delete</command> command does not know it anyway.
+    To delete a package, you can just run <command>pkg_delete
+    <replaceable>package-name</replaceable></command>. The package
+    name can be given with or without version number. Wildcards can
+    also be used to deinstall a set of packages, for example
+    <literal>*emacs*</literal>. Be sure to include them in quotes,
+    so that the shell does not expand them before
+    <literal>pkg_delete</literal> sees them.</para>
+
+    <para>The <option>-r</option> option is very powerful: it
+    removes all the packages that require the package in question
+    and then removes the package itself. For example:
+
+    <screen>
+&rprompt; <userinput>pkg_delete -r jpeg</userinput>
+    </screen>
+
+    will remove jpeg and all the packages that used it; this allows
+    upgrading the jpeg package.</para>
+
+  </sect2>
+
+  <sect2 id="using.pkg_info">
+    <title>Getting information about installed packages</title>
+
+    <para>The <command>pkg_info</command> shows information about
+    installed packages or binary package files.</para>
+
+  </sect2>
+
+  <sect2 id="vulnerabilities">
+    <title>Checking for security vulnerabilities in installed packages</title>
+
+    <para>
+      The NetBSD Security-Officer and Packages Groups maintain a list of
+      known security vulnerabilities to packages which are (or have been)
+      included in pkgsrc.  The list is available from the NetBSD
+      FTP site at <ulink url="ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/vulnerabilities"/>.
+    </para>
+
+    <para>
+      Through <filename role="pkg">security/audit-packages</filename>, 
+      this list can be downloaded
+      automatically, and a security audit of all packages installed on a system
+      can take place.
+    </para>
+
+    <para>
+      There are two components to 
+      <filename role="pkg">security/audit-packages</filename>.  The first
+      component, <quote>download-vulnerability-list</quote>, is for downloading
+      the list of vulnerabilities from the NetBSD FTP site.  The second
+      component, <quote>audit-packages</quote>, checks to see if any of your
+      installed packages are vulnerable.  If a package is vulnerable, you
+      will see output similar to the following:
+    </para>
+
+    <screen>Package samba-2.0.9 has a local-root-shell vulnerability, see
+    http://www.samba.org/samba/whatsnew/macroexploit.html</screen>
+
+    <para>
+      One can set up <filename 
+      role="pkg">security/audit-packages</filename> to download the
+      <ulink url="ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/vulnerabilities">vulnerabilities</ulink>
+      file daily, and include a package audit in the daily security script.
+      Details on this are located in the <ulink
+      url="http://cvsweb.NetBSD.org/bsdweb.cgi/pkgsrc/security/audit-packages/MESSAGE?rev=HEAD&amp;content-type=text/x-cvsweb-markup">MESSAGE</ulink>
+      file for <filename role="pkg">security/audit-packages</filename>.
+    </para>
+  </sect2>
+
+  <sect2 id="pkg_versions">
+    <title>Finding if newer versions of your installed packages are in pkgsrc</title>
+    <para>
+      Install <filename role="pkg">pkgtools/pkglint</filename> and run 
+      <command>lintpkgsrc</command> with the <quote>-i</quote>
+      argument to check if your packages are up-to-date, e.g.
+    </para>
+    <screen>
+&cprompt; <userinput>lintpkgsrc -i</userinput>
 ...
-Version mismatch: 'tcsh' 6.09.00 vs 6.10.00</screen>
-<para>You can then use <command>make update</command> to update the
-package on your system and rebuild any dependencies.
-</para>
-</sect2>
-
-<sect2 id="using.pkg_admin">
-<title>Other administrative functions</title>
-
-	<para>The <command>pkg_admin</command> executes various
-	administrative functions on the package system.</para>
-
-</sect2>
-
-    <sect2 id="a-word-of-warning">
-      <title>A word of warning</title>
-
-      <para>Please pay very careful attention to the warnings
-        expressed in the &man.pkg.add.1; manual page about the
-        inherent dangers of installing binary packages which you did
-        not create yourself, and the security holes that can be
-        introduced onto your system by indiscriminate adding of such
-        files.</para>
-
-      <para>The same warning of course applies to every package you
-      install from source when you haven't completely read and
-      understood the source code of the package, the compiler that
-      is used to build the package and all the other tools that are
-      involved.</para>
-
-    </sect2>
-  </sect1>
-
-  <sect1 id="building-packages-from-source">
-    <title>Building packages from source</title>
-
-<para>After obtaining pkgsrc, the <filename>pkgsrc</filename> directory
-now contains a set of packages, organized into categories. You can browse
-the online index of packages, or run <command>make readme</command>
-from the <filename>pkgsrc</filename> directory to build local
-<filename>README.html</filename> files for all packages, viewable with any web browser such as
-<filename role="pkg">www/lynx</filename> or 
-<filename role="pkg">www/firefox</filename>.</para>
-
-<para>The default <emphasis>prefix</emphasis> for installed packages is
-<filename>/usr/pkg</filename>. If you wish to change this, you should do
-so by setting <varname>LOCALBASE</varname> in
-<filename>mk.conf</filename>. You should not try to use multiple
-different <varname>LOCALBASE</varname> definitions on the same system
-(inside a chroot is an exception). </para>
-
-    <para>The rest of this chapter assumes that the package is already in pkgsrc. If it
-      is not, see <xref linkend="developers-guide"/> for instructions
-      how to create your own packages.</para>
-
-    <sect2 id="requirements">
-      <title>Requirements</title>
-
-      <para>To build packages from source, you need a working C
-      compiler. On NetBSD, you need to install the
-      <quote>comp</quote> and the <quote>text</quote> distribution
-      sets. If you want to build X11-related packages, the
-      <quote>xbase</quote> and <quote>xcomp</quote> distribution
-      sets are required, too.</para>
-      <!-- FIXME: what about installing x11/XFree86-*? -->
-    </sect2>
-
-
-    <sect2 id="fetching-distfiles">
-      <title>Fetching distfiles</title>
-
-      <para>The first step for building a package is downloading the
-      distfiles (i.e. the unmodified source). If they have not yet been
-      downloaded, pkgsrc will fetch them automatically.</para>
-
-<para>
-If you have all files that you need in the
-<filename>distfiles</filename> directory,
-you don't need to connect. If the distfiles are on CD-ROM, you can
-mount the CD-ROM on <filename>/cdrom</filename> and add:
-<screen>DISTDIR=/cdrom/pkgsrc/distfiles</screen>
-to your <filename>mk.conf</filename>.
-</para>
-
-      <para>You can overwrite some of the major distribution sites to fit to sites
-        that are close to your own.  Have a look at
-        <filename>pkgsrc/mk/defaults/mk.conf</filename> to find some examples
-        &mdash; in particular, look for the <varname>MASTER_SORT</varname>,
-        <varname>MASTER_SORT_REGEX</varname> and
-        <varname>INET_COUNTRY</varname> definitions.  This may save some of your
-        bandwidth and time.</para>
-
-      <para>You can change these settings either in your shell's environment, or,
-        if you want to keep the settings, by editing the
-        <filename>/etc/mk.conf</filename> file,
-        and adding the definitions there.</para>
-
-<para>
-If a package depends on many other packages (such as
-<filename role="pkg">meta-pkgs/kde3</filename>), the build process may 
-alternate between periods of
-downloading source, and compiling. To ensure you have all the source
-downloaded initially you can run the command:
-<screen><prompt>%</prompt> <userinput>make fetch-list | sh</userinput></screen>
-which will output and run a set of shell commands to fetch the
-necessary files into the <filename>distfiles</filename> directory.  You can
-also choose to download the files manually.
-</para>
-
-    </sect2>
-
-    <sect2 id="how-to-build-and-install">
-      <title>How to build and install</title>
-
-<para>
-Once the software has downloaded, any patches will be applied, then it
-will be compiled for you. This may take some time depending on your
-computer, and how many other packages the software depends on and their
-compile time.
-</para>
-
-      <note><para>If using bootstrap or pkgsrc on a non-NetBSD system,
-        use the pkgsrc <command>bmake</command> command instead of
-        <quote>make</quote> in the examples in this guide.</para></note>
-
-     <para>For example, type</para>
-
-      <screen>&cprompt; <userinput>cd misc/figlet</userinput>
-&cprompt; <userinput>make</userinput></screen>
-
-      <para>at the shell prompt to build the various components of the
-        package.</para>
-
-	<para>The next stage is to actually install the newly compiled
-	program onto your system. Do this by entering:
-
-<screen>
-    <prompt>%</prompt> <userinput>make install</userinput>
-</screen>
-
-	while you are still in the directory for whatever package you
-	are installing.</para>
-
-	<para>Installing the package on your system may require you to
-	be root.  However, pkgsrc has a
-        <emphasis>just-in-time-su</emphasis> feature, which allows you
-        to only become root for the actual installation step.</para>
-
-<para>That's it, the software should now be installed and setup for use.
-You can now enter:
-
-<screen>
-    <prompt>%</prompt> <userinput>make clean</userinput>
-</screen>
-
-	to remove the compiled files in the work directory, as you shouldn't need
-	them any more. If other packages were also added to your system
-	(dependencies) to allow your program to compile, you can tidy these up
-	also with the command:</para>
-
-<screen>
-    <prompt>%</prompt> <userinput>make clean-depends</userinput>
-</screen>
-
-      <para>Taking the figlet utility as an example, we can install it on our
-        system by building as shown in <xref linkend="logs"/>.</para>
-
-      <para>The program is installed under the default root of the packages tree -
-        <filename>/usr/pkg</filename>. Should this not conform to your tastes,
-        set the <varname>LOCALBASE</varname>
-        variable in your environment, and it will use that value as the root of
-        your packages tree. So, to use <filename>/usr/local</filename>, set
-        <varname>LOCALBASE=/usr/local</varname> in your environment.  Please note
-        that you should use a directory which is
-        dedicated to packages and not shared with other programs (i.e., do not try
-        and use <varname>LOCALBASE=/usr</varname>).  Also, you should not try to
-        add any of your own files or directories (such as <filename>src/</filename>,
-        <filename>obj/</filename>, or <filename>pkgsrc/</filename>) below the
-        <varname>LOCALBASE</varname> tree.  This is to prevent possible conflicts
-        between programs and other files installed by the package system and
-        whatever else may have been installed there.</para>
-
-      <para>Some packages look in <filename>/etc/mk.conf</filename> to alter some
-        configuration options at build time.  Have a look at
-        <filename>pkgsrc/mk/defaults/mk.conf</filename> to
-        get an overview of what will be set there by default.  Environment
-        variables such as <varname>LOCALBASE</varname>
-        can be set in <filename>/etc/mk.conf</filename> to
-        save having to remember to set them each time you want to use pkgsrc.</para>
-
-      <para>Occasionally, people want to <quote>look under the covers</quote> to see
-        what is going on when a package is building or being installed. This may be
-        for debugging purposes, or out of simple curiosity. A number of utility
-        values have been added to help with this.</para>
-
-      <orderedlist>
-        <listitem>
-          <para>If you invoke the &man.make.1; command with <varname>PKG_DEBUG_LEVEL=2</varname>,
-            then a huge amount of information will be displayed. For example,</para>
-
-          <screen><userinput>make patch PKG_DEBUG_LEVEL=2</userinput></screen>
-
-          <para>will show all the commands that are invoked, up to and including the
-            <quote>patch</quote> stage.</para>
-        </listitem>
-
-        <listitem>
-          <para>If you want to know the value of a certain &man.make.1; definition, then
-            the <varname>VARNAME</varname> definition should be used, in conjunction
-            with the show-var target. e.g. to show the expansion of the &man.make.1; variable
-            <varname>LOCALBASE</varname>:</para>
-
-          <screen>&cprompt; <userinput>make show-var VARNAME=LOCALBASE</userinput>
+Version mismatch: 'tcsh' 6.09.00 vs 6.10.00
+    </screen>
+    <para>You can then use <command>make update</command> to update the
+    package on your system and rebuild any dependencies.
+    </para>
+  </sect2>
+
+  <sect2 id="using.pkg_admin">
+    <title>Other administrative functions</title>
+
+    <para>The <command>pkg_admin</command> executes various
+    administrative functions on the package system.</para>
+
+  </sect2>
+
+  <sect2 id="a-word-of-warning">
+    <title>A word of warning</title>
+
+    <para>Please pay very careful attention to the warnings
+    expressed in the &man.pkg.add.1; manual page about the
+    inherent dangers of installing binary packages which you did
+    not create yourself, and the security holes that can be
+    introduced onto your system by indiscriminate adding of such
+    files.</para>
+
+    <para>The same warning of course applies to every package you
+    install from source when you haven't completely read and
+    understood the source code of the package, the compiler that
+    is used to build the package and all the other tools that are
+    involved.</para>
+
+  </sect2>
+</sect1>
+
+<sect1 id="building-packages-from-source">
+  <title>Building packages from source</title>
+
+  <para>After obtaining pkgsrc, the <filename>pkgsrc</filename>
+  directory now contains a set of packages, organized into
+  categories. You can browse the online index of packages, or run
+  <command>make readme</command> from the <filename>pkgsrc</filename>
+  directory to build local <filename>README.html</filename> files for
+  all packages, viewable with any web browser such as <filename
+  role="pkg">www/lynx</filename> or <filename
+  role="pkg">www/firefox</filename>.</para>
+
+  <para>The default <emphasis>prefix</emphasis> for installed packages
+  is <filename>/usr/pkg</filename>. If you wish to change this, you
+  should do so by setting <varname>LOCALBASE</varname> in
+  <filename>mk.conf</filename>. You should not try to use multiple
+  different <varname>LOCALBASE</varname> definitions on the same
+  system (inside a chroot is an exception). </para>
+
+  <para>The rest of this chapter assumes that the package is already
+  in pkgsrc. If it is not, see <xref linkend="developers-guide"/> for
+  instructions how to create your own packages.</para>
+
+  <sect2 id="requirements">
+    <title>Requirements</title>
+
+    <para>To build packages from source, you need a working C
+    compiler. On NetBSD, you need to install the
+    <quote>comp</quote> and the <quote>text</quote> distribution
+    sets. If you want to build X11-related packages, the
+    <quote>xbase</quote> and <quote>xcomp</quote> distribution
+    sets are required, too.</para>
+    <!-- FIXME: what about installing x11/XFree86-*? -->
+  </sect2>
+
+
+  <sect2 id="fetching-distfiles">
+    <title>Fetching distfiles</title>
+
+    <para>The first step for building a package is downloading the
+    distfiles (i.e. the unmodified source). If they have not yet been
+    downloaded, pkgsrc will fetch them automatically.</para>
+
+    <para>If you have all files that you need in the
+    <filename>distfiles</filename> directory,
+    you don't need to connect. If the distfiles are on CD-ROM, you can
+    mount the CD-ROM on <filename>/cdrom</filename> and add:
+    <screen>DISTDIR=/cdrom/pkgsrc/distfiles</screen>
+    to your <filename>mk.conf</filename>.</para>
+
+    <para>You can overwrite some of the major distribution sites to
+    fit to sites that are close to your own.  By setting one or two
+    variables you can modify the order in which the master sites are
+    accessed.  <varname>MASTER_SORT</varname> contains a whitespace
+    delimited list of domain suffixes.
+    <varname>MASTER_SORT_REGEX</varname> is even more flexible, it
+    contains a whitespace delimited list of regular expressions.  It
+    has higher priority than <varname>MASTER_SORT</varname>.  Have a
+    look at <filename>pkgsrc/mk/defaults/mk.conf</filename> to find
+    some examples.  This may save some of your bandwidth and
+    time.</para>
+
+    <para>You can change these settings either in your shell's environment, or,
+    if you want to keep the settings, by editing the
+    <filename>/etc/mk.conf</filename> file,
+    and adding the definitions there.</para>
+
+    <para>
+      If a package depends on many other packages (such as
+      <filename role="pkg">meta-pkgs/kde3</filename>), the build process may 
+      alternate between periods of
+      downloading source, and compiling. To ensure you have all the source
+      downloaded initially you can run the command:
+      <screen>&cprompt; <userinput>make fetch-list | sh</userinput></screen>
+      which will output and run a set of shell commands to fetch the
+      necessary files into the <filename>distfiles</filename> directory.  You can
+      also choose to download the files manually.
+    </para>
+
+  </sect2>
+
+  <sect2 id="how-to-build-and-install">
+    <title>How to build and install</title>
+
+    <para>
+      Once the software has downloaded, any patches will be applied, then it
+      will be compiled for you. This may take some time depending on your
+      computer, and how many other packages the software depends on and their
+      compile time.
+    </para>
+
+    <note><para>If using bootstrap or pkgsrc on a non-NetBSD system,
+    use the pkgsrc <command>bmake</command> command instead of
+    <quote>make</quote> in the examples in this guide.</para></note>
+
+    <para>For example, type</para>
+
+    <screen>
+&cprompt; <userinput>cd misc/figlet</userinput>
+&cprompt; <userinput>make</userinput>
+    </screen>
+
+    <para>at the shell prompt to build the various components of the
+    package.</para>
+
+    <para>The next stage is to actually install the newly compiled
+    program onto your system. Do this by entering:
+
+    <screen>
+&cprompt; <userinput>make install</userinput>
+    </screen>
+
+    while you are still in the directory for whatever package you
+    are installing.</para>
+
+    <para>Installing the package on your system may require you to
+    be root.  However, pkgsrc has a
+    <emphasis>just-in-time-su</emphasis> feature, which allows you
+    to only become root for the actual installation step.</para>
+
+    <para>That's it, the software should now be installed and setup for use.
+    You can now enter:
+
+    <screen>
+&cprompt; <userinput>make clean</userinput>
+    </screen>
+
+    to remove the compiled files in the work directory, as you shouldn't need
+    them any more. If other packages were also added to your system
+    (dependencies) to allow your program to compile, you can tidy these up
+    also with the command:</para>
+
+    <screen>
+&cprompt; <userinput>make clean-depends</userinput>
+    </screen>
+
+    <para>Taking the figlet utility as an example, we can install it on our
+    system by building as shown in <xref linkend="logs"/>.</para>
+
+    <para>The program is installed under the default root of the
+    packages tree - <filename>/usr/pkg</filename>. Should this not
+    conform to your tastes, set the <varname>LOCALBASE</varname>
+    variable in your environment, and it will use that value as the
+    root of your packages tree. So, to use
+    <filename>/usr/local</filename>, set
+    <varname>LOCALBASE=/usr/local</varname> in your environment.
+    Please note that you should use a directory which is dedicated to
+    packages and not shared with other programs (i.e., do not try and
+    use <varname>LOCALBASE=/usr</varname>).  Also, you should not try
+    to add any of your own files or directories (such as
+    <filename>src/</filename>, <filename>obj/</filename>, or
+    <filename>pkgsrc/</filename>) below the
+    <varname>LOCALBASE</varname> tree.  This is to prevent possible
+    conflicts between programs and other files installed by the
+    package system and whatever else may have been installed
+    there.</para>
+
+    <para>Some packages look in <filename>/etc/mk.conf</filename> to
+    alter some configuration options at build time.  Have a look at
+    <filename>pkgsrc/mk/defaults/mk.conf</filename> to get an overview
+    of what will be set there by default.  Environment variables such
+    as <varname>LOCALBASE</varname> can be set in
+    <filename>/etc/mk.conf</filename> to save having to remember to
+    set them each time you want to use pkgsrc.</para>
+
+    <para>Occasionally, people want to <quote>look under the
+    covers</quote> to see what is going on when a package is building
+    or being installed. This may be for debugging purposes, or out of
+    simple curiosity. A number of utility values have been added to
+    help with this.</para>
+
+    <orderedlist>
+      <listitem>
+	<para>If you invoke the &man.make.1; command with
+	<varname>PKG_DEBUG_LEVEL=2</varname>, then a huge amount of
+	information will be displayed. For example,</para>
+
+	<screen><userinput>make patch PKG_DEBUG_LEVEL=2</userinput></screen>
+
+	<para>will show all the commands that are invoked, up to and
+	including the <quote>patch</quote> stage.</para>
+      </listitem>
+
+      <listitem>
+	<para>If you want to know the value of a certain &man.make.1;
+	definition, then the <varname>VARNAME</varname> definition
+	should be used, in conjunction with the show-var
+	target. e.g. to show the expansion of the &man.make.1;
+	variable <varname>LOCALBASE</varname>:</para>
+
+	<screen>
+&cprompt; <userinput>make show-var VARNAME=LOCALBASE</userinput>
 /usr/pkg
 &cprompt;
-          </screen>
-
-        </listitem>
-      </orderedlist>
-
-      <para>If you want to install a binary package that you've either
-        created yourself (see next section), that you put into pkgsrc/packages manually or
-        that is located on a remote FTP server, you can use the "bin-install"
-        target. This target will install a binary package - if available - via
-        &man.pkg.add.1;, else do a <command>make package</command>.
-        The list of remote
-        FTP sites searched is kept in the variable
-        <varname>BINPKG_SITES</varname>, which defaults to
-        ftp.NetBSD.org. Any flags that should be added to &man.pkg.add.1; can be put
-        into <varname>BIN_INSTALL_FLAGS</varname>.
-        See <filename>pkgsrc/mk/defaults/mk.conf</filename> for more details.</para>
-
-      <para>A final word of warning: If you set up a system that has a non-standard
-        setting for <varname>LOCALBASE</varname>, be sure to set that
-        before any packages are installed, as you cannot use several directories
-        for the same purpose. Doing so will result in pkgsrc not being able to
-        properly detect your installed packages, and fail miserably. Note also that
-        precompiled binary packages are usually built with the default
-        <varname>LOCALBASE</varname> of
-        <filename>/usr/pkg</filename>, and that you should <emphasis>not</emphasis>
-        install any if you use a non-standard <varname>LOCALBASE</varname>.</para>
-    </sect2>
-
-    <sect2 id="selecting-the-compiler">
-      <title>Selecting the compiler</title>
-
-      <para>By default, pkgsrc will use GCC to build packages.  This may be
-        overridden by setting the following variables in /etc/mk.conf:</para>
-
-      <variablelist>
-        <varlistentry>
-          <term><varname>PKGSRC_COMPILER</varname>:</term>
-
-          <listitem>
-            <para>This is a list of values specifying the chain of
-              compilers to invoke when building packages.  Valid values
-              are:</para>
-
-<!-- TODO: update this list after jlam's changes in May 2005 -->
-            <itemizedlist>
-              <listitem><para><varname>distcc</varname>:
-                distributed C/C++ (chainable)</para>
-              </listitem>
-
-              <listitem><para><varname>ccache</varname>:
-                compiler cache (chainable)</para>
-              </listitem>
-
-              <listitem><para><varname>gcc</varname>:
-                GNU C/C++ Compiler</para>
-              </listitem>
-
-              <listitem><para><varname>mipspro</varname>:
-                Silicon Graphics, Inc. MIPSpro (n32/n64)</para>
-              </listitem>
-
-              <listitem><para><varname>mipspro</varname>:
-                Silicon Graphics, Inc. MIPSpro (o32)</para>
-              </listitem>
-
-              <listitem><para><varname>sunpro</varname>:
-                Sun Microsystems, Inc. WorkShip/Forte/Sun ONE Studio</para>
-              </listitem>
-            </itemizedlist>
-
-            <para>The default is
-              <quote><varname>gcc</varname></quote>.  You can use
-              <varname>ccache</varname> and/or
-              <varname>distcc</varname> with an appropriate
-              <varname>PKGSRC_COMPILER</varname> setting,
-              e.g. <quote><varname>ccache gcc</varname></quote>.  This
-              variable should always be
-              terminated with a value for a real compiler.</para>
-	  </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><varname>GCC_REQD</varname>:</term>
-<!--
-   TODO: what are the effects of setting GCC_REQD if PKGSRC_COMPILER
-   is not gcc?
--->
-          <listitem>
-            <para>This specifies the minimum version of GCC to use
-              when building packages.  If the system GCC doesn't
-              satisfy this requirement, then pkgsrc will build and
-              install one of the GCC packages to use instead.</para>
-          </listitem>
-        </varlistentry>
-      </variablelist>
-    </sect2>
+	</screen>
+
+      </listitem>
+    </orderedlist>
+
+    <para>If you want to install a binary package that you've either
+    created yourself (see next section), that you put into
+    pkgsrc/packages manually or that is located on a remote FTP
+    server, you can use the "bin-install" target. This target will
+    install a binary package - if available - via &man.pkg.add.1;,
+    else do a <command>make package</command>.  The list of remote FTP
+    sites searched is kept in the variable
+    <varname>BINPKG_SITES</varname>, which defaults to
+    ftp.NetBSD.org. Any flags that should be added to &man.pkg.add.1;
+    can be put into <varname>BIN_INSTALL_FLAGS</varname>.  See
+    <filename>pkgsrc/mk/defaults/mk.conf</filename> for more
+    details.</para>
+
+    <para>A final word of warning: If you set up a system that has a
+    non-standard setting for <varname>LOCALBASE</varname>, be sure to
+    set that before any packages are installed, as you cannot use
+    several directories for the same purpose. Doing so will result in
+    pkgsrc not being able to properly detect your installed packages,
+    and fail miserably. Note also that precompiled binary packages are
+    usually built with the default <varname>LOCALBASE</varname> of
+    <filename>/usr/pkg</filename>, and that you should
+    <emphasis>not</emphasis> install any if you use a non-standard
+    <varname>LOCALBASE</varname>.</para>
+  </sect2>
+
+  <sect2 id="selecting-the-compiler">
+    <title>Selecting the compiler</title>
+
+    <para>By default, pkgsrc will use GCC to build packages.  This may be
+    overridden by setting the following variables in /etc/mk.conf:</para>
+
+    <variablelist>
+      <varlistentry>
+	<term><varname>PKGSRC_COMPILER</varname>:</term>
+
+	<listitem>
+	  <para>This is a list of values specifying the chain of
+	  compilers to invoke when building packages.  Valid values
+	  are:</para>
+
+	  <!-- TODO: update this list after jlam's changes in May 2005 -->
+	  <itemizedlist>
+	    <listitem><para><varname>distcc</varname>:
+	    distributed C/C++ (chainable)</para>
+	    </listitem>
+
+	    <listitem><para><varname>ccache</varname>:
+	    compiler cache (chainable)</para>
+	    </listitem>
+
+	    <listitem><para><varname>gcc</varname>:
+	    GNU C/C++ Compiler</para>
+	    </listitem>
+
+	    <listitem><para><varname>mipspro</varname>:
+	    Silicon Graphics, Inc. MIPSpro (n32/n64)</para>
+	    </listitem>
+
+	    <listitem><para><varname>mipspro</varname>:
+	    Silicon Graphics, Inc. MIPSpro (o32)</para>
+	    </listitem>
+
+	    <listitem><para><varname>sunpro</varname>:
+	    Sun Microsystems, Inc. WorkShip/Forte/Sun ONE Studio</para>
+	    </listitem>
+	  </itemizedlist>
+
+	  <para>The default is
+	  <quote><varname>gcc</varname></quote>.  You can use
+	  <varname>ccache</varname> and/or
+	  <varname>distcc</varname> with an appropriate
+	  <varname>PKGSRC_COMPILER</varname> setting,
+	  e.g. <quote><varname>ccache gcc</varname></quote>.  This
+	  variable should always be
+	  terminated with a value for a real compiler.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><varname>GCC_REQD</varname>:</term>
+	<!--
+	    TODO: what are the effects of setting GCC_REQD if PKGSRC_COMPILER
+	    is not gcc?
+	-->
+	<listitem>
+	  <para>This specifies the minimum version of GCC to use
+	  when building packages.  If the system GCC doesn't
+	  satisfy this requirement, then pkgsrc will build and
+	  install one of the GCC packages to use instead.</para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+  </sect2>
 
 </sect1>
 </chapter>