Move details on $ translation to Package Version Constraint section in manual

1 files changed, 92 insertions, 81 deletions

diff --git a/doc/manual.cli b/doc/manual.cli
index 117891e..599b571 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -297,6 +297,92 @@ 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.|
 
+Instead of a concrete value, the version in the constraint can be specified in
+terms of the dependent package's version (that is, the version of the package
+placing the constraint) using the special \c{$} value. For example:
+
+\
+libfoo == $
+\
+
+A constraint that contains \c{$} is called incomplete. This mechanism is
+primarily useful when developing related packages that should track each
+other's versions exactly or closely.
+
+In comparison operators and ranges the \c{$} value is replaced with the
+dependent version ignoring the revision. For shortcut operators, the dependent
+version must be a standard version and the following additional processing is
+applied depending on whether the version is a release, final pre-release, or a
+snapshot pre-release.
+
+\ol|
+
+\li|For a release we set the min version patch to zero. For \c{^} we also set
+the minor version to zero, unless the major version is zero (reduces to
+\c{~}). The max version is set according to the standard shortcut logic. For
+example, \c{~$} is completed as follows:
+
+\
+1.2.0 -> [1.2.0 1.3.0-)
+1.2.1 -> [1.2.0 1.3.0-)
+1.2.2 -> [1.2.0 1.3.0-)
+\
+
+And \c{^$} is completed as follows:
+
+\
+1.0.0 -> [1.0.0 2.0.0-)
+1.1.1 -> [1.0.0 2.0.0-)
+\
+
+|
+
+\li|For a final pre-release the key observation is that if the patch
+component for \c{~} or minor and patch components for \c{^} are not zero, then
+that means there has been a compatible release and we treat this case the same
+as release, ignoring the pre-release part. If, however, it/they are zero, then
+that means there may yet be no final release and we have to start from the
+first alpha. For example, for the \c{~$} case:
+
+\
+1.2.0-a.1 -> [1.2.0-a.1 1.3.0-)
+1.2.0-b.2 -> [1.2.0-a.1 1.3.0-)
+1.2.1-a.1 -> [1.2.0     1.3.0-)
+1.2.2-b.2 -> [1.2.0     1.3.0-)
+\
+
+And for the \c{^$} case:
+
+\
+1.0.0-a.1 -> [1.0.0-a.1 2.0.0-)
+1.0.0-b.2 -> [1.0.0-a.1 2.0.0-)
+1.0.1-a.1 -> [1.0.0     2.0.0-)
+1.1.0-b.2 -> [1.0.0     2.0.0-)
+\
+
+|
+
+\li|For a snapshot pre-release we distinguish two cases: a patch snapshot
+(the patch component is not zero) and a major/minor snapshot (the patch
+component is zero). For the patch snapshot case we assume that it is (most
+likely) developed independently of the dependency and we treat it the same as
+the final pre-release case. For example, if the dependent version is
+\c{1.2.1-a.0.nnn}, the dependency could be \c{1.2.0} or \c{1.2.2} (or
+somewhere in-between).
+
+For the major/minor snapshot we assume that all the packages are developed in
+the lockstep and have the same \c{X.Y.0} version. In this case we make the
+range start from the earliest possible version in this \"snapshot series\" and
+end before the final pre-release. For example (in this case \c{~} and \c{^}
+are treated the same):
+
+\
+1.2.0-a.0.nnn -> [1.2.0-a.0.1 1.2.0-a.1)
+2.0.0-b.2.nnn -> [2.0.0-b.2.1 2.0.0-b.3)
+\
+
+||
+
 
 \h1#manifests|Manifests|
 
@@ -1116,13 +1202,12 @@ It is recommended that you specify unconditional dependencies first with
 simple (no alternatives) dependencies leading each set.
 
 See \l{#package-version-constraint Package Version Constraint} for the format
-and semantics of the optional version constraint. Instead of a concrete
-value, it can also be specified in terms of the dependent package's version
-(that is, its \l{#manifest-package-version \c{version}} value) using the
-special \c{$} value. A \c{depends} value that contains \c{$} is called
-incomplete. This mechanism is primarily useful when developing related
-packages that should track each other's versions exactly or closely. For
-example:
+and semantics of the optional version constraint. Instead of a concrete value,
+the version in the constraint can also be specified in terms of the dependent
+package's version (that is, its \l{#manifest-package-version \c{version}}
+value) using the special \c{$} value. This mechanism is primarily useful when
+developing related packages that should track each other's versions exactly or
+closely. For example:
 
 \
 name: sqlite3
@@ -1130,80 +1215,6 @@ version: 3.18.2
 depends: libsqlite3 == $
 \
 
-In comparison operators and ranges the \c{$} value is replaced with the
-dependent version ignoring the revision. For shortcut operators, the dependent
-version must be a standard version and the following additional processing is
-applied depending on whether the version is a release, final pre-release, or a
-snapshot pre-release.
-
-\ol|
-
-\li|For a release we set the min version patch to zero. For \c{^} we also set
-the minor version to zero, unless the major version is zero (reduces to
-\c{~}). The max version is set according to the standard shortcut logic. For
-example, \c{~$} is completed as follows:
-
-\
-1.2.0 -> [1.2.0 1.3.0-)
-1.2.1 -> [1.2.0 1.3.0-)
-1.2.2 -> [1.2.0 1.3.0-)
-\
-
-And \c{^$} is completed as follows:
-
-\
-1.0.0 -> [1.0.0 2.0.0-)
-1.1.1 -> [1.0.0 2.0.0-)
-\
-
-|
-
-\li|For a final pre-release the key observation is that if the patch
-component for \c{~} or minor and patch components for \c{^} are not zero, then
-that means there has been a compatible release and we treat this case the same
-as release, ignoring the pre-release part. If, however, it/they are zero, then
-that means there may yet be no final release and we have to start from the
-first alpha. For example, for the \c{~$} case:
-
-\
-1.2.0-a.1 -> [1.2.0-a.1 1.3.0-)
-1.2.0-b.2 -> [1.2.0-a.1 1.3.0-)
-1.2.1-a.1 -> [1.2.0     1.3.0-)
-1.2.2-b.2 -> [1.2.0     1.3.0-)
-\
-
-And for the \c{^$} case:
-
-\
-1.0.0-a.1 -> [1.0.0-a.1 2.0.0-)
-1.0.0-b.2 -> [1.0.0-a.1 2.0.0-)
-1.0.1-a.1 -> [1.0.0     2.0.0-)
-1.1.0-b.2 -> [1.0.0     2.0.0-)
-\
-
-|
-
-\li|For a snapshot pre-release we distinguish two cases: a patch snapshot
-(the patch component is not zero) and a major/minor snapshot (the patch
-component is zero). For the patch snapshot case we assume that it is (most
-likely) developed independently of the dependency and we treat it the same as
-the final pre-release case. For example, if the dependent version is
-\c{1.2.1-a.0.nnn}, the dependency could be \c{1.2.0} or \c{1.2.2} (or
-somewhere in-between).
-
-For the major/minor snapshot we assume that all the packages are developed in
-the lockstep and have the same \c{X.Y.0} version. In this case we make the
-range start from the earliest possible version in this \"snapshot series\" and
-end before the final pre-release. For example (in this case \c{~} and \c{^}
-are treated the same):
-
-\
-1.2.0-a.0.nnn -> [1.2.0-a.0.1 1.2.0-a.1)
-2.0.0-b.2.nnn -> [2.0.0-b.2.1 2.0.0-b.3)
-\
-
-||
-
 
 \h2#manifest-package-requires|\c{requires}|