Move around text and rewrite some of the text

explaining BUILDLINK_API_DEPENDS and
BUILDLINK_ABI_DEPENDS.

1 files changed, 32 insertions, 25 deletions

diff --git a/doc/guide/files/buildlink.xml b/doc/guide/files/buildlink.xml
index 2209746fc86..2c2665905da 100644
--- a/doc/guide/files/buildlink.xml
+++ b/doc/guide/files/buildlink.xml
@@ -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>