Index: portfiledev.xml
===================================================================
--- portfiledev.xml	(revision 68309)
+++ portfiledev.xml	(working copy)
@@ -482,15 +482,35 @@
     <section id="development.variants.default">
       <title>Default Variants</title>
 
-      <para>Variants are used to specify actions that lie outside the core
+      <para>MacPorts has a "build everything" approach to ensure the user
+      gets any functionality they might have been expecting. Sometimes
+      this includes deciding which version of mysql to use if the user
+      has not specified a preference.</para>
+
+      <programlisting>variant mysql4 conflicts mysql5 description {Build with MySQL 4 support} {
+    depends_lib-append  port:mysql4
+    configure.args      --with-mysql=${prefix}
+}
+
+variant mysql5 conflicts mysql4 description {Build with MySQL 5 support} {
+    depends_lib-append  path:bin/mysql_config5:mysql5
+    configure.args      --with-mysql-lib=${prefix}/lib/mysql5/mysql \
+                --with-mysql-include=${prefix}/include/mysql5/mysql
+}
+
+if {![variant_isset mysql4]} {
+    default_variants +mysql5
+}
+
+</programlisting>
+
+      <para>Variants are also used to deselect actions that lie outside the core
       functions of an application or port, but there may be some cases where
-      you wish to specify these non-core functions by default. For this
+      you wish to disable these non-core functions by default. For this
       purpose you may use the keyword default_variants.</para>
 
-      <programlisting>default_variants    +foo +bar</programlisting>
+      <programlisting>default_variants    +no_foo +no_bar</programlisting>
 
-      <!-- TODO: add warning not to use default_variant at the moment -->
-
       <note>
         <para>The default_variant keyword may only be used in the global
         Portfile section.</para>