regen.

1 files changed, 116 insertions, 42 deletions

diff --git a/doc/pkgsrc.txt b/doc/pkgsrc.txt
index e4590b309ca..fcceb281bd6 100644
--- a/doc/pkgsrc.txt
+++ b/doc/pkgsrc.txt
@@ -12,7 +12,7 @@ Hubert Feyrer
 
 The pkgsrc Developers
 
-Copyright (C) 1994-2006 The NetBSD Foundation, Inc
+Copyright   1994-2006 The NetBSD Foundation, Inc
 
 $NetBSD: pkgsrc.xml,v 1.18 2006/05/19 22:05:09 rillig Exp $
 
@@ -41,10 +41,16 @@ I. The pkgsrc user's guide
 
     2. Where to get pkgsrc and how to keep it up-to-date
 
-        2.1. As tar file
-        2.2. Via SUP
-        2.3. Via CVS
-        2.4. Keeping pkgsrc up-to-date via CVS
+        2.1. Getting pkgsrc for the first time
+
+            2.1.1. As tar file
+            2.1.2. Via SUP
+            2.1.3. Via CVS
+
+        2.2. Keeping pkgsrc up-to-date
+
+            2.2.1. Via tar files
+            2.2.2. Via CVS
 
     3. Using pkgsrc on systems other than NetBSD
 
@@ -511,10 +517,16 @@ Table of Contents
 
 2. Where to get pkgsrc and how to keep it up-to-date
 
-    2.1. As tar file
-    2.2. Via SUP
-    2.3. Via CVS
-    2.4. Keeping pkgsrc up-to-date via CVS
+    2.1. Getting pkgsrc for the first time
+
+        2.1.1. As tar file
+        2.1.2. Via SUP
+        2.1.3. Via CVS
+
+    2.2. Keeping pkgsrc up-to-date
+
+        2.2.1. Via tar files
+        2.2.2. Via CVS
 
 3. Using pkgsrc on systems other than NetBSD
 
@@ -593,20 +605,52 @@ Chapter 2. Where to get pkgsrc and how to keep it up-to-date
 
 Table of Contents
 
-2.1. As tar file
-2.2. Via SUP
-2.3. Via CVS
-2.4. Keeping pkgsrc up-to-date via CVS
+2.1. Getting pkgsrc for the first time
+
+    2.1.1. As tar file
+    2.1.2. Via SUP
+    2.1.3. Via CVS
+
+2.2. Keeping pkgsrc up-to-date
+
+    2.2.1. Via tar files
+    2.2.2. Via CVS
+
+The most common location where pkgsrc is installed is /usr/pkgsrc for the
+"package sources" and /usr/pkg for the installed binary packages. You are
+though free to install the sources and binary packages wherever you want in
+your filesystem, provided that both paths do not contain white-space or other
+characters that are interpreted specially by the shell and some other programs.
+A safe bet is to use only letters, digits, underscores and dashes in the names.
+
+2.1. Getting pkgsrc for the first time
+
+Before you download any pkgsrc files, you should decide whether you want the
+current branch or the stable branch. The latter is forked on a quarterly basis
+from the current branch and only gets modified for security updates. The names
+of the stable branches are built from the year and the quarter, for example
+2006Q1.
+
+The second step is to decide how you want to download pkgsrc. You can get it as
+a tar file, via SUP, or via CVS. All three ways are described here.
 
-There are three ways to get pkgsrc. Either as a tar file, via SUP, or via CVS.
-All three ways are described here.
+2.1.1. As tar file
 
-2.1. As tar file
+The primary download location for all pkgsrc files is ftp://ftp.NetBSD.org/pub/
+pkgsrc/. There are a number of subdirectories for different purposes, which are
+described in detail in Appendix C, Layout of the FTP server's package archive.
 
-To get pkgsrc going, you need to get the pkgsrc.tar.gz file from ftp.NetBSD.org
-and unpack it into /usr/pkgsrc.
+The tar file for the current branch is in the directory current and is called
+pkgsrc.tar.gz. It is autogenerated daily.
 
-2.2. Via SUP
+The tar file for the stable branch 2006Q1 is in the directory 2006Q1 and is
+also called pkgsrc.tar.gz.
+
+After downloading the tar file, change to the directory where you want to have
+pkgsrc. This is usually /usr. Then, run tar xfz pkgsrc.tar.gz to extract the
+files.
+
+2.1.2. Via SUP
 
 As an alternative to the tar file, you can get pkgsrc via the Software Update
 Protocol, SUP. To do so, make sure your supfile has a line
@@ -616,37 +660,67 @@ Protocol, SUP. To do so, make sure your supfile has a line
 in it, see the examples in /usr/share/examples/supfiles, and that the /usr/
 pkgsrc directory exists. Then, simply run sup -v /path/to/your/supfile.
 
-2.3. Via CVS
+2.1.3. Via CVS
 
-To get pkgsrc via CVS, make sure you have "cvs" installed. To do an initial
-(full) checkout of pkgsrc, do the following steps:
+To get pkgsrc via CVS, make sure you have cvs(1) installed. To do an initial
+(full) checkout of pkgsrc, you first have to set some environment variables.
+For the C-Shell, type:
 
-% setenv CVSROOT anoncvs@anoncvs.NetBSD.org:/cvsroot
-% setenv CVS_RSH ssh
-% cd /usr
-% cvs checkout -P pkgsrc
+    % setenv CVSROOT anoncvs@anoncvs.NetBSD.org:/cvsroot
+    % setenv CVS_RSH ssh
 
-This will create the pkgsrc directory in your /usr, and all the package source
-will be stored under /usr/pkgsrc. To update pkgsrc after the initial checkout,
-make sure you have CVS_RSH set as above, then do:
+Or, the same for the bourne shell:
 
-% cd /usr/pkgsrc
-% cvs -q update -dP
+    $ CVSROOT="anoncvs@anoncvs.NetBSD.org:/cvsroot"
+    $ CVS_RSH="ssh"
+    $ export CVSROOT CVS_RSH
+
+Then, you change to the directory where you want to have your copy of pkgsrc.
+In most cases this is /usr. In that directory you run the checkout command,
+which is cvs -q checkout -P pkgsrc for the current branch and cvs -q checkout
+-rpkgsrc-2006Q1 -P pkgsrc for the stable branch. This command will create a
+directory called pkgsrc with all the pkgsrc files in it.
+
+2.2. Keeping pkgsrc up-to-date
+
+The preferred way to keep pkgsrc up-to-date is via CVS (which also works if you
+have first installed it via a tar file). It saves bandwidth and hard disk
+activity, compared to downloading the tar file again.
+
+2.2.1. Via tar files
+
+Warning
+
+Updating from tar file cannot detect or preserve any changes you have done to
+your local copy of pkgsrc. Therefore updating via CVS is strongly recommended.
+
+To update pkgsrc from a tar file, download the tar file as explained above.
+Then, make sure that you have not made any changes to the files in the pkgsrc
+directory. Remove the pkgsrc directory and extract the new tar file. Done.
+
+2.2.2. Via CVS
+
+To update pkgsrc via CVS, make sure the environment variable CVS_RSH is set as
+above. Then, change to the pkgsrc directory and run cvs -q update -dP. The "-q"
+option tells cvs to only report those files that have changed. The "-d" option
+fetches new packages (which is curiously not done by default), and the "-P"
+option removes empty directories after everything has been updated.
 
-Please also note that it is possible to have multiple copies of the pkgsrc
-hierarchy in use at any one time - all work is done relatively within the
-pkgsrc tree.
+2.2.2.1. Switching between different pkgsrc branches
 
-2.4. Keeping pkgsrc up-to-date via CVS
+When updating pkgsrc, the CVS program keeps track of the branch you selected.
+But if you, for whatever reason, want to switch from the stable branch to the
+current one, you can do it by adding the option "-A" after the "update"
+keyword. To switch from the current branch back to the stable branch, add the
+"-rpkgsrc-2006Q1" option.
 
-If your copy of pkgsrc contains a lot of CVS directories, you can update it
-using the cvs(1) program. First, cd to the top level directory of pkgsrc. Then
-run cvs -q update -dP, and you're done.
+2.2.2.2. What happens to my changes when updating?
 
-If that doesn't work and the file CVS/Root contains the string ":pserver:", you
-have to run cvs login once to get known to the NetBSD CVS server. The cvs
-utility will then ask you for a password. Just enter "anoncvs". Then try again
-to update.
+When you update pkgsrc, the CVS program will only touch those files that are
+registered in the CVS repository. That means that any packages that you created
+on your own will stay unmodified. If you change files that are managed by CVS,
+later updates will try to merge your changes with those that have been done by
+others. See the CVS manual, chapter "update" for details.
 
 Chapter 3. Using pkgsrc on systems other than NetBSD