Add note about IEEE 1541 definitions of units

README.rst

@@ -91,6 +91,35 @@ Human friendly input/output (text formatting) on the command line based on the P
 
 .. [[[end]]]
 
+Note on units used
+------------------
+
+This package uses the traditional units based on powers of two. These units are
+still used in Microsoft Windows' graphical user interface and in other
+software.
+
++--------+----------------+
+| Unit   | Value in bytes |
++--------+----------------+
+| ``KB`` |          1024  |
++--------+----------------+
+| ``MB`` |       1048576  |
++--------+----------------+
+| ``GB`` |    1073741824  |
++--------+----------------+
+| ``TB`` | 1099511627776  |
++--------+----------------+
+| etc    |                |
++--------+----------------+
+
+The standard IEEE 1541, used by many hardware and software vendors today,
+contradicts this definition, using power of 10 units instead for ``kB``,
+``MB``, ``GB`` and so on. These definitions are often referred to as SI
+formatting, due to their similarity with the metric system. Thankfully, IEEE
+1541 also unambigously defines ``KiB``, ``MiB`` (etc) to the values based on
+powers of 2. This module does not yet support these units.
+
+
 Contact
 -------
 

humanfriendly/__init__.py

@@ -112,7 +112,8 @@ def format_size(num_bytes, keep_width=False):
                        ``False`` if they can be stripped.
     :returns: The corresponding human readable file size (a string).
 
-    This function supports ranges from kilobytes to terabytes.
+    This function supports ranges from kilobytes to terabytes. It only supports
+    the definitions that are based on powers of 2.
 
     Some examples:
 
@@ -143,6 +144,8 @@ def parse_size(size):
     :returns: The corresponding size in bytes (an integer).
     :raises: :exc:`InvalidSize` when the input can't be parsed.
 
+    This function only supports the definitions that are based on powers of 2.
+
     Some examples:
 
     >>> from humanfriendly import parse_size