regen

1 files changed, 88 insertions, 81 deletions

diff --git a/doc/pkgsrc.txt b/doc/pkgsrc.txt
index bf207b1c07c..36966b811a0 100644
--- a/doc/pkgsrc.txt
+++ b/doc/pkgsrc.txt
@@ -518,7 +518,7 @@ pkgsrc provides the following key features:
 
   * Like NetBSD, pkgsrc is designed with portability in mind and consists of
     highly portable code. This allows the greatest speed of development when
-    porting to new a platform. This portability also ensures that pkgsrc is
+    porting to new a platform. This portability also ensures that pkgsrc is 
     consistent across all platforms.
 
   * The installation prefix, acceptable software licenses, international
@@ -825,7 +825,7 @@ underscores and dashes.
 
 2.1. Getting pkgsrc for the first time
 
-Before you download any pkgsrc files, you should decide whether you want the
+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
@@ -850,8 +850,8 @@ To download a pkgsrc stable tarball, run:
 
 $ ftp ftp://ftp.NetBSD.org/pub/pkgsrc/pkgsrc-20xxQy/pkgsrc-20xxQy.tar.gz
 
-Where pkgsrc-20xxQy is the stable branch to be downloaded, for example,
-"pkgsrc-2009Q1".
+Where pkgsrc-20xxQy is the stable branch to be downloaded, for example, "
+pkgsrc-2009Q1".
 
 Then, extract it with:
 
@@ -870,8 +870,8 @@ To fetch a specific pkgsrc stable branch, run:
 
 $ cd /usr && cvs -q -z3 -d anoncvs@anoncvs.NetBSD.org:/cvsroot checkout -r pkgsrc-20xxQy -P pkgsrc
 
-Where pkgsrc-20xxQy is the stable branch to be checked out, for example,
-"pkgsrc-2009Q1"
+Where pkgsrc-20xxQy is the stable branch to be checked out, for example, "
+pkgsrc-2009Q1"
 
 This will create the directory pkgsrc/ in your /usr/ directory and all the
 package source will be stored under /usr/pkgsrc/.
@@ -948,8 +948,8 @@ $ cvs update -dP
 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-2009Q3" option.
+keyword. To switch from the current branch back to the stable branch, add the "
+-rpkgsrc-2009Q3" option.
 
 2.2.2.2. What happens to my changes when updating?
 
@@ -1506,7 +1506,7 @@ After these preparations, installing a package is very easy:
 Note that any prerequisite packages needed to run the package in question will
 be installed, too, assuming they are present where you install from.
 
-Adding packages might install vulnerable packages. Thus you should run
+Adding packages might install vulnerable packages. Thus you should run 
 pkg_admin audit regularly, especially after installing new packages, and verify
 that the vulnerabilities are acceptable for your configuration.
 
@@ -1604,7 +1604,7 @@ involved.
 4.2. Building packages from source
 
 After obtaining pkgsrc, the pkgsrc directory now contains a set of packages,
-organized into categories. You can browse the online index of packages, or run
+organized into categories. You can browse the online index of packages, or run 
 make readme from the pkgsrc directory to build local README.html files for all
 packages, viewable with any web browser such as www/lynx or www/firefox.
 
@@ -1741,8 +1741,8 @@ added to help with this.
 
     make patch PKG_DEBUG_LEVEL=2
 
-    will show all the commands that are invoked, up to and including the
-    "patch" stage.
+    will show all the commands that are invoked, up to and including the "patch
+    " stage.
 
  2. If you want to know the value of a certain make(1) definition, then the
     VARNAME definition should be used, in conjunction with the show-var target.
@@ -2174,8 +2174,8 @@ others must survive a sudden reboot.
 
 Note
 
-There are two ways of doing a bulk build. The old-style one and the new-style
-"pbulk". The latter is the recommended way.
+There are two ways of doing a bulk build. The old-style one and the new-style "
+pbulk". The latter is the recommended way.
 
 7.3.1. Configuration
 
@@ -2208,7 +2208,7 @@ Some options that are especially useful for bulk builds can be found at the top
 lines of the file mk/bulk/bsd.bulk-pkg.mk. The most useful options of these are
 briefly described here.
 
-  * If you are on a slow machine, you may want to set USE_BULK_BROKEN_CHECK to
+  * If you are on a slow machine, you may want to set USE_BULK_BROKEN_CHECK to 
     "no".
 
   * If you are doing bulk builds from a read-only copy of pkgsrc, you have to
@@ -2228,8 +2228,8 @@ Some other options are scattered in the pkgsrc infrastructure:
   * CHECK_FILES (pkgsrc/mk/check/check-files.mk) can be set to "yes" to check
     that the installed set of files matches the PLIST.
 
-  * CHECK_INTERPRETER (pkgsrc/mk/check/check-interpreter.mk) can be set to
-    "yes" to check that the installed "#!"-scripts will find their interpreter.
+  * CHECK_INTERPRETER (pkgsrc/mk/check/check-interpreter.mk) can be set to "yes
+    " to check that the installed "#!"-scripts will find their interpreter.
 
   * PKGSRC_RUN_TEST can be set to "yes" to run each package's self-test before
     installing it. Note that some packages make heavy use of "good" random
@@ -2649,8 +2649,8 @@ PKG_DBDIR=              ${HOME}/pkg/var/db/pkg
 What these four directories are for, and what they look like is explained
 below.
 
-  * LOCALBASE corresponds to the /usr directory in the base system. It is the
-    "main" directory where the files are installed and contains the well-known
+  * LOCALBASE corresponds to the /usr directory in the base system. It is the "
+    main" directory where the files are installed and contains the well-known
     subdirectories like bin, include, lib, share and sbin.
 
   * VARBASE corresponds to /var in the base system. Some programs (especially
@@ -3099,10 +3099,10 @@ they have chosen.
     there are sometimes changes that only work when the whole pkgsrc tree is
     updated.
 
- 2. Make sure that you don't have any CVS conflicts. Search for "<<<<<<" or
-    ">>>>>>" in all your pkgsrc files.
+ 2. Make sure that you don't have any CVS conflicts. Search for "<<<<<<" or "
+    >>>>>>" in all your pkgsrc files.
 
- 3. Make sure that you don't have old copies of the packages extracted. Run
+ 3. Make sure that you don't have old copies of the packages extracted. Run 
     make clean clean-depends to verify this.
 
  4. If the problem still exists, write a mail to the pkgsrc-users mailing list.
@@ -3425,7 +3425,7 @@ package involves only a few steps.
  8. Now, run bmake to build the package. For the various things that can go
     wrong in this phase, consult Chapter 19, Making your package work.
 
- 9. When the package builds fine, the next step is to install the package. Run
+ 9. When the package builds fine, the next step is to install the package. Run 
     bmake install and hope that everything works.
 
 10. Up to now, the file PLIST, which contains a list of the files that are
@@ -3473,8 +3473,8 @@ to work with, from the most recent to the older one, e.g.
 PYTHON_VERSIONS_ACCEPTED=       25 24
 
 If the packaged software is a Python module, include "../../lang/python/
-extension.mk". In this case, the package directory should be called
-"py-software" and PKGNAME should be set to "${PYPKGPREFIX}-${DISTNAME}", e.g.
+extension.mk". In this case, the package directory should be called "
+py-software" and PKGNAME should be set to "${PYPKGPREFIX}-${DISTNAME}", e.g.
 
 DISTNAME=   foopymodule-1.2.10
 PKGNAME=    ${PYPKGPREFIX}-${DISTNAME}
@@ -3847,8 +3847,7 @@ supported by pkgsrc. Therefore, a number of custom patch files are needed to
 make the package work. These patch files are found in the patches/ directory.
 
 In the patch phase, these patches are applied to the files in WRKSRC directory
-after extracting them, in alphabetic order, so patch-aa is applied before
-patch-ab, etc.
+after extracting them, in alphabetic order.
 
 11.3.1. Structure of a single patch file
 
@@ -3863,19 +3862,16 @@ Id of the patch itself. The second line should be empty for aesthetic reasons.
 After that, there should be a comment for each change that the patch does.
 There are a number of standard cases:
 
-  * Patches that replace the == operator for test(1) with = in shell scripts
-    are so common that they don't need a comment at all.
-
   * Patches for commonly known vulnerabilities should mention the vulnerability
     ID (CAN, CVE).
 
   * Patches that change source code should mention the platform and other
     environment (for example, the compiler) that the patch is needed for.
 
-In all other cases, the patch should be commented so that any developer who
-knows the code of the application can make some use of the patch. Special care
-should be taken for the upstream developers, since we generally want that they
-accept our patches, so we have less work in the future.
+In all, the patch should be commented so that any developer who knows the code
+of the application can make some use of the patch. Special care should be taken
+for the upstream developers, since we generally want that they accept our
+patches, so we have less work in the future.
 
 11.3.2. Creating patch files
 
@@ -3886,11 +3882,11 @@ avoid these problems.
 
 For even more automation, we recommend using mkpatches from the same package to
 make a whole set of patches. You just have to backup files before you edit them
-to filename.orig, e.g. with cp -p filename filename.orig or, easier, by using
+to filename.orig, e.g. with cp -p filename filename.orig or, easier, by using 
 pkgvi again from the same package. If you upgrade a package this way, you can
-easily compare the new set of patches with the previously existing one with
-patchdiff. Copy the patches you want to use or update from the work/.newpatches
-directory to patches/.
+easily compare the new set of patches with the previously existing one with 
+patchdiff. The files in patches are replaced by new files, so carefully check
+if you want to take all the changes.
 
 When you have finished a package, remember to generate the checksums for the
 patch files by using the make makepatchsum command, see Section 11.2,
@@ -3901,7 +3897,11 @@ enforcing pkgsrc's view of where man pages should go), send the patch as a bug
 report to the maintainer. This benefits non-pkgsrc users of the package, and
 usually makes it possible to remove the patch in future version.
 
-The file names of the patch files are usually of the form patch-[a-z][a-z].
+The file names of the patch files are usually of the form patch-
+path_to_file__with__underscores.c. Many packages still use the previous
+convention patch-[a-z][a-z], but new patches should be of the form containing
+the filename. mkpatches included in pkgtools/pkgdiff takes care of the name
+automatically.
 
 11.3.3. Sources where the patch files come from
 
@@ -3994,6 +3994,9 @@ to accept your changes. It is extremely important that you do it so that the
 packages in pkgsrc are kept simple and thus further changes can be done without
 much hassle.
 
+When you have done this, please add a URL to the upstream bug report to the
+patch comment.
+
 Support the idea of free software!
 
 11.4. Other mandatory files
@@ -4597,8 +4600,8 @@ package build from non-system-supplied software.
 
 14.1. Converting packages to use buildlink3
 
-The process of converting packages to use the buildlink3 framework
-("bl3ifying") is fairly straightforward. The things to keep in mind are:
+The process of converting packages to use the buildlink3 framework ("bl3ifying"
+) is fairly straightforward. The things to keep in mind are:
 
  1. Ensure that the build always calls the wrapper scripts instead of the
     actual toolchain. Some packages are tricky, and the only way to know for
@@ -4861,7 +4864,7 @@ The third section sets USE_BUILTIN.pkg and is required in all builtin.mk files.
 The code in this section must make the determination whether the built-in
 software is adequate to satisfy the dependencies listed in
 BUILDLINK_API_DEPENDS.pkg. This is typically done by comparing BUILTIN_PKG.pkg
-against each of the dependencies in BUILDLINK_API_DEPENDS.pkg. USE_BUILTIN.pkg
+against each of the dependencies in BUILDLINK_API_DEPENDS.pkg. USE_BUILTIN.pkg 
 must be set to the correct value by the end of the builtin.mk file. Note that
 USE_BUILTIN.pkg may be "yes" even if IS_BUILTIN.pkg is "no" because we may make
 the determination that the built-in version of the software is similar enough
@@ -4877,8 +4880,8 @@ additional files to symlink into ${BUILDLINK_DIR} (via BUILDLINK_FILES.pkg).
 When building packages, it's possible to choose whether to set a global
 preference for using either the built-in (native) version or the pkgsrc version
 of software to satisfy a dependency. This is controlled by setting
-PREFER_PKGSRC and PREFER_NATIVE. These variables take values of either "yes",
-"no", or a list of packages. PREFER_PKGSRC tells pkgsrc to use the pkgsrc
+PREFER_PKGSRC and PREFER_NATIVE. These variables take values of either "yes", "
+no", or a list of packages. PREFER_PKGSRC tells pkgsrc to use the pkgsrc
 versions of software, while PREFER_NATIVE tells pkgsrc to use the built-in
 versions. Preferences are determined by the most specific instance of the
 package in either PREFER_PKGSRC or PREFER_NATIVE. If a package is specified in
@@ -5509,8 +5512,8 @@ for more details.
 When choosing which of these variables to use, follow the following rules:
 
   * PREFIX always points to the location where the current pkg will be
-    installed. When referring to a pkg's own installation path, use "${PREFIX}
-    ".
+    installed. When referring to a pkg's own installation path, use "${PREFIX}"
+    .
 
   * LOCALBASE 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
@@ -5536,7 +5539,7 @@ When choosing which of these variables to use, follow the following rules:
     either USE_X11BASE or USE_IMAKE in your package.
 
     Some notes: If you need to find includes or libraries installed by a pkg
-    that has USE_IMAKE or USE_X11BASE in its pkg Makefile, you need to look in
+    that has USE_IMAKE or USE_X11BASE in its pkg Makefile, you need to look in 
     both ${X11BASE} and ${LOCALBASE}. To force installation of all X11 packages
     in LOCALBASE, the pkgtools/xpkgwedge package is enabled by default.
 
@@ -5627,7 +5630,7 @@ installed.
 17.5. The fetch phase
 
 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
+(distfiles) from the sites that are providing them. This is the task of the 
 fetch phase.
 
 17.5.1. What to fetch and where to get it from
@@ -5883,9 +5886,9 @@ these directories, MAKE_PROGRAM is run with the environment MAKE_ENV and
 arguments BUILD_MAKE_FLAGS. The variables MAKE_ENV, BUILD_MAKE_FLAGS, MAKE_FILE
 and BUILD_TARGET may all be changed by the package.
 
-The default value of MAKE_PROGRAM is "gmake" if USE_TOOLS contains "gmake",
-"make" otherwise. The default value of MAKE_FILE is "Makefile", and
-BUILD_TARGET defaults to "all".
+The default value of MAKE_PROGRAM is "gmake" if USE_TOOLS contains "gmake", "
+make" otherwise. The default value of MAKE_FILE is "Makefile", and BUILD_TARGET
+defaults to "all".
 
 If there is no build step at all, set NO_BUILD to "yes".
 
@@ -5978,7 +5981,7 @@ INSTALLATION_DIRS
     needed directories itself before installing files to it and list all other
     directories here.
 
-In the rare cases that a package shouldn't install anything, set NO_INSTALL to
+In the rare cases that a package shouldn't install anything, set NO_INSTALL to 
 "yes". This is mostly relevant for packages in the regress category.
 
 17.15. The package phase
@@ -6041,8 +6044,8 @@ deinstall
         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 make deinstall DEINSTALLDEPENDS=1 is done in
-        pkgsrc/x11/kde, this is likely to remove whole KDE. Works by adding
-        "-R" to the pkg_delete(1) command line.
+        pkgsrc/x11/kde, this is likely to remove whole KDE. Works by adding "-R
+        " to the pkg_delete(1) command line.
 
 bin-install
 
@@ -6078,16 +6081,16 @@ update
 
         Install target to recursively use for the updated package and the
         dependent packages. Defaults to DEPENDS_TARGET if set, "install"
-        otherwise for make update. Other good targets are "package" or
-        "bin-install". Do not set this to "update" or you will get stuck in an
+        otherwise for make update. Other good targets are "package" or "
+        bin-install". Do not set this to "update" or you will get stuck in an
         endless loop!
 
     NOCLEAN
 
         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
-        "clean-update" target below) or you may run into troubles with old
+        purposes. Be sure you eventually clean up the source tree (see the "
+        clean-update" target below) or you may run into troubles with old
         source code still lying around on your next make or make update.
 
     REINSTALL
@@ -6111,7 +6114,7 @@ clean-update
     update 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 make update) or you may lose some
-    packages you intended to update. As a rule of thumb: only use this target
+    packages you intended to update. As a rule of thumb: only use this target 
     before the first time you run make update and only if you have a dirty
     package tree (e.g., if you used NOCLEAN).
 
@@ -6219,8 +6222,8 @@ show-pkgsrc-dir
     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
-    "show-host-specific-pkgs" target.
+    can be invoked from the top-level pkgsrc Makefile by using the "
+    show-host-specific-pkgs" target.
 
 show-installed-depends
 
@@ -6263,7 +6266,7 @@ bulk-package
 bulk-install
 
     Used during bulk-installs to install required packages. If an up-to-date
-    binary package is available, it will be installed via pkg_add(1). If not,
+    binary package is available, it will be installed via pkg_add(1). If not, 
     make bulk-package will be executed, but the installed binary won't be
     removed.
 
@@ -6797,8 +6800,8 @@ not met, set PKG_FAIL_REASON to a descriptive message.
 
 To ensure that a package may not be deleted, once it has been installed, the
 PKG_PRESERVE definition should be set in the package Makefile. This will be
-carried into any binary package that is made from this pkgsrc entry. A
-"preserved" package will not be deleted using pkg_delete(1) unless the "-f"
+carried into any binary package that is made from this pkgsrc entry. A "
+preserved" package will not be deleted using pkg_delete(1) unless the "-f"
 option is used.
 
 19.1.10. Handling packages with security problems
@@ -7021,8 +7024,8 @@ Here's how to use libtool in a package in seven simple steps:
 
 
     The "-release" option will produce different results for a.out and ELF
-    (excluding symlinks) in only one case. An ELF library of the form
-    "libfoo-release.so.x.y" will have a symlink of "libfoo.so.x.y" on an a.out
+    (excluding symlinks) in only one case. An ELF library of the form "
+    libfoo-release.so.x.y" will have a symlink of "libfoo.so.x.y" on an a.out
     platform. This is handled automatically.
 
     The "-rpath argument" is the install directory of the library being built.
@@ -7167,6 +7170,10 @@ variables:
     implementation, "1.4" insists on versions 1.4 or above, and "1.5" only
     accepts versions 1.5 or above. This variable is not set by default.
 
+  * PKG_JAVA_HOME is automatically set to the runtime location of the used Java
+    implementation dependency. It may be used to set JAVA_HOME to a good value
+    if the program needs this variable to be defined.
+
 19.4.3. Packages containing perl scripts
 
 If your package contains interpreted perl scripts, add "perl" to the USE_TOOLS
@@ -7374,8 +7381,8 @@ but rely on INSTALL_GAME and INSTALL_GAME_DATA to set these correctly.
 DESTDIR support means that a package installs into a staging directory, not the
 final location of the files. Then a binary package is created which can be used
 for installation as usual. There are two ways: Either the package must install
-as root ("destdir") or the package can install as non-root user
-("user-destdir").
+as root ("destdir") or the package can install as non-root user ("user-destdir"
+).
 
   * PKG_DESTDIR_SUPPORT has to be set to "destdir" or "user-destdir". If
     bsd.prefs.mk is included in the Makefile, PKG_DESTDIR_SUPPORT needs to be
@@ -7453,7 +7460,7 @@ build dependency on the devel/gtexinfo package will be added automatically.
 
 The build and installation process of the software provided by the package
 should not use the install-info command as the registration of info files is
-the task of the package INSTALL script, and it must use the appropriate
+the task of the package INSTALL script, and it must use the appropriate 
 makeinfo command.
 
 To achieve this goal, the pkgsrc infrastructure creates overriding scripts for
@@ -7469,8 +7476,8 @@ error.
 All packages that install manual pages should install them into the same
 directory, so that there is one common place to look for them. In pkgsrc, this
 place is ${PREFIX}/${PKGMANDIR}, and this expression should be used in
-packages. The default for PKGMANDIR is "man". Another often-used value is
-"share/man".
+packages. The default for PKGMANDIR is "man". Another often-used value is "
+share/man".
 
 Note
 
@@ -7610,7 +7617,7 @@ ensure that the database is kept consistent with respect to these new files:
     MIME database at installation and deinstallation time, and disallows any
     access to it directly from the package.
 
- 2. Check the PLIST and remove any entries under the share/mime directory,
+ 2. Check the PLIST and remove any entries under the share/mime directory, 
     except for files saved under share/mime/packages. The former are handled
     automatically by the update-mime-database program, but the latter are
     package-dependent and must be removed by the package that installed them in
@@ -7835,8 +7842,8 @@ package is also available as a substitute for either of the above two tools.
 In the form of the problem report, the category should be "pkg", the synopsis
 should include the package name and version number, and the description field
 should contain a short description of your package (contents of the COMMENT
-variable or DESCR file are OK). The uuencoded package data should go into the
-"fix" field.
+variable or DESCR file are OK). The uuencoded package data should go into the "
+fix" field.
 
 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.
@@ -7950,7 +7957,7 @@ follow these steps.
 
     and use that for further work.
 
- 3. Fix CATEGORIES and any DEPENDS paths that just did "../package" instead of
+ 3. Fix CATEGORIES and any DEPENDS paths that just did "../package" instead of 
     "../../category/package".
 
  4. In the modified package's Makefile, consider setting PREV_PKGPATH to the
@@ -8029,8 +8036,8 @@ pkgsrc-users mailing list.
 
 22.5. Why does make show-var VARNAME=BUILDLINK_PREFIX.foo say it's empty?
 
-      For optimization reasons, some variables are only available in the
-      "wrapper" phase and later. To "simulate" the wrapper phase, append
+      For optimization reasons, some variables are only available in the "
+      wrapper" phase and later. To "simulate" the wrapper phase, append 
       PKG_PHASE=wrapper to the above command.
 
 22.6. What does ${MASTER_SITE_SOURCEFORGE:=package/} mean? I don't understand
@@ -8176,7 +8183,7 @@ pkgsrc includes three GNOME-related meta packages:
 
 In all these packages, the DEPENDS lines are sorted in a way that eases
 updates: a package may depend on other packages listed before it but not on any
-listed after it. It is very important to keep this order to ease updates so...
+listed after it. It is very important to keep this order to ease updates so... 
 do not change it to alphabetical sorting!
 
 23.2. Packaging a GNOME application
@@ -8231,7 +8238,7 @@ those, your package is most likely incorrect.
 
 The following table lists the common situations that result in using shared
 directories or files. For each of them, the appropriate solution is given.
-After applying the solution be sure to regenerate the package's file list with
+After applying the solution be sure to regenerate the package's file list with 
 make print-PLIST and ensure it is correct.
 
 Table 23.1. PLIST handling for GNOME packages
@@ -8645,7 +8652,7 @@ how regression tests work in pkgsrc and how you can add new tests.
 
 25.2. Running the regression tests
 
-You first need to install the pkgtools/pkg_regress package, which provides the
+You first need to install the pkgtools/pkg_regress package, which provides the 
 pkg_regress command. Then you can simply run that command, which will run all
 tests in the regress category.
 
@@ -8779,7 +8786,7 @@ A.1. files
 A.2. Steps for building, installing, packaging
 
 We checked to find a piece of software that wasn't in the packages collection,
-and picked GNU bison. Quite why someone would want to have bison when Berkeley
+and picked GNU bison. Quite why someone would want to have bison when Berkeley 
 yacc is already present in the tree is beyond us, but it's useful for the
 purposes of this exercise.