diff --git a/README.md b/README.md
index a45f498..35d8196 100644
--- a/README.md
+++ b/README.md
@@ -24,16 +24,15 @@ components of the Nutils suite, from where it should be imortable as `SI`:
 ## Usage
 
 The SI module defines all base units and derived units of the International
-System of Units (SI) are predefined, as well as the full set of metric
-prefixes. Dimensional values are generated primarily by instantiating the
-Quantity type with a string value.
+System of Units (SI) plus an Angle dimension, as well as the full set of metric
+prefixes. Dimensional values are generated primarily by parsing a string value.
 
     >>> v = SI.parse('7μN*5h/6g')
 
-The Quantity constructor recognizes the multiplication (\*) and division (/)
-operators to separate factors. Every factor can be prefixed with a scale and
-suffixed with a power. The remainder must be either a unit, or else a unit with
-a metric prefix.
+The parser recognizes the multiplication (\*) and division (/) operators to
+separate factors. Every factor can be prefixed with a scale and suffixed with a
+power. The remainder must be either a unit, or else a unit with a metric
+prefix.
 
 In this example, the resulting object is of type "L/T", i.e. length over time,
 which is a subtype of Quantity that stores the powers L=1 and T=-1. Many
@@ -43,9 +42,9 @@ through manipulation.
     >>> type(v) == SI.Velocity == SI.Length / SI.Time
     True
 
-While Quantity can instantiate any subtype, we could have created the same
-object by instantiating Velocity directly, which has the advantage of verifying
-that the specified quantity is indeed of the desired dimension.
+While `parse` can instantiate any subtype of Quantity, we could have created
+the same object by instantiating Velocity directly, which has the advantage of
+verifying that the specified quantity is indeed of the desired dimension.
 
     >>> w = SI.Velocity('8km')
     Traceback (most recent call last):
@@ -56,7 +55,7 @@ Explicit subtypes can also be used in function annotations:
 
     >>> def f(size: SI.Length, load: SI.Force): pass
 
-The Quantity type acts as an opaque container. As long as a quantity has a
+The Quantity types act as an opaque container. As long as a quantity has a
 physical dimension, its value is inaccessible. The value can only be retrieved
 by dividing out a reference quantity, so that the result becomes dimensionless
 and the Quantity wrapper falls away.
@@ -64,8 +63,9 @@ and the Quantity wrapper falls away.
     >>> v / SI.parse('m/s')
     21.0
 
-To simplify this fairly common situation, any operation involving a Quantity
-and a string is handled by parsing the latter automatically.
+To simplify the fairly common situation that the reference quantity is a unit
+or another parsed value, any operation involving a Quantity and a string is
+handled by parsing the latter automatically.
 
     >>> v / 'm/s'
     21.0
@@ -101,36 +101,32 @@ In case the predefined set of dimensions and units are insufficient, both can
 be extended. For instance, though it is not part of the official SI system, it
 might be desirable to add an angular dimension. This is done by creating a new
 Dimension instance, using a symbol that avoids the existing symbols T, L, M, I,
-Θ, N and J:
+Θ, N, J and A:
 
-    >>> Angle = SI.Dimension.create('Φ')
+    >>> Xonon = SI.Dimension.create('X')
 
 At this point, the dimension is not very useful yet as it lacks units. To
-rectify this we define the radian by its abbreviation 'rad' in terms of the
-provided reference quantity, and assign it to the global table of units:
+rectify this we define the unit yam as being internally represented by a unit
+value:
 
-    >>> SI.units.rad = Angle.reference_quantity
+    >>> SI.units.yam = Xonon.reference_quantity
 
-Additional units can be defined by relating them to pre-existing ones:
+Additional units can be defined by relating them to pre-existing ones. Here we
+define the unit zop as the equal of 15 kilo-yam:
 
     >>> import math
-    >>> SI.units.deg = math.pi / 180 * SI.units.rad
+    >>> SI.units.zop = 15 * SI.units.kyam
 
 Alternatively, units can be defined using the same string syntax that is used
 by the Quantity constructor. Nevertheless, the following statement fails as we
 cannot define the same unit twice.
 
-    >>> SI.units.deg = '0.017453292519943295rad'
+    >>> SI.units.zop = '15kyam'
     Traceback (most recent call last):
          ...
-    ValueError: cannot define 'deg': unit is already defined
+    ValueError: cannot define 'zop': unit is already defined
 
 Having defined the new units we can directly use them:
 
-    >>> angle = SI.parse('30deg')
-
-Any function that accepts angular values will expect to receive them in a
-specific unit. The new Angle dimension makes this unit explicit:
-
-    >>> math.sin(angle / SI.units.rad)
-    0.49999999999999994
+    >>> SI.parse('24mzop/h')
+    0.1[X/T]