regen.

1 files changed, 104 insertions, 53 deletions

diff --git a/doc/pkgsrc.txt b/doc/pkgsrc.txt
index 9c56a1178f5..e4590b309ca 100644
--- a/doc/pkgsrc.txt
+++ b/doc/pkgsrc.txt
@@ -12,15 +12,16 @@ Hubert Feyrer
 
 The pkgsrc Developers
 
-Copyright (C) 1994-2005 The NetBSD Foundation, Inc
+Copyright (C) 1994-2006 The NetBSD Foundation, Inc
 
-$NetBSD: pkgsrc.xml,v 1.16 2006/05/12 23:03:22 rillig Exp $
+$NetBSD: pkgsrc.xml,v 1.18 2006/05/19 22:05:09 rillig Exp $
 
 Abstract
 
-Information about using the NetBSD package system (pkgsrc) from both a user
-view for installing packages as well as from a pkgsrc developers' view for
-creating new packages.
+pkgsrc is a centralized package management system for Unix-like operating
+systems. This guide provides information for users and developers of pkgsrc. It
+covers installation of binary and source packages, creation of binary and
+source packages and a high-level overview about the infrastructure.
 
 -------------------------------------------------------------------------------
 
@@ -31,6 +32,9 @@ Table of Contents
     1.1. Introduction
     1.2. Overview
     1.3. Terminology
+
+        1.3.1. People involved in pkgsrc
+
     1.4. Typography
 
 I. The pkgsrc user's guide
@@ -114,6 +118,7 @@ I. The pkgsrc user's guide
         7.13. Using 'sudo' with pkgsrc
         7.14. How do I change the location of configuration files?
         7.15. Automated security checks
+        7.16. Why do some packages ignore my CFLAGS?
 
 II. The pkgsrc developer's guide
 
@@ -283,11 +288,12 @@ II. The pkgsrc developer's guide
     17. Debugging
     18. Submitting and Committing
 
-        18.1. Submitting your packages
-        18.2. General notes when adding, updating, or removing packages
-        18.3. Committing: Importing a package into CVS
-        18.4. Updating a package to a newer version
-        18.5. Moving a package in pkgsrc
+        18.1. Submitting binary packages
+        18.2. Submitting source packages (for non-NetBSD-developers)
+        18.3. General notes when adding, updating, or removing packages
+        18.4. Committing: Importing a package into CVS
+        18.5. Updating a package to a newer version
+        18.6. Moving a package in pkgsrc
 
     19. Frequently Asked Questions
 
@@ -348,6 +354,9 @@ Table of Contents
 1.1. Introduction
 1.2. Overview
 1.3. Terminology
+
+    1.3.1. People involved in pkgsrc
+
 1.4. Typography
 
 1.1. Introduction
@@ -463,6 +472,32 @@ Program
     the files in the distfile by the actions defined in the corresponding
     package.
 
+1.3.1. People involved in pkgsrc
+
+pkgsrc users
+
+    The pkgsrc users are people who use the packages provided by pkgsrc.
+    Typically they are system administrators. The people using the software
+    that is inside the packages (maybe called "end users") are not covered by
+    the pkgsrc guide.
+
+    There are two kinds of pkgsrc users: Some only want to install pre-built
+    binary packages. Others build the pkgsrc packages from source, either for
+    installing them directly or for building binary packages themselves. For
+    pkgsrc users Part I, "The pkgsrc user's guide" should provide all necessary
+    documentation.
+
+package maintainers
+
+    A package maintainer creates packages as described in Part II, "The pkgsrc
+    developer's guide".
+
+infrastructure developers
+
+    These people are involved in all those files that live in the mk/ directory
+    and below. Only these people should need to read through Part III, "The
+    pkgsrc infrastructure internals", though others might be curious, too.
+
 1.4. Typography
 
 When giving examples for commands, shell prompts are used to show if the
@@ -552,6 +587,7 @@ Table of Contents
     7.13. Using 'sudo' with pkgsrc
     7.14. How do I change the location of configuration files?
     7.15. Automated security checks
+    7.16. Why do some packages ignore my CFLAGS?
 
 Chapter 2. Where to get pkgsrc and how to keep it up-to-date
 
@@ -2015,6 +2051,7 @@ Table of Contents
 7.13. Using 'sudo' with pkgsrc
 7.14. How do I change the location of configuration files?
 7.15. Automated security checks
+7.16. Why do some packages ignore my CFLAGS?
 
 This section contains hints, tips & tricks on special things in pkgsrc that we
 didn't find a better place for in the previous chapters, and it contains items
@@ -2335,6 +2372,20 @@ If this package is installed, pkgsrc builds will use it to perform a security
 check before building any package. See Section 5.2, "Variables affecting the
 build process" for ways to control this check.
 
+7.16. Why do some packages ignore my CFLAGS?
+
+When you add your own preferences to the CFLAGS variable in your mk.conf, these
+flags are passed in environment variables to the ./configure scripts and to
+make(1). Some package authors ignore the CFLAGS from the environment variable
+by overriding them in the Makefiles of their package.
+
+Currently there is no solution to this problem. If you really need the package
+to use your CFLAGS you should run make patch in the package directory and then
+inspect any Makefile and Makefile.in for whether they define CFLAGS explicitly.
+Usually you can remove these lines. But be aware that some "smart" programmers
+write so bad code that it only works for the specific combination of CFLAGS
+they have chosen.
+
 Part II. The pkgsrc developer's guide
 
 Table of Contents
@@ -2504,11 +2555,12 @@ Table of Contents
 17. Debugging
 18. Submitting and Committing
 
-    18.1. Submitting your packages
-    18.2. General notes when adding, updating, or removing packages
-    18.3. Committing: Importing a package into CVS
-    18.4. Updating a package to a newer version
-    18.5. Moving a package in pkgsrc
+    18.1. Submitting binary packages
+    18.2. Submitting source packages (for non-NetBSD-developers)
+    18.3. General notes when adding, updating, or removing packages
+    18.4. Committing: Importing a package into CVS
+    18.5. Updating a package to a newer version
+    18.6. Moving a package in pkgsrc
 
 19. Frequently Asked Questions
 
@@ -2852,7 +2904,7 @@ When a variable's value is parsed from a Makefile, the hash character ``#'' and
 the backslash character ``\'' are handled specially. If a backslash is followed
 by a newline, any whitespace immediately in front of the backslash, the
 backslash, the newline, and any whitespace immediately behind the newline are
-replaced with a single space. A backspace character and an immediately
+replaced with a single space. A backslash character and an immediately
 following hash character are replaced with a single hash character. Otherwise,
 the backslash is passed as is. In a variable assignment, any hash character
 that is not preceded by a backslash starts a comment that continues upto the
@@ -5119,10 +5171,12 @@ download it. graphics/ns-cult3d is an example of this usage.
 
 If the download can't be automated, because the user must submit personal
 information to apply for a password, or must pay for the source, or whatever,
-you can set _FETCH_MESSAGE to a macro which displays a message explaining the
-situation. _FETCH_MESSAGE must be executable shell commands, not just a
-message. (Generally, it executes ${ECHO}). See one of the following packages
-for an example: fonts/acroread-jpnfont, sysutils/storage-manager.
+you can set FETCH_MESSAGE to a list of lines that are displayed to the user
+before aborting the build. Example:
+
+    FETCH_MESSAGE=  "Please download the files"
+    FETCH_MESSAGE+= "    "${DISTFILES:Q}
+    FETCH_MESSAGE+= "manually from "${MASTER_SITES:Q}"."
 
 16.2.2. How to handle modified distfiles with the 'old' name
 
@@ -5870,43 +5924,40 @@ Chapter 18. Submitting and Committing
 
 Table of Contents
 
-18.1. Submitting your packages
-18.2. General notes when adding, updating, or removing packages
-18.3. Committing: Importing a package into CVS
-18.4. Updating a package to a newer version
-18.5. Moving a package in pkgsrc
-
-18.1. Submitting your packages
-
-You have to separate between binary and "normal" (source) packages here:
+18.1. Submitting binary packages
+18.2. Submitting source packages (for non-NetBSD-developers)
+18.3. General notes when adding, updating, or removing packages
+18.4. Committing: Importing a package into CVS
+18.5. Updating a package to a newer version
+18.6. Moving a package in pkgsrc
 
-  * precompiled binary packages
+18.1. Submitting binary packages
 
-    Our policy is that we accept binaries only from pkgsrc developers to
-    guarantee that the packages don't contain any trojan horses etc. This is
-    not to annoy anyone but rather to protect our users! You're still free to
-    put up your home-made binary packages and tell the world where to get them.
-    NetBSD developers doing bulk builds and wanting to upload them please see
-    Section 6.3.8, "Uploading results of a bulk build".
+Our policy is that we accept binaries only from pkgsrc developers to guarantee
+that the packages don't contain any trojan horses etc. This is not to annoy
+anyone but rather to protect our users! You're still free to put up your
+home-made binary packages and tell the world where to get them. NetBSD
+developers doing bulk builds and wanting to upload them please see
+Section 6.3.8, "Uploading results of a bulk build".
 
-  * packages
+18.2. Submitting source packages (for non-NetBSD-developers)
 
-    First, check that your package is complete, compiles and runs well; see
-    Chapter 17, Debugging and the rest of this document. Next, generate an
-    uuencoded gzipped tar(1) archive, preferably with all files in a single
-    directory. Finally, send-pr with category "pkg", a synopsis which includes
-    the package name and version number, a short description of your package
-    (contents of the COMMENT variable or DESCR file are OK) and attach the
-    archive to your PR.
+First, check that your package is complete, compiles and runs well; see
+Chapter 17, Debugging and the rest of this document. Next, generate an
+uuencoded gzipped tar(1) archive, preferably with all files in a single
+directory. Finally, send-pr with category "pkg", a synopsis which includes the
+package name and version number, a short description of your package (contents
+of the COMMENT variable or DESCR file are OK) and attach the archive to your
+PR.
 
-    If you want to submit several packages, please send a separate PR for each
-    one, it's easier for us to track things that way.
+If you want to submit several packages, please send a separate PR for each one,
+it's easier for us to track things that way.
 
-    Alternatively, you can also import new packages into pkgsrc-wip ("pkgsrc
-    work-in-progress"); see the homepage at http://pkgsrc-wip.sourceforge.net/
-    for details.
+Alternatively, you can also import new packages into pkgsrc-wip ("pkgsrc
+work-in-progress"); see the homepage at http://pkgsrc-wip.sourceforge.net/ for
+details.
 
-18.2. General notes when adding, updating, or removing packages
+18.3. General notes when adding, updating, or removing packages
 
 Please note all package additions, updates, moves, and removals in pkgsrc/doc/
 CHANGES. It's very important to keep this file up to date and conforming to the
@@ -5930,7 +5981,7 @@ or package moves or removals, set the CTYPE variable on the command line to
 if your local login name is not the same as your NetBSD login name. Don't
 forget to commit the changes to pkgsrc/doc/CHANGES!
 
-18.3. Committing: Importing a package into CVS
+18.4. Committing: Importing a package into CVS
 
 This section is only of interest for pkgsrc developers with write access to the
 pkgsrc repository. Please remember that cvs imports files relative to the
@@ -5952,7 +6003,7 @@ so people reading the mailing lists know what the package is/does.
 For new packages, "cvs import" is preferred to "cvs add" because the former
 gets everything with a single command, and provides a consistent tag.
 
-18.4. Updating a package to a newer version
+18.5. Updating a package to a newer version
 
 Please always put a concise, appropriate and relevant summary of the changes
 between old and new versions into the commit log when updating a package. There
@@ -5977,7 +6028,7 @@ which pkgsrc is used. Please use your judgement about what should go into
 pkgsrc, and bear in mind that stability is to be preferred above new and
 possibly untested features.
 
-18.5. Moving a package in pkgsrc
+18.6. Moving a package in pkgsrc
 
  1. Make a copy of the directory somewhere else.