diff --git a/docs/images/general_ellipsoid.png b/docs/images/general_ellipsoid.png
new file mode 100644
index 0000000000..f6191d465a
Binary files /dev/null and b/docs/images/general_ellipsoid.png differ
diff --git a/docs/images/general_ellipsoid.svg b/docs/images/general_ellipsoid.svg
new file mode 100644
index 0000000000..d9e69b7175
--- /dev/null
+++ b/docs/images/general_ellipsoid.svg
@@ -0,0 +1,227 @@
+
+
diff --git a/docs/source/operations/options/R.rst b/docs/source/operations/options/R.rst
index 6d1b597e4f..40ccc3847b 100644
--- a/docs/source/operations/options/R.rst
+++ b/docs/source/operations/options/R.rst
@@ -1,4 +1,6 @@
.. option:: +R=
- Radius of the sphere given in meters. If used in conjunction with ``+ellps``,
- ``+R`` takes precedence.
+ Radius of the sphere, given in meters. If used in conjunction with
+ ``+ellps``, :option:`+R` takes precedence.
+
+ See :ref:`ellipsoid_size_parameters` for more information.
diff --git a/docs/source/operations/options/ellps.rst b/docs/source/operations/options/ellps.rst
index b754f74187..9fda547f39 100644
--- a/docs/source/operations/options/ellps.rst
+++ b/docs/source/operations/options/ellps.rst
@@ -1,5 +1,8 @@
.. option:: +ellps=
- See :option:`proj -le` for a list of available ellipsoids.
+ The name of a built-in ellipsoid definition.
+
+ See :ref:`ellipsoids` for more information, or execute
+ :option:`proj -le` for a list of built-in ellipsoid names.
*Defaults to "GRS80".*
diff --git a/docs/source/usage/ellipsoids.rst b/docs/source/usage/ellipsoids.rst
new file mode 100644
index 0000000000..cd4b0c4307
--- /dev/null
+++ b/docs/source/usage/ellipsoids.rst
@@ -0,0 +1,159 @@
+.. _ellipsoids:
+
+================================================================================
+Ellipsoids
+================================================================================
+An ellipsoid is a mathematically defined surface which approximates the *geoid*:
+the surface of the Earth's gravity field, which is approximately the same as
+mean sea level.
+
+
+.. figure:: ../../images/general_ellipsoid.png
+ :width: 500 px
+ :align: center
+ :alt: Global and local fitting of the ellipsoid
+
+ Global and local fitting of the ellipsoid
+
+
+A complete ellipsoid definition comprises a size (primary) and a shape (secondary)
+parameter.
+
+.. _ellipsoid_size_parameters:
+
+Ellipsoid size parameters
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. option:: +R=
+
+ Radius of the sphere, :math:`R`.
+
+.. option:: +a=
+
+ Semi-major axis of the ellipsoid, :math:`a`.
+
+.. _ellipsoid_shape_parameters:
+
+Ellipsoid shape parameters
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. option:: +rf=
+
+ Reverse flattening of the ellipsoid, :math:`1/f`.
+
+.. option:: +f=
+
+ Flattening of the ellipsoid, :math:`f`.
+
+.. option:: +es=
+
+ Eccentricity squared, :math:`e^2`.
+
+.. option:: +e=
+
+ Eccentricity, :math:`e`.
+
+.. option:: +b=
+
+ Semi-minor axis, :math:`b`.
+
+The ellipsoid definition may be augmented with a spherification flag, turning
+the ellipsoid into a sphere with features defined by the ellipsoid.
+
+.. _ellipsoid_spherification_parameters:
+
+Ellipsoid spherification parameters
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. option:: +R_A=
+
+ A sphere with the same surface area as the ellipsoid.
+
+.. option:: +R_V=
+
+ A sphere with the same volume as the ellipsoid.
+
+.. option:: +R_a=
+
+ A sphere with :math:`R = (a + b)/2` (arithmetic mean).
+
+.. option:: +R_g=
+
+ A sphere with :math:`R = \sqrt{ab}` (geometric mean).
+
+.. option:: +R_h=
+
+ A sphere with :math:`R = 2ab/(a+b)` (harmonic mean).
+
+.. option:: +R_lat_a=
+
+ A sphere with :math:`R` being the arithmetic mean of the corresponding
+ ellipsoid at latitude :math:`\phi`.
+
+.. option:: +R_lat_g=
+
+ A sphere with :math:`R` being the geometric mean of the corresponding
+ ellipsoid at latitude :math:`\phi`.
+
+If :option:`+R` is given as size parameter, any shape and spherification
+parameters given are ignored.
+
+.. _ellipsoid_definitions:
+
+Built-in ellipsoid definitions
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The ``ellps=xxx`` parameter provides both size and shape for a number of
+built-in ellipsoid definitions.
+
+ ============ ================================= ============================
+ ellps Parameters Datum name
+ ============ ================================= ============================
+ GRS80 a=6378137.0 rf=298.257222101 GRS 1980(IUGG, 1980)
+ airy a=6377563.396 b=6356256.910 Airy 1830
+ bessel a=6377397.155 rf=299.1528128 Bessel 1841
+ clrk66 a=6378206.4 b=6356583.8 Clarke 1866
+ intl a=6378388.0 rf=297. International 1909 (Hayford)
+ WGS60 a=6378165.0 rf=298.3 WGS 60
+ WGS66 a=6378145.0 rf=298.25 WGS 66
+ WGS72 a=6378135.0 rf=298.26 WGS 72
+ WGS84 a=6378137.0 rf=298.257223563 WGS 84
+ sphere a=6370997.0 b=6370997.0 Normal Sphere (r=6370997)
+ ============ ================================= ============================
+
+If size and shape are given as ``ellps=xxx``, later shape and size parameters
+are are taken into account as modifiers for the built-in ellipsoid definition.
+
+While this may seem strange, it is in accordance with historical PROJ
+behavior. It can e.g. be used to define coordinates on the ellipsoid
+scaled to unit semimajor axis by specifying ``+ellps=xxx +a=1``
+
+.. _ellipsoid_transformation_examples:
+
+Transformation examples
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Spherical earth with radius 7000km:
+
+::
+
+ proj=laton R=7000000
+
+Using the GRS80 ellipsoid:
+
+::
+
+ proj=laton ellps=GRS80
+
+Expressing ellipsoid by semi-major axis and reverse flattening (:math:`1/f`):
+
+::
+
+ proj=laton a=6378137.0 rf=298.25
+
+Spherical earth based on volume of ellipsoid
+
+::
+
+ proj=laton a=6378137.0 rf=298.25 +R_V
+
diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst
index a074b18b9e..4bb7512161 100644
--- a/docs/source/usage/index.rst
+++ b/docs/source/usage/index.rst
@@ -15,6 +15,7 @@ command line applications or the C API that is a part of the software package.
quickstart
projections
transformation
+ ellipsoids
environmentvars
differences
network
diff --git a/src/ell_set.cpp b/src/ell_set.cpp
index f6599b9e36..f86bf65a28 100644
--- a/src/ell_set.cpp
+++ b/src/ell_set.cpp
@@ -51,7 +51,7 @@ int pj_ellipsoid (PJ *P) {
Spherification parameters supported are:
R_A, which gives a sphere with the same surface area as the ellipsoid
- R_A, which gives a sphere with the same volume as the ellipsoid
+ R_V, which gives a sphere with the same volume as the ellipsoid
R_a, which gives a sphere with R = (a + b)/2 (arithmetic mean)
R_g, which gives a sphere with R = sqrt(a*b) (geometric mean)