-A spatial vector is similar to a position, but instead using
-absolute world coordinates, it uses *relative* coordinates, relative to
-no particular point.
-
-Internally, it is implemented as a table with the 3 fields
-`x`, `y` and `z`. Example: `{x = 0, y = 1, z = 0}`.
-However, one should *never* create a vector manually as above, such misbehavior
-is deprecated. The vector helpers set a metatable for the created vectors which
-allows indexing with numbers, calling functions directly on vectors and using
-operators (like `+`). Furthermore, the internal implementation might change in
+
+Minetest stores 3-dimensional spatial vectors in Lua as tables of 3 coordinates,
+and has a class to represent them (`vector.*`), which this chapter is about.
+For details on what a spatial vectors is, please refer to Wikipedia:
+https://en.wikipedia.org/wiki/Euclidean_vector.
+
+Spatial vectors are used for various things, including, but not limited to:
+
+* any 3D spatial vector (x/y/z-directions)
+* Euler angles (pitch/yaw/roll in radians) (Spatial vectors have no real semantic
+ meaning here. Therefore, most vector operations make no sense in this use case.)
+
+Note that they are *not* used for:
+
+* n-dimensional vectors where n is not 3 (ie. n=2)
+* arrays of the form `{num, num, num}`
+
+The API documentation may refer to spatial vectors, as produced by `vector.new`,
+by any of the following notations:
+
+* `(x, y, z)` (Used rarely, and only if it's clear that it's a vector.)
+* `vector.new(x, y, z)`
+* `{x=num, y=num, z=num}` (Even here you are still supposed to use `vector.new`.)
+
+Compatibility notes
+-------------------
+
+Vectors used to be defined as tables of the form `{x = num, y = num, z = num}`.
+Since Minetest 5.5.0, vectors additionally have a metatable to enable easier use.
+Note: Those old-style vectors can still be found in old mod code. Hence, mod and
+engine APIs still need to be able to cope with them in many places.
+
+Manually constructed tables are deprecated and highly discouraged. This interface
+should be used to ensure seamless compatibility between mods and the Minetest API.
+This is especially important to callback function parameters and functions overwritten
+by mods.
+Also, though not likely, the internal implementation of a vector might change in