[86707] trunk/doc-new/guide/xml/portfile-keywords.xml

[ryandesign at macports.org]

Revision: 86707
          http://trac.macports.org/changeset/86707
Author:   ryandesign at macports.org
Date:     2011-11-01 09:00:28 -0700 (Tue, 01 Nov 2011)
Log Message:
-----------
portfile-keywords.xml: rewrite epoch section a bit

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

Modified: trunk/doc-new/guide/xml/portfile-keywords.xml
===================================================================
--- trunk/doc-new/guide/xml/portfile-keywords.xml	2011-11-01 16:00:07 UTC (rev 86706)
+++ trunk/doc-new/guide/xml/portfile-keywords.xml	2011-11-01 16:00:28 UTC (rev 86707)
@@ -72,23 +72,19 @@
       <term>epoch</term>
 
       <listitem>
-        <para>An optional keyword (default value is 0) that may be used when
-        ports are updated to a version that is numerically less than the
-        previous version. For example 1.10 -> 1.2 or 20070928 -> 1.0. An
-        epoch ensures that port version comparisons work correctly in these
-        cases. Often the epoch is formatted like a date, but it can simply be
-        a number such as 1.</para>
+        <para>An optional keyword (default value is 0) that must be used when
+        a port is updated to a version that is numerically less than the
+        previous version, for example 1.10 -> 1.2 or 20070928 -> 1.0.
+        Some Portfile authors have used large epoch values that look like a
+        date, but there is no reason to do so. The epoch is simply an unsigned
+        integer, and the only requirement is that it never be decreased.</para>
 
-        <programlisting>epoch               20080924</programlisting>
-
         <programlisting>epoch               1</programlisting>
 
         <note>
-          <para>An epoch is not needed for most ports. If an epoch is used it
-          must never be decreased or removed even when a port's version is
-          updated; this would cause port version comparisons to be incorrect
-          since epochs take precedence over versions once epochs have been
-          used.</para>
+          <para>An epoch is not needed for most ports. If a port's version
+          numbers advance in normal dotted-decimal sequence, there is no reason
+          to add an epoch.</para>
         </note>
       </listitem>
     </varlistentry>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/macports-changes/attachments/20111101/48e742c0/attachment.html>