Face lift for the "Version Identifcation" documentation.

Reword for better clarity,

update sorting example (r8468 corrected the comparison to incomplete tuples),

fix links.

No policy change.

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk/docutils@8689 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 67 insertions, 99 deletions

diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt
index 5c9237b87..b8f7dbfeb 100644
--- a/docs/dev/policies.txt
+++ b/docs/dev/policies.txt
@@ -409,12 +409,9 @@ Version Identification
 ======================
 
 The state of development of the current Docutils codebase is stored in
-two forms: a `docutils.__version_info__`_ namedtuple, and a
-`docutils.__version__`_ text string.
-
-See also the `Docutils Release Procedure`_, and
-``docutils.__version__`` & ``docutils.__version_info__`` in
-docutils/__init__.py.
+two forms: the sequence `docutils.__version_info__`_ and the
+`PEP 440`_ conformant text string `docutils.__version__`_.
+See also the `Docutils Release Procedure`_
 
 .. _Docutils Release Procedure: release.html#version-numbers
 
@@ -422,10 +419,9 @@ docutils/__init__.py.
 ``docutils.__version_info__``
 -----------------------------
 
-Detailed version information is available in
-``docutils.__version_info__``, an instance of the namedtuple_
-``docutils.VersionInfo``. It is modelled on `sys.version_info`_ and
-has the following attributes:
+``docutils.__version_info__`` is an instance of ``docutils.VersionInfo``
+based on collections.namedtuple_. It is modelled on `sys.version_info`_
+and has the following attributes:
 
 major : non-negative integer
     **Major releases** (x.0, e.g. 1.0) will be rare, and will
@@ -444,131 +440,103 @@ minor : non-negative integer
 micro : non-negative integer
     Releases that change the micro number (x.y.z, e.g. 0.4.1) will be
     **bug-fix releases**.  No new features will be introduced in these
-    releases; only bug fixes will be included.  The micro number is
-    omitted from ``docutils.__version__`` when micro=0.
+    releases; only bug fixes will be included.
+
+    The micro number is omitted from `docutils.__version__`_ when it
+    equals zero.
 
-releaselevel : text string
+_`releaselevel` : text string
     The release level indicates the `development status`_ (or phase)
     of the project's codebase:
 
-    =============  =======  ============================================
-    Release Level  Label    Description
-    =============  =======  ============================================
-    alpha          ``a``    Reserved for use after major experimental
-                            changes, to indicate an unstable codebase.
+    =============  ==========  ===============================================
+    Release Level  Label [#]_  Description
+    =============  ==========  ===============================================
+    alpha          ``a``       Reserved for use after major experimental
+                               changes, to indicate an unstable codebase.
 
-    beta           ``b``    Indicates active development, between releases.
-                            Used with serial = 0.
+    beta           ``b``       Indicates active development, between releases.
 
-    candidate      ``rcN``  Release candidate: indicates that the
-                            codebase is ready to release unless
-                            significant bugs emerge.
-                            Serial N starts at 1.
+    candidate      ``rc``      Release candidate: indicates that the
+                               codebase is ready to release unless
+                               significant bugs emerge.
 
-    final                   Indicates an official project release.
-                            There is no pre-release segment for final
-                            releases (no label).
-    =============  =======  ============================================
+    final                      Indicates an official project release.
+    =============  ==========  ===============================================
 
-    The abbreviations in the "Label" column are used in the
-    `docutils.__version__`_ identifier text.
+    .. [#] The labels are used in the `docutils.__version__`_ pre-release
+       segment.
 
     .. _development status:
        https://en.wikipedia.org/wiki/Software_release_life_cycle
 
-serial : non-negative integer
-    The serial number is incremented whenever a new pre-release is
-    begun.
+_`serial` : non-negative integer
+    The serial number is zero for final releases and incremented
+    whenever a new pre-release is begun.
 
-release : boolean
+_`release` : boolean
     True for official releases and pre-releases, False during
     development.
 
-One of *{major, minor, micro}* is incremented after each official
-release, and the lower-order numbers are reset to 0.
+* One of *{major, minor, micro, serial}* is incremented after each
+  release, and the lower-order numbers are reset to 0.
 
-The default state of the repository during active development and
-between releases is: release level "beta", serial = 0, release =
-False.
+* The default state of the repository during active development is
+  release level = "beta", serial = 0, release = False.
 
 ``docutils.__version_info__`` can be used to test for a minimally
-required version, e.g.::
-
-    comparison_version = docutils.VersionInfo(
-        major=0, minor=13, micro=0,
-        releaselevel='candidate', serial=2, release=True)
-    if docutils.__version_info__ >= comparison_version:
-        ...
-
-For practical purposes it may suffice to test against a truncated tuple,
-e.g.::
-
-    if docutils.__version_info__ >= (0, 13)
-
-is True for all versions "larger" than ``"0.13"``.
-
-Mind, however, that a test like ::
+required version, e.g. ::
 
-    if docutils.__version_info__ > (0, 14)
+    docutils.__version_info__ >= (0, 13)
 
-is True also for development versions and pre-releases of the 0.14 series
-although, according to PEP 440, these must be sorted before 0.14.
-
-.. _namedtuple: https://docs.python.org/3/library/collections.html#collections.namedtuple
-.. _sys.version_info: https://docs.python.org/3/library/sys.html#version-info
+is True for all versions after ``"0.13"``.
 
+.. _collections.namedtuple:
+   https://docs.python.org/3/library/collections.html#collections.namedtuple
+.. _sys.version_info:
+   https://docs.python.org/3/library/sys.html#sys.version_info
 
 ``docutils.__version__``
 ------------------------
 
-``docutils.__version__`` contains the version identifier as a text
-string: a concise, `PEP 440`_-conforming representation of
-``docutils.__version_info__``.
-
-For version comparison operations, use `docutils.__version_info__`_.
-Do not parse the text of ``docutils.__version__``.
+The text string ``docutils.__version__`` is a human readable,
+`PEP 440`_-conforming version specifier.  For version comparison
+operations, use `docutils.__version_info__`_.
 
 ``docutils.__version__`` takes the following form::
 
-    <major>.<minor>[.<micro>][<releaselevel>[<serial>]][.dev]
-    <--- release segment ---><-- pre-release segment -><- development ->
-
-.. _PEP 440: https://www.python.org/dev/peps/pep-0440/
-
-* The abbreviated forms of each release level, found in the "Label"
-  column in the table above ("a" or "b" or "rc"), are used in the
-  pre-release segment.
+    "<major>.<minor>[.<micro>][<releaselevel>[<serial>]][.dev]"
+     <--- release segment ---><-- pre-release segment -><- development ->
 
-* When the serial number is 0, it is omitted from the pre-release
-  segment.
+* The *pre-release segment* contains a label representing the
+  releaselevel_ ("a", "b", or "rc") and eventually a serial_ number
+  (omitted, if zero).
 
-* The development segment is present during active development (as
-  "``.dev``", when ``docutils.__version_info__.release`` is False),
-  and absent for official releases and pre-releases (when
-  ``docutils.__version_info__.release`` is True).
+* The *development segment* is ``".dev"`` during active development
+  (release_ == False) and omitted for official releases and pre-releases.
 
 Examples of ``docutils.__version__`` identifiers, over the course of
 normal development (without branches), in ascending order:
 
-======================  ============================
-Release Level           Version Identifier
-======================  ============================
-final (release)         0.14
-beta (development)      0.15b.dev [2]_
-beta (release)          0.15b [1]_
-candidate 1 (dev.)      0.15rc1.dev
-candidate 1 (release)   0.15rc1
-candidate 2 (dev.)      0.15rc2.dev [1]_
-candidate 2 (release)   0.15rc2 [1]_
-... candidate N         0.15rcN.dev [1]_, 0.15rcN [1]_
-final (release)         0.15
-beta (dev.)             0.16b.dev [2]_
-======================  ============================
-
-.. [1] These steps may be skipped.
-
-.. [2] Default active development state between releases.
+==============================  =============================
+Release Level                   Version Identifier
+==============================  =============================
+final (release)                 0.14
+beta (development) [#dev]_      0.15b.dev
+beta (release)  [#skip]_        0.15b
+candidate 1 (dev.)              0.15rc1.dev
+candidate 1 (release)           0.15rc1
+candidate 2 (dev.) [#skip]_     0.15rc2.dev
+candidate 2 (release) [#skip]_  0.15rc2
+...
+final (release)                 0.15
+beta (development) [#dev]_      0.16b.dev
+==============================  =============================
+
+.. [#dev] Default active development state between releases.
+.. [#skip] These steps may be skipped.
 
+.. _PEP 440: https://www.python.org/dev/peps/pep-0440/
 
 Policy History
 --------------