Merge pull request #2302 from igorw/versions-table

Format the possible version formats as a table

doc/01-basic-usage.md

@@ -58,31 +58,31 @@ smaller decoupled parts.
 
 ### Package Versions
 
-We are requiring version `1.0.*` of monolog. This means any version in the `1.0`
-development branch. It would match `1.0.0`, `1.0.2` or `1.0.20`.
+In the previous example we were requiring version `1.0.*` of monolog. This
+means any version in the `1.0` development branch. It would match `1.0.0`,
+`1.0.2` or `1.0.20`.
 
 Version constraints can be specified in a few different ways.
 
-* **Exact version:** You can specify the exact version of a package, for
-  example `1.0.2`.
-
-* **Range:** By using comparison operators you can specify ranges of valid
-  versions. Valid operators are `>`, `>=`, `<`, `<=`, `!=`. An example range
-  would be `>=1.0`. You can define multiple ranges, separated by a comma:
-  `>=1.0,<2.0`.
-
-* **Wildcard:** You can specify a pattern with a `*` wildcard. `1.0.*` is the
-  equivalent of `>=1.0,<1.1`.
-
-* **Next Significant Release (Tilde Operator):** The `~` operator is best
-  explained by example: `~1.2` is equivalent to `>=1.2,<2.0`, while `~1.2.3` is
-  equivalent to `>=1.2.3,<1.3`. As you can see it is mostly useful for projects
-  respecting [semantic versioning](http://semver.org/). A common usage would be
-  to mark the minimum minor version you depend on, like `~1.2` (which allows
-  anything up to, but not including, 2.0). Since in theory there should be no
-  backwards compatibility breaks until 2.0, that works well. Another way of
-  looking at it is that using `~` specifies a minimum version, but allows the
-  last digit specified to go up.
+Name           | Example                                   | Description
+-------------- | ---------------------                     | -----------
+Exact version  | `1.0.2`                                   | You can specify the exact version of a package.
+Range          | `>=1.0` `>=1.0,<2.0` `>=1.0,<1.1 | >=1.2` | By using comparison operators you can specify ranges of valid versions. Valid operators are `>`, `>=`, `<`, `<=`, `!=`. <br />You can define multiple ranges, separated by a comma, which will be treated as a **logical AND**. A pipe symbol `|` will be treated as a **logical OR**. <br />AND has higher precedence than OR.
+Wildcard       | `1.0.*`                                   | You can specify a pattern with a `*` wildcard. `1.0.*` is the equivalent of `>=1.0,<1.1`.
+Tilde Operator | `~1.2`                                    | Very useful for projects that follow semantic versioning. `~1.2` is equivalent to `>=1.2,<2.0`. For more details, read the next section below.
+
+### Next Significant Release (Tilde Operator)
+
+The `~` operator is best explained by example: `~1.2` is equivalent to
+`>=1.2,<2.0`, while `~1.2.3` is equivalent to `>=1.2.3,<1.3`. As you can see
+it is mostly useful for projects respecting [semantic
+versioning](http://semver.org/). A common usage would be to mark the minimum
+minor version you depend on, like `~1.2` (which allows anything up to, but not
+including, 2.0). Since in theory there should be no backwards compatibility
+breaks until 2.0, that works well. Another way of looking at it is that using
+`~` specifies a minimum version, but allows the last digit specified to go up.
+
+### Stability
 
 By default only stable releases are taken into consideration. If you would like
 to also get RC, beta, alpha or dev versions of your dependencies you can do