fix and improve broken links (version/range)

fixes #6372 by fixing a broken link and adding links to interconnect pages related to version ranges.

Signed-off-by: Christoph Rueger <[email protected]>

add example

add more example

improve examples

docs/_chapters/170-versioning.md

@@ -113,7 +113,7 @@ This asymmetry creates the need for two version policies:
     -provider-policy :    ${range;[==,=+)}
     -consumer-policy :    ${range;[==,+)}
 
-The given values are the defaults. The value of the version policy will be used calculate the import based on the exported package. The `${range}` macro provides a convenient shortcut to do this using a version mask.
+The given values are the defaults. The value of the version policy will be used calculate the import based on the exported package. The [`${range}`](../macros/range.html) macro provides a convenient shortcut to do this using a version mask.
 
 For example, a bundle that implements the OSGi Event Admin service can use the following bnd file:
 
@@ -126,10 +126,14 @@ The resulting manifest would look like:
         Import-Package:  org.osgi.service.event; version="[1.1,2)", ...
         ...
 
-How does bnd know if a bundle is a provider or a consumer of a specific package? Well, the default is the consumer policy but this can be overridden with the `provide:=true` directive that works on the `Import-Package` clauses as well as on the `Export-Package` clauses. 
+How does bnd know if a bundle is a provider or a consumer of a specific package? 
+
+Well, the default is the consumer policy but this can be overridden with the `provide:=true` directive that works on the `Import-Package` clauses as well as on the `Export-Package` clauses.
 
 The `provide:` directive indicates to bnd that the given package contains API that is provided by this bundle. The (strongly) recommended way is to put the `provide:=true` directive on the `Export-Package` header, even if the package comes from another bundle. This way the bundle contains a copy of the package that is by default imported with the proper provider policy range.
 
+Also see [-consumerpolicy](../instructions/consumer_policy.html), [-providerpolicy](../instructions/provider_policy.html) and [range](../macros/range.html).
+
 For example, an implementation of the OSGi Event Admin specification could use the following bnd file:
 
     bnd.bnd:

docs/_heads/import_package.md

@@ -11,7 +11,7 @@ For example:
     Import-Package: !org.apache.commons.log4j, com.acme.*,\
      com.foo.extra
 
-During processing, bnd will attempt to find the exported version of imported packages. If no version or version range is specified on the import instruction, the exported version will then be used though the micro part and the qualifier are dropped. That is, when the exporter is `1.2.3.build123`, then the import version will be 1.2. If a specific version (range) is specified, this will override any found version. This default an be overridden with the [-versionpolicy](../instructions/versionpolicy.html) instruction.
+During processing, bnd will attempt to find the exported version of imported packages. If no version or version range is specified on the import instruction, the exported version will then be used though the micro part and the qualifier are dropped. That is, when the exporter is `1.2.3.build123`, then the import version will be 1.2. If a specific version (range) is specified, this will override any found version. This default an be overridden with the [-consumerpolicy](../instructions/consumer_policy.html) or [-providerpolicy](../instructions/provider_policy.html) instruction (also see [Versioning](../chapters/170-versioning.html)).
 
 If an explicit version is given, then `${@}` can be used to substitute the found version in a range. In those cases, the [range](../macros/range.html) macro can be very useful to calculate ranges and drop specific parts of the version. For example:
 

docs/_macros/range.md

@@ -8,7 +8,7 @@ summary: Create a semantic version range out of a version using a mask to contro
 The `range` macro takes a version range mask/template and uses it calculate a range from a given version. The primary reason for the `${range}` macro is to be used in the [version policy][1]. With the version policy we have a version of an exported package and we need to calculate the range for that. The rules come from the [consumer][2] or [provider][3] policy. However, this policy can be overridden on the Import-Package header by specifying the version as a range macro:
 
 	Import-Package: com.example.myownpolicy; version="${range;[==,=+)}", *
-<foo ]>
+
 
 Since the version for the exported package is set as `${@}`, the macro will calculate the proper semantic range for a provider.
 
@@ -26,12 +26,39 @@ The meaning of the characters is:
 * `+` – Increment the version part
 * `[0-9]` – Replace the version part
 * `~` – Ignore the version part
-* `[Ss]` – If the qualifier equals `SNAPSHOT`, then it will return a maven like snapshot version. Maven snapshot versions do not use the `.` as the separator but a `-` sign. The upper case `S` checks case sensitive, the lower case `s` is case insensitive. This template character will be treated as the last character in the template and return the version immediately. For example, `${versionmask;=S;1.2.3.SNAPSHOT}` will return `1-SNAPSHOT`.  
+* `[Ss]` – If the qualifier equals `SNAPSHOT`, then it will return a maven like snapshot version. Maven snapshot versions do not use the `.` as the separator but a `-` sign. The upper case `S` checks case sensitive, the lower case `s` is case insensitive. This template character will be treated as the last character in the template and return the version immediately. 
+
+## Examples
+
+With `${range}`:
+
+- `${range;[==,+);1.2.3}` will return `[1.2,2)`.
+- `${range;[===,+++);1.2.3}` will return `[1.2.3,2.3.4)`.
+- `${range;[===,+==);1.2.3}` will return `[1.2.3,2.2.3)`.
+- `${range;[===,==+);1.2.3}` will return `[1.2.3,1.2.4)`.
+- `${range;[=+=,+=+);1.2.3}` will return `[1.3.3,2.2.4)`.
+
+With `${versionmask}`:
+
+- `${versionmask;===S;1.2.3.SNAPSHOT}` will return `1.2.3-SNAPSHOT`.
+- `[${versionmask;==;1.2.3},${versionmask;+;1.2.3})` will return `[1.2,2)`.
+- `[${versionmask;===;1.2.3},${versionmask;+++;1.2.3})` will return `[1.2.3,2.3.4)`.
+- `[${versionmask;===;1.2.3},${versionmask;+==;1.2.3})` will return `[1.2.3,2.2.3)`.
+- `[${versionmask;===;1.2.3},${versionmask;==+;1.2.3})` will return `[1.2.3,1.2.4)`.
+- `[${versionmask;=+=;1.2.3},${versionmask;+=+;1.2.3})` will return `[1.3.3,2.2.4)`.
+
+
+
+Also see [versionmask][5] / [version][4].  
+
+
 
 
 [1]: /chapters/170-versioning.html
 [2]: /instructions/consumer_policy.html
 [3]: /instructions/provider_policy.html
+[4]: /macros/version.html
+[5]: /macros/versionmask.html
 
 	/**
 	 * Schortcut for version policy