From 8924bdf04489a93fcea408d0e45347b37a0d88a8 Mon Sep 17 00:00:00 2001
From: Paul Brossier <piem@piem.org>
Date: Wed, 21 Nov 2018 21:21:49 +0100
Subject: [PATCH] [doc] describe single-/double-precision modes

---
 doc/requirements.rst | 32 ++++++++++++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

diff --git a/doc/requirements.rst b/doc/requirements.rst
index 078f7c68..fcad2d1a 100644
--- a/doc/requirements.rst
+++ b/doc/requirements.rst
@@ -302,10 +302,38 @@ Here is an example of a custom command:
 Double precision
 ................
 
+The datatype used to store real numbers in aubio is named `smpl_t`. By default,
+`smpl_t` is defined as `float`, a `single-precision format
+<https://en.wikipedia.org/wiki/Single-precision_floating-point_format>`_
+(32-bit).  Some algorithms require a floating point representation with a
+higher precision, for instance to prevent arithmetic underflow in recursive
+filters.  In aubio, these special samples are named `lsmp_t` and defined as
+`double` by default (64-bit).
+
+Sometimes it may be useful to compile aubio in `double-precision`, for instance
+to reproduce numerical results obtained with 64-bit routines. In this case,
+`smpl_t` will be defined as `double`.
+
+The following table shows how `smpl_t` and `lsmp_t` are defined in single- and
+double-precision modes:
+
+.. list-table:: Single and double-precision modes
+   :align: center
+
+   * -
+     - single
+     - double
+   * - `smpl_t`
+     - ``float``
+     - ``double``
+   * - `lsmp_t`
+     - ``double``
+     - ``long double``
+
 To compile aubio in double precision mode, configure with ``--enable-double``.
 
-To compile aubio in single precision mode, use ``--disable-double`` (default,
-recommended).
+To compile in single-precision mode (default), use ``--disable-double`` (or
+simply none of these two options).
 
 Disabling the tests
 ...................
-- 
2.11.0