[35548] trunk/doc-new/guide/xml

[markd at macports.org]

Revision: 35548
          http://trac.macosforge.org/projects/macports/changeset/35548
Author:   markd at macports.org
Date:     2008-03-29 21:48:15 -0700 (Sat, 29 Mar 2008)

Log Message:
-----------
Document variants descriptions as suggested by Ryan in an email on the
MacPorts-dev support list recently.

Modified Paths:
--------------
    trunk/doc-new/guide/xml/portfile-variants.xml
    trunk/doc-new/guide/xml/portfiledev.xml

Modified: trunk/doc-new/guide/xml/portfile-variants.xml
===================================================================
--- trunk/doc-new/guide/xml/portfile-variants.xml	2008-03-30 03:26:28 UTC (rev 35547)
+++ trunk/doc-new/guide/xml/portfile-variants.xml	2008-03-30 04:48:15 UTC (rev 35548)
@@ -122,6 +122,30 @@
     </variablelist>
   </section>
 
+  <section id="reference.variants.descriptions">
+    <title>User-Selected Variant Descriptions</title>
+
+    <para>User-selected variants ought to provide a description, which will be
+    displayed when using command <quote>port variants foo</quote>. The syntax
+    used for the description keyword is shown below.</para>
+
+    <programlisting>variant bar description {Add IMAP support} {}</programlisting>
+
+    <para>Descriptions should be short but clear, and not merely repeat the
+    name of the variant. To allow for compatibility for possible MacPorts GUI
+    support, a good rule of thumb is to use sentence fragments for brevity,
+    with a capitalized first letter and no trailing punctuation. Think of them
+    as short labels such as ones you'd find next to a GUI checkbox or radio
+    button. Thus, it would be better to write "Build with support for foo"
+    instead of "Builds with support for foo"; "Add support for foo" would be
+    better than "Adds support for foo". </para>
+
+    <para>Variant descriptions are strings, so one should take care not to put
+    whitespace between the brackets and the beginning and end of the variant
+    description, and also not to use unnceccessary whitespace, unlike with
+    port descriptions and long_descriptions.</para>
+  </section>
+
   <section id="reference.variants.platform">
     <title>Platform Variants</title>
 

Modified: trunk/doc-new/guide/xml/portfiledev.xml
===================================================================
--- trunk/doc-new/guide/xml/portfiledev.xml	2008-03-30 03:26:28 UTC (rev 35547)
+++ trunk/doc-new/guide/xml/portfiledev.xml	2008-03-30 04:48:15 UTC (rev 35548)
@@ -338,21 +338,44 @@
 
     <para>Variants are a way for port authors to provide options that may be
     invoked at install time. They are declared in the global section of a
-    Portfile using the "variant" keyword and may provide a description.</para>
+    Portfile using the "variant" keyword, and should include <link
+    linkend="reference.variants.descriptions">carefully chosen variant
+    descriptions</link>.</para>
 
     <section id="development.variants.options">
-      <title>Variants to Modify Options</title>
+      <title>Example Variants</title>
 
-      <para>The most common use for a variant is to add or remove
-      dependencies, configure arguments, and build arguments from the global
-      Portfile section. Here is an example of a port providing four variants
-      that add additional configure arguments to a port.</para>
+      <para>The most common actions for user-selected variants is to add or
+      remove dependencies, configure arguments, and build arguments according
+      to various options a port author wishes to provide. Here is an example
+      of several variants that modify depends_lib and configure arguments for
+      a port.</para>
 
-      <programlisting>variant pop     { configure.args-append --enable-pop }
-variant imap    { configure.args-append --enable-imap }
-variant ssl     { configure.args-append --with-ssl }
-variant debug   { configure.args-append --enable-debug }</programlisting>
+      <programlisting>variant fastcgi description {Add fastcgi binary} {
+    configure.args-append \
+            --enable-fastcgi \
+            --enable-force-cgi-redirect \
+            --enable-memory-limit
+}
 
+variant gmp description {Add GNU MP functions} {
+    depends_lib-append port:gmp
+    configure.args-append --with-gmp=${prefix}
+
+}
+
+variant sqlite description {Build sqlite support} {
+    depends_lib-append \
+        port:sqlite3
+    configure.args-delete \
+        --without-sqlite \
+        --without-pdo-sqlite
+    configure.args-append \
+        --with-sqlite \
+        --with-pdo-sqlite=${prefix} \
+        --enable-sqlite-utf8
+}</programlisting>
+
       <note>
         <para>Variant names may contain only the characters A-Z, a-z, and the
         underscore character <quote>_</quote>. Therefore, take care to never

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/macports-changes/attachments/20080329/ba30a66d/attachment-0001.html