doc/pkgsrc.*: regen

1 files changed, 36 insertions, 23 deletions

diff --git a/doc/pkgsrc.txt b/doc/pkgsrc.txt
index 92211385a34..31f1534d5aa 100644
--- a/doc/pkgsrc.txt
+++ b/doc/pkgsrc.txt
@@ -5197,10 +5197,10 @@ buildlink3.mk files and is used to track the dependency tree.
 The main section is protected from multiple inclusion and controls how the
 dependency on pkg is added. Several important variables are set in the section:
 
-  * BUILDLINK_API_DEPENDS.pkg is the actual dependency recorded in the
+  * BUILDLINK_API_DEPENDS.pkg is the dependency version recorded in the
     installed package; this should always be set using += to ensure that we're
     appending to any pre-existing list of values. This variable should be set
-    to the first version of the package that had an backwards-incompatible API
+    to the last version of the package that had an backwards-incompatible API
     change.
 
   * BUILDLINK_PKGSRCDIR.pkg is the location of the pkg pkgsrc directory.
@@ -5272,31 +5272,40 @@ included:
 18.2.2. Updating BUILDLINK_API_DEPENDS.pkg and BUILDLINK_ABI_DEPENDS.pkg in
 buildlink3.mk files
 
-These two variables differ in that one describes source compatibility (API) and
-the other binary compatibility (ABI). The difference is that a change in the
-API breaks compilation of programs while changes in the ABI stop compiled
-programs from running.
-
-Changes to the BUILDLINK_API_DEPENDS.pkg variable in a buildlink3.mk file
-happen very rarely. One possible reason is that all packages depending on this
-already need a newer version. In case it is bumped see the description below.
-
-The most common example of an ABI change is that the major version of a shared
-library is increased. In this case, BUILDLINK_ABI_DEPENDS.pkg should be
-adjusted to require at least the new package version. Then the packages that
-depend on this package need their PKGREVISIONs increased and, if they have
-buildlink3.mk files, their BUILDLINK_ABI_DEPENDS.pkg adjusted, too. This is
-needed so pkgsrc will require the correct package dependency and not settle for
-an older one when building the source.
+Both variables set lower bounds for a version of this package. The two
+variables differ in that one describes source compatibility (API) and the other
+binary compatibility (ABI). The difference is that a change in the API breaks
+compilation of programs while changes in the ABI stop compiled programs from
+running.
+
+The BUILDLINK_API_DEPENDS.pkg variable in a buildlink3.mk should be changed
+very rarely. (One possible scenario: If all packages using this package need a
+higher version than defined in the buildlink3.mk, BUILDLINK_API_DEPENDS.pkg
+could be updated to that higher version.)
+
+On the other hand, changes to BUILDLINK_ABI_DEPENDS.pkg are more common. The
+variable will need to be updated every time the major version of one of its
+shared libraries is changed, or any other change where a binary built against
+the previous version of the package will not run against the new version any
+longer.
+
+In such a case, the package's BUILDLINK_ABI_DEPENDS.pkg must be increased to
+require the new package version. Then the PKGREVISION of all packages foo that
+depend on this package need to be increased, and if they have buildlink3.mk
+files, BUILDLINK_ABI_DEPENDS.foo in their buildlink3.mk files must be increased
+to the new version as well. This is required so that a package will pull in the
+versions of the packages that use the new ABI and that the packages'
+PKGREVISIONs uniquely identify the packages built against the new ABI. The
+pkgtools/revbump package can help with these updates.
 
 See Section 21.1.5, "Handling dependencies" for more information about
-dependencies on other packages, including the BUILDLINK_ABI_DEPENDS and
-ABI_DEPENDS definitions.
+dependencies on other packages, including the BUILDLINK_API_DEPENDS
+definitions.
 
 Please take careful consideration before adjusting BUILDLINK_API_DEPENDS.pkg or
-BUILDLINK_ABI_DEPENDS.pkg as we don't want to cause unneeded package deletions
-and rebuilds. In many cases, new versions of packages work just fine with older
-dependencies.
+BUILDLINK_ABI_DEPENDS.pkg in a buildlink3.mk file as we don't want to cause
+unneeded package deletions and rebuilds. In many cases, new versions of
+packages work just fine with older dependencies.
 
 Also it is not needed to set BUILDLINK_ABI_DEPENDS.pkg when it is identical to
 BUILDLINK_API_DEPENDS.pkg.
@@ -5459,6 +5468,10 @@ resulting PLIST:
 
 PRINT_PLIST_AWK+=       /^libdata\/foo/ { next; }
 
+The PRINT_PLIST_AWK transformations are evaluated after the file list and
+directory list are sorted. EARLY_PRINT_PLIST_AWK is like PRINT_PLIST_AWK except
+it operates before the file list and directory list are sorted.
+
 19.4. Variable substitution in PLIST
 
 A number of variables are substituted automatically in PLISTs when a package is