Rewrite the Conflicts Handling section.

Sponsored by:	Absolight

1 files changed, 95 insertions, 44 deletions

diff --git a/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
index 90b1ed5be9..2ebcba4c2b 100644
--- a/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
@@ -7332,52 +7332,103 @@ DISTVERSION=	1.0</programlisting>
       those other ports for a few months to cater for users who only
       update once in a while.</para>
 
-    <sect2 xml:id="conflicts-conflicts_install">
-      <title><varname>CONFLICTS_INSTALL</varname></title>
-
-      <para>If the package cannot coexist with other packages
-	(because of file conflicts, runtime incompatibilities, etc.),
-	list the other package names in
-	<varname>CONFLICTS_INSTALL</varname>.  Use
-	shell globs like <literal>*</literal> and <literal>?</literal>
-	here.  Enumerate package names in there, not port names or
-	origins.  Please make sure
-	that <varname>CONFLICTS_INSTALL</varname> does not match this
-	port's package itself.  Otherwise enforcing its installation
-	with <varname>FORCE_PKG_REGISTER</varname> will no longer
-	work.  <varname>CONFLICTS_INSTALL</varname> check is done
-	after the build stage and prior to the install stage.</para>
-    </sect2>
+    <variablelist xml:id="conflicts-variables">
+      <varlistentry xml:id="conclicts-conflicts_install">
+	<term><varname>CONFLICTS_INSTALL</varname></term>
 
-    <sect2 xml:id="conflicts-conflicts_build">
-      <title><varname>CONFLICTS_BUILD</varname></title>
-
-      <para>If the port cannot be built when other specific ports are
-	already installed, list the other port names in
-	<varname>CONFLICTS_BUILD</varname>.  Use
-	shell globs like <literal>*</literal> and <literal>?</literal>
-	here.  Use package names, not port names or origins.
-	<varname>CONFLICTS_BUILD</varname> check is done prior to the
-	build stage.  Build conflicts are not recorded in the
-	resulting package.</para>
-    </sect2>
+	<listitem> <para>If the package cannot coexist with other
+	  packages (because of file conflicts, runtime
+	  incompatibilities, etc.).
+	  <varname>CONFLICTS_INSTALL</varname> check is done after the
+	  build stage and prior to the install stage.</para>
+    </listitem> </varlistentry>
 
-    <sect2 xml:id="conflicts-conflicts">
-      <title><varname>CONFLICTS</varname></title>
-
-      <para>If the port cannot be built if a certain port is already
-	installed and the resulting package cannot coexist with the
-	other package, list the other package name in
-	<varname>CONFLICTS</varname>.  use shell
-	globs like <literal>*</literal> and <literal>?</literal> here.
-	Enumerate package names in there, not port names or
-	origins.  Please make sure that
-	<varname>CONFLICTS</varname> does not match this
-	port's package itself.  Otherwise enforcing its installation
-	with <varname>FORCE_PKG_REGISTER</varname> will no longer
-	work.  <varname>CONFLICTS</varname> check is done prior to the
-	build stage and prior to the install stage.</para>
-    </sect2>
+      <varlistentry xml:id="conclicts-conflicts_build">
+	<term><varname>CONFLICTS_BUILD</varname></term>
+
+	<listitem>
+	  <para>If the port cannot be built when other specific ports
+	    are already installed.  Build conflicts are not recorded
+	    in the resulting package.</para>
+	</listitem>
+
+      </varlistentry>
+
+      <varlistentry xml:id="conclicts-conflicts">
+	<term><varname>CONFLICTS</varname></term>
+
+	<listitem>
+	  <para>If the port cannot be built if a certain port is
+	    already installed and the resulting package cannot coexist
+	    with the other package.  <varname>CONFLICTS</varname>
+	    check is done prior to the build stage and prior to the
+	    install stage.</para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>The most common content of one of these variable is the
+      package base of another port.  The package base is the package
+      name without the appended version, it can be obtained by running
+      <command>make -V PKGBASE</command>.</para>
+
+    <example xml:id="conflicts-ex1">
+      <title>Basic usage of
+	<varname>CONFLICTS<replaceable>*</replaceable></varname></title>
+
+      <para><package role="port">dns/bind99</package> cannot be
+	installed if <package role="port">dns/bind910</package> is
+	present because they install same files.  First gather the
+	package base to use:</para>
+
+      <screen>&prompt.user; <userinput>make -C dns/bind99 -V PKGBASE</userinput>
+bind99
+&prompt.user; <userinput>make -C dns/bind910 -V PKGBASE</userinput>
+bind910</screen>
+
+      <para>Then add to the <filename>Makefile</filename> of <package
+	role="port">dns/bind99</package>:</para>
+
+      <programlisting>CONFLICTS_INSTALL=	bind910</programlisting>
+
+      <para>And add to the <filename>Makefile</filename> of <package
+	role="port">dns/bind910</package>:</para>
+
+      <programlisting>CONFLICTS_INSTALL=	bind99</programlisting>
+    </example>
+
+    <para>Sometime, only some version of another port is incompatible,
+      in this case, use the full package name, with the version, and
+      use shell globs, like <literal>*</literal> and
+      <literal>?</literal> to make sure all possible versions are
+      matched.</para>
+
+    <example xml:id="conflicts-ex2">
+      <title>Using <varname>CONFLICTS<replaceable>*</replaceable></varname> With Globs.</title>
+
+      <para>From versions from 2.0 and up-to 2.4.1_2, <package
+	  role="port">deskutils/gnotime</package> used to install a
+	bundled version of <package
+	  role="port">databases/qof</package>.</para>
+
+      <para>To reflect this past, the <filename>Makefile</filename> of
+	<package role="port">databases/qof</package> contains:</para>
+
+      <programlisting>CONFLICTS_INSTALL=	gnotime-2.[0-3]* \
+			gnotime-2.4.0* gnotime-2.4.1 \
+			gnotime-2.4.1_[12]</programlisting>
+
+      <para>The first entry match versions <literal>2.0</literal>
+	through <literal>2.3</literal>, the second all the revisions
+	of <literal>2.4.0</literal>, the third the exact
+	<literal>2.4.1</literal> version, and the last the first and
+	second revisions of the <literal>2.4.1</literal>
+	version.</para>
+
+      <para><package role="port">deskutils/gnotime</package> does not
+	have any conflicts line because its current version does not
+	conflict with anything else.</para>
+    </example>
   </sect1>
 
   <sect1 xml:id="install">