[pkgsrc/trunk]: pkgsrc/doc/guide/files Move around text and rewrite some of t...

[reed <reed%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/e30b4fb82f31
branches:  trunk
changeset: 510897:e30b4fb82f31
user:      reed <reed%pkgsrc.org@localhost>
date:      Thu Apr 06 07:57:10 2006 +0000

description:
Move around text and rewrite some of the text
explaining BUILDLINK_API_DEPENDS and
BUILDLINK_ABI_DEPENDS.

diffstat:

 doc/guide/files/buildlink.xml |  57 ++++++++++++++++++++++++------------------
 1 files changed, 32 insertions(+), 25 deletions(-)

diffs (85 lines):

diff -r fa4ad6f24104 -r e30b4fb82f31 doc/guide/files/buildlink.xml
--- a/doc/guide/files/buildlink.xml     Thu Apr 06 07:33:30 2006 +0000
+++ b/doc/guide/files/buildlink.xml     Thu Apr 06 07:57:10 2006 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: buildlink.xml,v 1.15 2006/04/06 07:33:30 reed Exp $ -->
+<!-- $NetBSD: buildlink.xml,v 1.16 2006/04/06 07:57:10 reed Exp $ -->
 
 <chapter id="buildlink">
   <title>Buildlink methodology</title>
@@ -365,23 +365,12 @@
       <title>Updating <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname> in <filename>buildlink3.mk</filename> files</title>
 
       <para>
-        There are two situations that require increasing the
-       dependency listed in
+        The situation that requires increasing the dependency listed in
        <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
-       after a package update: </para>
+       after a package update is when the API or interface to the
+       header files change.</para>
 
-      <orderedlist>
-        <listitem>
-         <para> if the sonames (major number of the library version)
-           of any installed shared libraries change. </para>
-        </listitem>
-
-        <listitem>
-         <para> if the API or interface to the header files change. </para>
-        </listitem>
-      </orderedlist>
-
-      <para> In these cases,
+      <para> In this case,
        <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
        should be adjusted to require at least the new package
        version.  In some cases, the packages that depend on this new
@@ -389,20 +378,38 @@
        increased and, if they have <filename>buildlink3.mk</filename>
        files, their
        <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
-       adjusted, too. This is needed so that binary packages made
-       using it will require the correct package dependency and not
-       settle for an older one which will not contain the necessary
-       shared libraries. </para>
+       adjusted, too.  This is needed so pkgsrc will require the
+       correct package dependency and not settle for an older one
+       when building the source.</para>
+
+      <para>
+       <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
+       should be increased when the binary interface or sonames
+       (major number of the library version) of any installed
+       shared libraries change.  This is needed so that binary
+       packages made using it will require the correct package
+       dependency and not settle for an older one which will not
+       contain the necessary shared libraries. </para>
+
+      <para>
+       See <xref linkend="dependencies"/> for
+       more information about dependencies on other packages,
+       including the <varname>BUILDLINK_ABI_DEPENDS</varname> and
+       <varname>ABI_DEPENDS</varname> definitions. </para>
 
       <para> Please take careful consideration before adjusting
        <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
+       or
+       <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
        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.  See <xref
-       linkend="dependencies"/> for
-       more information about dependencies on other packages,
-       including the <varname>BUILDLINK_ABI_DEPENDS</varname> and
-       <varname>ABI_DEPENDS</varname> definitions. </para>
+       fine with older dependencies.</para>
+
+      <para>
+       Also it is not needed to set
+       <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
+       when it is identical to
+       <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>.        </para>
     </sect2>
   </sect1>