Added Indentation section to document the exact exapected behavior of…

… inedntation realted options

index.rst

@@ -235,7 +235,9 @@ and the supported values associated with them:
      - Supported values
    * - ``indent_style``
      - Set to ``tab`` or ``space`` to use hard tabs or soft tabs respectively. The
-       values are case insensitive.
+       values are case insensitive. Note that this settings signifies the indentation
+       style to be **preferred whenever possible**. The exact semantics with examples can be
+       found in the indentation_ section
    * - ``indent_size``
      - Set to a whole number defining the number of columns used for each
        indentation level and the width of soft tabs (when supported). If this
@@ -285,6 +287,52 @@ Pair keys are case insensitive. All keys are lowercased after parsing.
 Cores must accept keys and values with lengths up to and including 1024 and 4096 characters respectively.
 Beyond that, each implementation may choose to define its own upper limits or no explicit upper limits at all.
 
+.. indentation:
+
+Indentation
+=================================
+The indentation related options (``indent_style``, ``indent_size`` and ``tab_width``) require a special documentation
+section to specify their behavior. Let's assume we have the following code snippet::
+
+    def execute():
+        source = "indentation is important"
+        for i in source.split(" "):
+            print(i)
+
+The ``indent_size`` setting for this code snippet equals to 4, because ``indent_size`` actually means how much columns are required
+to indent the next line in relation to previous (if indentation, of course, is applicable for this line). Then the next question
+is *how* this indentation of 4 columns is actually achieved. It may be just 4 consequent spaces/soft tabs, or it equally might
+be just a single tab with width equal to 4, or two tabs with width equal to 2.
+
+This is when ``indent_style`` comes into picture. It specifies what character should be used **whenever possible** in order to
+achieve the indentation size specified in ``indent_size``. To fully understand what "whenever possible" actually means, lets
+assume that the editorconfig rules are specified for the file above::
+
+    root = true
+    [example_file.py]
+    indent_style = tab
+    indent_size = 4
+    tab_width = 3
+
+As we can notice, the ``indent_size`` of 4 is not achievable by placing 1 or 2 consequent tabs, because the ``tab_width``. Therefore,
+in order to comply with this editorconfig configuration, the new lines (where indentation is applicable, of course) **must be precisely
+indented with one tab, and one space**. That is because by placing one tab we're not achieving the ``indent_size`` required, but by
+placing the 2 consequent tabs we're overreaching. Therefore, although the preferable ``indent_style`` is tab, we still have to fallback
+to one space character to fulfill the requirement.
+
+Also as a consequence, when we have the following editorconfig rules defined::
+
+    root = true
+    [another_file.py]
+    indent_style = tab
+    indent_size = 8
+    tab_width = 4
+
+One **MUST** expect that spaces will not be used at all for indentation, since all the indentation can be achieved via tabs only
+
+As a side note - it is *not* restricted (although, it does not make much sense) by spec to have ``indent_size`` less then the ``tab_width``.
+In this case, regardless of ``indent_style``, only the spaces can be used to achieve the appropriate ``indent_size`` for obvious reasons.
+
 Suggestions for Plugin Developers
 =================================