From 6cb3810952e4a29023bce6682608a1bee40ca910 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Thu, 3 May 2018 14:29:26 +0200
Subject: Specify ^ and ~ version constraint operators

---
 doc/manual.cli | 56 +++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 49 insertions(+), 7 deletions(-)

diff --git a/doc/manual.cli b/doc/manual.cli
index 0d5b5ab..9458857 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -733,8 +733,9 @@ notifications for this package are sent by email.
 
 <alternatives> := <dependency> [ '|' <dependency>]*
 <dependency>   := <name> [<constraint>]
-<constraint>   := <comparison> | <range>
+<constraint>   := <comparison> | <shortcut> | <range>
 <comparison>   := ('==' | '>' | '<' | '>=' | '<=') <version>
+<shortcut>     := ('^' | '~') <version>
 <range>        := ('(' | '[') <version> <version> (')' | ']')
 \
 
@@ -767,7 +768,7 @@ For example:
 
 \
 depends: libz
-depends: libfoo [1.2.0 1.3.0-); Need libfoo 1.2.X.
+depends: libfoo ~1.2.0; Only works with libfoo 1.2.*.
 depends: libgnutls >= 1.2.3 | libopenssl >= 2.3.4
 depends: ? libboost-regex >= 1.52.0; Only if no C++11 <regex>.
 depends: ? libqtcore >= 5.0.0; Only if GUI is enabled.
@@ -776,12 +777,53 @@ depends: ? libqtcore >= 5.0.0; Only if GUI is enabled.
 It is recommended that you specify unconditional dependencies first with
 simple (no alternatives) dependencies leading each set.
 
-Note that internally comparisons can be represented as ranges (that is, \c{[v,
-v]} for \c{==}, \c{(v, inf)} for \c{>}, etc). However, for display and
+The optional version constraint can be specified using comparison operators,
+shortcut (to range) operators, and ranges.
+
+The shortcut operators can only be used with \l{b#module-version standard
+versions} (a semantic version without the pre-release part is a standard
+version). They are equivalent to the following ranges. \N{The \c{X.Y.Z-} version
+signifies the earliest pre-release in the \c{X.Y.Z} series; see
+\l{#package-version Package Version} for details}.
+
+\
+~X.Y.Z  [X.Y.Z  X.Y+1.0-)
+
+^X.Y.Z  [X.Y.Z  X+1.0.0-)  if X >  0
+^0.Y.Z  [0.Y.Z  0.Y+1.0-)  if X == 0
+\
+
+That is, the tilde (\c{~}) constraint allows upgrades to any further patch
+version while the caret (\c{^}) constraint \- also to any further minor
+version.
+
+\N|Zero major version component is customarily used during early development
+where the minor version effectively becomes major. As a result, the tilde
+constraint has special semantics for this case.|
+
+Note that the shortuct operators can only be used with the complete,
+three-component versions (\c{X.Y.Z} with the optional pre-release part per the
+standard version). Specifically, there is no support for special \c{^X.Y} or
+\c{~X} semantics offered by some package manager \- if desired, such
+functionality can be easily achieved with ranges. Also, the \c{0.0.Z} version
+is not considered special except as having zero manjor component for the tilde
+semantics discussed above.
+
+Note also that pre-releases do not required any special considerations when
+used with the shortcut operators. For example, if package \c{libfoo} is
+usable starting with the second beta of the \c{2.0.0} release, then our
+constraint could be expressed as:
+
+\
+depends: libfoo ^2.0.0-b.2
+\
+
+\N|Internally shortucts and comparisons can be represented as ranges (that is,
+\c{[v, v]} for \c{==}, \c{(v, inf)} for \c{>}, etc). However, for display and
 serialization such representations should be converted back to simple
-comparisons. While it is possible that the original manifest specified
-equality as \c{[v, v]}, it is acceptable to display/serialize it as
-simpler \c{==}.
+operators. While it is possible that the original manifest specified equality
+or shortucts as full ranges, it is acceptable to display/serialize them as
+simpler operators.|
 
 \h2#manifest-package-requires|\c{requires}|
 
-- 
cgit v1.1