diff --git a/README.md b/README.md
index 7b41e82..bd03fd2 100644
--- a/README.md
+++ b/README.md
@@ -351,363 +351,254 @@
 
 ## Knobs
 
-`ALIGN_CLOSING_BRACKET_WITH_VISUAL_INDENT`
+#### `ALIGN_CLOSING_BRACKET_WITH_VISUAL_INDENT`
 
-    Align closing bracket with visual indentation.
+>    Align closing bracket with visual indentation.
 
-`ALLOW_MULTILINE_LAMBDAS`
+#### `ALLOW_MULTILINE_LAMBDAS`
 
-    Allow lambdas to be formatted on more than one line.
+>    Allow lambdas to be formatted on more than one line.
 
-`ALLOW_MULTILINE_DICTIONARY_KEYS`
+#### `ALLOW_MULTILINE_DICTIONARY_KEYS`
 
-    Allow dictionary keys to exist on multiple lines. For example:
+>    Allow dictionary keys to exist on multiple lines. For example:
 
 ```python
-        x = {
-            ('this is the first element of a tuple',
-             'this is the second element of a tuple'):
-                 value,
-        }
+    x = {
+        ('this is the first element of a tuple',
+         'this is the second element of a tuple'):
+             value,
+    }
 ```
 
-`ALLOW_SPLIT_BEFORE_DEFAULT_OR_NAMED_ASSIGNS`
+#### `ALLOW_SPLIT_BEFORE_DEFAULT_OR_NAMED_ASSIGNS`
 
-    Allow splitting before a default / named assignment in an argument list.
+>    Allow splitting before a default / named assignment in an argument list.
 
-`ALLOW_SPLIT_BEFORE_DICT_VALUE`
+#### `ALLOW_SPLIT_BEFORE_DICT_VALUE`
 
-    Allow splits before the dictionary value.
+>    Allow splits before the dictionary value.
 
-`ARITHMETIC_PRECEDENCE_INDICATION`
+#### `ARITHMETIC_PRECEDENCE_INDICATION`
 
-    Let spacing indicate operator precedence. For example:
+>    Let spacing indicate operator precedence. For example:
 
 ```python
-        a = 1 * 2 + 3 / 4
-        b = 1 / 2 - 3 * 4
-        c = (1 + 2) * (3 - 4)
-        d = (1 - 2) / (3 + 4)
-        e = 1 * 2 - 3
-        f = 1 + 2 + 3 + 4
+    a = 1 * 2 + 3 / 4
+    b = 1 / 2 - 3 * 4
+    c = (1 + 2) * (3 - 4)
+    d = (1 - 2) / (3 + 4)
+    e = 1 * 2 - 3
+    f = 1 + 2 + 3 + 4
 ```
 
-    will be formatted as follows to indicate precedence:
+>    will be formatted as follows to indicate precedence:
 
 ```python
-        a = 1*2 + 3/4
-        b = 1/2 - 3*4
-        c = (1+2) * (3-4)
-        d = (1-2) / (3+4)
-        e = 1*2 - 3
-        f = 1 + 2 + 3 + 4
+    a = 1*2 + 3/4
+    b = 1/2 - 3*4
+    c = (1+2) * (3-4)
+    d = (1-2) / (3+4)
+    e = 1*2 - 3
+    f = 1 + 2 + 3 + 4
 ```
 
-`BLANK_LINE_BEFORE_NESTED_CLASS_OR_DEF`
+#### `BLANK_LINES_AROUND_TOP_LEVEL_DEFINITION`
 
-    Insert a blank line before a `def` or `class` immediately nested within
-    another `def` or `class`. For example:
+>    Sets the number of desired blank lines surrounding top-level function and
+>    class definitions. For example:
 
 ```python
-        class Foo:
-                           # <------ this blank line
-            def method():
-                pass
+    class Foo:
+        pass
+                       # <------ having two blank lines here
+                       # <------ is the default setting
+    class Bar:
+        pass
 ```
 
-`BLANK_LINE_BEFORE_MODULE_DOCSTRING`
+#### `BLANK_LINE_BEFORE_CLASS_DOCSTRING`
 
-    Insert a blank line before a module docstring.
+>    Insert a blank line before a class-level docstring.
 
-`BLANK_LINE_BEFORE_CLASS_DOCSTRING`
+#### `BLANK_LINE_BEFORE_MODULE_DOCSTRING`
 
-    Insert a blank line before a class-level docstring.
+>    Insert a blank line before a module docstring.
 
-`BLANK_LINES_AROUND_TOP_LEVEL_DEFINITION`
+#### `BLANK_LINE_BEFORE_NESTED_CLASS_OR_DEF`
 
-    Sets the number of desired blank lines surrounding top-level function and
-    class definitions. For example:
+>    Insert a blank line before a `def` or `class` immediately nested within
+>    another `def` or `class`. For example:
 
 ```python
-        class Foo:
-            pass
-                           # <------ having two blank lines here
-                           # <------ is the default setting
-        class Bar:
+    class Foo:
+                       # <------ this blank line
+        def method():
             pass
 ```
 
-`BLANK_LINES_BETWEEN_TOP_LEVEL_IMPORTS_AND_VARIABLES`
+#### `BLANK_LINES_BETWEEN_TOP_LEVEL_IMPORTS_AND_VARIABLES`
 
-    Sets the number of desired blank lines between top-level imports and
-    variable definitions. Useful for compatibility with tools like isort.
+>    Sets the number of desired blank lines between top-level imports and
+>    variable definitions. Useful for compatibility with tools like isort.
 
-`COALESCE_BRACKETS`
+#### `COALESCE_BRACKETS`
 
-    Do not split consecutive brackets. Only relevant when
-    `DEDENT_CLOSING_BRACKETS` or `INDENT_CLOSING_BRACKETS` is set. For example:
+>    Do not split consecutive brackets. Only relevant when
+>    `DEDENT_CLOSING_BRACKETS` or `INDENT_CLOSING_BRACKETS` is set. For example:
 
 ```python
-        call_func_that_takes_a_dict(
-            {
-                'key1': 'value1',
-                'key2': 'value2',
-            }
-        )
-```
-
-    would reformat to:
-
-```python
-        call_func_that_takes_a_dict({
+    call_func_that_takes_a_dict(
+        {
             'key1': 'value1',
             'key2': 'value2',
-        })
-```
-
-`COLUMN_LIMIT`
-
-    The column limit (or max line-length)
-
-`CONTINUATION_ALIGN_STYLE`
-
-    The style for continuation alignment. Possible values are:
-
-    - `SPACE`: Use spaces for continuation alignment. This is default
-      behavior.
-    - `FIXED`: Use fixed number (CONTINUATION_INDENT_WIDTH) of columns
-      (ie: CONTINUATION_INDENT_WIDTH/INDENT_WIDTH tabs or
-      CONTINUATION_INDENT_WIDTH spaces) for continuation alignment.
-    - `VALIGN-RIGHT`: Vertically align continuation lines to multiple of
-      INDENT_WIDTH columns. Slightly right (one tab or a few spaces) if cannot
-      vertically align continuation lines with indent characters.
-
-`CONTINUATION_INDENT_WIDTH`
-
-    Indent width used for line continuations.
-
-`DEDENT_CLOSING_BRACKETS`
-
-    Put closing brackets on a separate line, dedented, if the bracketed
-    expression can't fit in a single line. Applies to all kinds of brackets,
-    including function definitions and calls. For example:
-
-```python
-        config = {
-            'key1': 'value1',
-            'key2': 'value2',
-        }  # <--- this bracket is dedented and on a separate line
-
-        time_series = self.remote_client.query_entity_counters(
-            entity='dev3246.region1',
-            key='dns.query_latency_tcp',
-            transform=Transformation.AVERAGE(window=timedelta(seconds=60)),
-            start_ts=now()-timedelta(days=3),
-            end_ts=now(),
-        )  # <--- this bracket is dedented and on a separate line
-```
-
-`DISABLE_ENDING_COMMA_HEURISTIC`
-
-    Disable the heuristic which places each list element on a separate line if
-    the list is comma-terminated.
-
-`EACH_DICT_ENTRY_ON_SEPARATE_LINE`
-
-    Place each dictionary entry onto its own line.
-
-`FORCE_MULTILINE_DICT`
-
-    Respect `EACH_DICT_ENTRY_ON_SEPARATE_LINE` even if the line is shorter than
-    `COLUMN_LIMIT`.
-
-`I18N_COMMENT`
-
-    The regex for an internationalization comment. The presence of this comment
-    stops reformatting of that line, because the comments are required to be
-    next to the string they translate.
-
-`I18N_FUNCTION_CALL`
-
-    The internationalization function call names. The presence of this function
-    stops reformatting on that line, because the string it has cannot be moved
-    away from the i18n comment.
-
-`INDENT_DICTIONARY_VALUE`
-
-    Indent the dictionary value if it cannot fit on the same line as the
-    dictionary key. For example:
-
-```python
-        config = {
-            'key1':
-                'value1',
-            'key2': value1 +
-                    value2,
         }
+    )
 ```
 
-`INDENT_WIDTH`
-
-    The number of columns to use for indentation.
-
-`INDENT_BLANK_LINES`
-
-    Set to `True` to prefer indented blank lines rather than empty
-
-`INDENT_CLOSING_BRACKETS`
-
-    Put closing brackets on a separate line, indented, if the bracketed
-    expression can't fit in a single line. Applies to all kinds of brackets,
-    including function definitions and calls. For example:
+>    would reformat to:
 
 ```python
-        config = {
-            'key1': 'value1',
-            'key2': 'value2',
-            }  # <--- this bracket is indented and on a separate line
-
-        time_series = self.remote_client.query_entity_counters(
-            entity='dev3246.region1',
-            key='dns.query_latency_tcp',
-            transform=Transformation.AVERAGE(window=timedelta(seconds=60)),
-            start_ts=now()-timedelta(days=3),
-            end_ts=now(),
-            )  # <--- this bracket is indented and on a separate line
+    call_func_that_takes_a_dict({
+        'key1': 'value1',
+        'key2': 'value2',
+    })
 ```
 
-`JOIN_MULTIPLE_LINES`
+#### `COLUMN_LIMIT`
 
-    Join short lines into one line. E.g., single line `if` statements.
+>    The column limit (or max line-length)
 
-`NO_SPACES_AROUND_SELECTED_BINARY_OPERATORS`
+#### `CONTINUATION_ALIGN_STYLE`
 
-    Do not include spaces around selected binary operators. For example:
+>    The style for continuation alignment. Possible values are:
+
+>    - `SPACE`: Use spaces for continuation alignment. This is default
+>      behavior.
+>    - `FIXED`: Use fixed number (`CONTINUATION_INDENT_WIDTH`) of columns
+>      (i.e. `CONTINUATION_INDENT_WIDTH`/`INDENT_WIDTH` tabs or
+>      `CONTINUATION_INDENT_WIDTH` spaces) for continuation alignment.
+>    - `VALIGN-RIGHT`: Vertically align continuation lines to multiple of
+>      `INDENT_WIDTH` columns. Slightly right (one tab or a few spaces) if cannot
+>      vertically align continuation lines with indent characters.
+
+#### `CONTINUATION_INDENT_WIDTH`
+
+>    Indent width used for line continuations.
+
+#### `DEDENT_CLOSING_BRACKETS`
+
+>    Put closing brackets on a separate line, dedented, if the bracketed
+>    expression can't fit in a single line. Applies to all kinds of brackets,
+>    including function definitions and calls. For example:
 
 ```python
-        1 + 2 * 3 - 4 / 5
+    config = {
+        'key1': 'value1',
+        'key2': 'value2',
+    }  # <--- this bracket is dedented and on a separate line
+
+    time_series = self.remote_client.query_entity_counters(
+        entity='dev3246.region1',
+        key='dns.query_latency_tcp',
+        transform=Transformation.AVERAGE(window=timedelta(seconds=60)),
+        start_ts=now()-timedelta(days=3),
+        end_ts=now(),
+    )  # <--- this bracket is dedented and on a separate line
 ```
 
-    will be formatted as follows when configured with `*`, `/`:
+#### `DISABLE_ENDING_COMMA_HEURISTIC`
+
+>    Disable the heuristic which places each list element on a separate line if
+>    the list is comma-terminated.
+
+#### `EACH_DICT_ENTRY_ON_SEPARATE_LINE`
+
+>    Place each dictionary entry onto its own line.
+
+#### `FORCE_MULTILINE_DICT`
+
+>    Respect `EACH_DICT_ENTRY_ON_SEPARATE_LINE` even if the line is shorter than
+>    `COLUMN_LIMIT`.
+
+#### `I18N_COMMENT`
+
+>    The regex for an internationalization comment. The presence of this comment
+>    stops reformatting of that line, because the comments are required to be
+>    next to the string they translate.
+
+#### `I18N_FUNCTION_CALL`
+
+>    The internationalization function call names. The presence of this function
+>    stops reformatting on that line, because the string it has cannot be moved
+>    away from the i18n comment.
+
+#### `INDENT_BLANK_LINES`
+
+>    Set to `True` to prefer indented blank lines rather than empty
+
+#### `INDENT_CLOSING_BRACKETS`
+
+>    Put closing brackets on a separate line, indented, if the bracketed
+>    expression can't fit in a single line. Applies to all kinds of brackets,
+>    including function definitions and calls. For example:
 
 ```python
-        1 + 2*3 - 4/5
+    config = {
+        'key1': 'value1',
+        'key2': 'value2',
+        }  # <--- this bracket is indented and on a separate line
+
+    time_series = self.remote_client.query_entity_counters(
+        entity='dev3246.region1',
+        key='dns.query_latency_tcp',
+        transform=Transformation.AVERAGE(window=timedelta(seconds=60)),
+        start_ts=now()-timedelta(days=3),
+        end_ts=now(),
+        )  # <--- this bracket is indented and on a separate line
 ```
 
-`SPACES_AROUND_POWER_OPERATOR`
+#### `INDENT_DICTIONARY_VALUE`
 
-    Set to `True` to prefer using spaces around `**`.
-
-`SPACES_AROUND_DEFAULT_OR_NAMED_ASSIGN`
-
-    Set to `True` to prefer spaces around the assignment operator for default
-    or keyword arguments.
-
-`SPACES_AROUND_DICT_DELIMITERS`
-
-    Adds a space after the opening '{' and before the ending '}' dict delimiters.
+>    Indent the dictionary value if it cannot fit on the same line as the
+>    dictionary key. For example:
 
 ```python
-        {1: 2}
+    config = {
+        'key1':
+            'value1',
+        'key2': value1 +
+                value2,
+    }
 ```
 
-    will be formatted as:
+#### `INDENT_WIDTH`
+
+>    The number of columns to use for indentation.
+
+#### `JOIN_MULTIPLE_LINES`
+
+>    Join short lines into one line. E.g., single line `if` statements.
+
+#### `NO_SPACES_AROUND_SELECTED_BINARY_OPERATORS`
+
+>    Do not include spaces around selected binary operators. For example:
 
 ```python
-        { 1: 2 }
+    1 + 2 * 3 - 4 / 5
 ```
 
-`SPACES_AROUND_LIST_DELIMITERS`
-
-    Adds a space after the opening '[' and before the ending ']' list delimiters.
+>    will be formatted as follows when configured with `*`, `/`:
 
 ```python
-        [1, 2]
+    1 + 2*3 - 4/5
 ```
 
-    will be formatted as:
+#### `SPACE_BETWEEN_ENDING_COMMA_AND_CLOSING_BRACKET`
 
-```python
-        [ 1, 2 ]
-```
+>    Insert a space between the ending comma and closing bracket of a list, etc.
 
-`SPACES_AROUND_SUBSCRIPT_COLON`
-
-    Use spaces around the subscript / slice operator.  For example:
-
-```python
-        my_list[1 : 10 : 2]
-```
-
-`SPACES_AROUND_TUPLE_DELIMITERS`
-
-    Adds a space after the opening '(' and before the ending ')' tuple delimiters.
-
-```python
-        (1, 2, 3)
-```
-
-    will be formatted as:
-
-```python
-        ( 1, 2, 3 )
-```
-
-`SPACES_BEFORE_COMMENT`
-
-    The number of spaces required before a trailing comment.
-    This can be a single value (representing the number of spaces
-    before each trailing comment) or list of values (representing
-    alignment column values; trailing comments within a block will
-    be aligned to the first column value that is greater than the maximum
-    line length within the block).
-
-    > **Note:** Lists of values may need to be quoted in some contexts
-    > (eg. shells or editor config files).
-
-    For example, with `spaces_before_comment=5`:
-
-```python
-        1 + 1 # Adding values
-```
-
-    will be formatted as:
-
-```python
-        1 + 1     # Adding values <-- 5 spaces between the end of the statement and comment
-```
-
-    with `spaces_before_comment="15, 20"`:
-
-```python
-        1 + 1 # Adding values
-        two + two # More adding
-
-        longer_statement # This is a longer statement
-        short # This is a shorter statement
-
-        a_very_long_statement_that_extends_beyond_the_final_column # Comment
-        short # This is a shorter statement
-```
-
-    will be formatted as:
-
-```python
-        1 + 1          # Adding values <-- end of line comments in block aligned to col 15
-        two + two      # More adding
-
-        longer_statement    # This is a longer statement <-- end of line comments in block aligned to col 20
-        short               # This is a shorter statement
-
-        a_very_long_statement_that_extends_beyond_the_final_column  # Comment <-- the end of line comments are aligned based on the line length
-        short                                                       # This is a shorter statement
-```
-
-`SPACE_BETWEEN_ENDING_COMMA_AND_CLOSING_BRACKET`
-
-    Insert a space between the ending comma and closing bracket of a list, etc.
-
-`SPACE_INSIDE_BRACKETS`
+#### `SPACE_INSIDE_BRACKETS`
 
     Use spaces inside brackets, braces, and parentheses.  For example:
 
@@ -717,177 +608,286 @@
         my_set = { 1, 2, 3 }
 ```
 
-`SPLIT_ARGUMENTS_WHEN_COMMA_TERMINATED`
+#### `SPACES_AROUND_DEFAULT_OR_NAMED_ASSIGN`
 
-    Split before arguments if the argument list is terminated by a comma.
+>    Set to `True` to prefer spaces around the assignment operator for default
+>    or keyword arguments.
 
-`SPLIT_ALL_COMMA_SEPARATED_VALUES`
+#### `SPACES_AROUND_DICT_DELIMITERS`
 
-    If a comma separated list (`dict`, `list`, `tuple`, or function `def`) is
-    on a line that is too long, split such that each element is on a separate
-    line.
-
-`SPLIT_ALL_TOP_LEVEL_COMMA_SEPARATED_VALUES`
-
-    Variation on `SPLIT_ALL_COMMA_SEPARATED_VALUES` in which, if a
-    subexpression with a comma fits in its starting line, then the
-    subexpression is not split. This avoids splits like the one for
-    `b` in this code:
+>    Adds a space after the opening '{' and before the ending '}' dict delimiters.
 
 ```python
-        abcdef(
-            aReallyLongThing: int,
-            b: [Int,
-                Int])
+        {1: 2}
 ```
 
-    with the new knob this is split as:
+>    will be formatted as:
 
 ```python
-        abcdef(
-            aReallyLongThing: int,
-            b: [Int, Int])
+        { 1: 2 }
 ```
 
-`SPLIT_BEFORE_BITWISE_OPERATOR`
+#### `SPACES_AROUND_LIST_DELIMITERS`
 
-    Set to `True` to prefer splitting before `&`, `|` or `^` rather than after.
-
-`SPLIT_BEFORE_ARITHMETIC_OPERATOR`
-
-    Set to `True` to prefer splitting before `+`, `-`, `*`, `/`, `//`, or `@`
-    rather than after.
-
-`SPLIT_BEFORE_CLOSING_BRACKET`
-
-    Split before the closing bracket if a `list` or `dict` literal doesn't fit
-    on a single line.
-
-`SPLIT_BEFORE_DICT_SET_GENERATOR`
-
-    Split before a dictionary or set generator (`comp_for`). For example, note
-    the split before the `for`:
+>    Adds a space after the opening '[' and before the ending ']' list delimiters.
 
 ```python
-        foo = {
-            variable: 'Hello world, have a nice day!'
-            for variable in bar if variable != 42
-        }
+    [1, 2]
 ```
 
-`SPLIT_BEFORE_DOT`
-
-    Split before the `.` if we need to split a longer expression:
+>    will be formatted as:
 
 ```python
-        foo = ('This is a really long string: {}, {}, {}, {}'.format(a, b, c, d))
+    [ 1, 2 ]
 ```
 
-    would reformat to something like:
+#### `SPACES_AROUND_POWER_OPERATOR`
+
+>    Set to `True` to prefer using spaces around `**`.
+
+#### `SPACES_AROUND_SUBSCRIPT_COLON`
+
+>    Use spaces around the subscript / slice operator.  For example:
 
 ```python
-        foo = ('This is a really long string: {}, {}, {}, {}'
-               .format(a, b, c, d))
+    my_list[1 : 10 : 2]
 ```
 
-`SPLIT_BEFORE_EXPRESSION_AFTER_OPENING_PAREN`
+##### `SPACES_AROUND_TUPLE_DELIMITERS`
 
-    Split after the opening paren which surrounds an expression if it doesn't
-    fit on a single line.
-
-`SPLIT_BEFORE_FIRST_ARGUMENT`
-
-    If an argument / parameter list is going to be split, then split before the
-    first argument.
-
-`SPLIT_BEFORE_LOGICAL_OPERATOR`
-
-    Set to `True` to prefer splitting before `and` or `or` rather than after.
-
-`SPLIT_BEFORE_NAMED_ASSIGNS`
-
-    Split named assignments onto individual lines.
-
-`SPLIT_COMPLEX_COMPREHENSION`
-
-    For list comprehensions and generator expressions with multiple clauses
-    (e.g multiple `for` calls, `if` filter expressions) and which need to be
-    reflowed, split each clause onto its own line. For example:
+>    Adds a space after the opening '(' and before the ending ')' tuple delimiters.
 
 ```python
-        result = [
-            a_var + b_var for a_var in xrange(1000) for b_var in xrange(1000)
-            if a_var % b_var]
+    (1, 2, 3)
 ```
 
-    would reformat to something like:
+>    will be formatted as:
 
 ```python
-        result = [
-            a_var + b_var
-            for a_var in xrange(1000)
-            for b_var in xrange(1000)
-            if a_var % b_var]
+    ( 1, 2, 3 )
 ```
 
-`SPLIT_PENALTY_AFTER_OPENING_BRACKET`
+#### `SPACES_BEFORE_COMMENT`
 
-    The penalty for splitting right after the opening bracket.
+>    The number of spaces required before a trailing comment.
+>    This can be a single value (representing the number of spaces
+>    before each trailing comment) or list of values (representing
+>    alignment column values; trailing comments within a block will
+>    be aligned to the first column value that is greater than the maximum
+>    line length within the block).
 
-`SPLIT_PENALTY_AFTER_UNARY_OPERATOR`
+> **Note:** Lists of values may need to be quoted in some contexts
+> (eg. shells or editor config files).
 
-    The penalty for splitting the line after a unary operator.
-
-`SPLIT_PENALTY_ARITHMETIC_OPERATOR`
-
-    The penalty of splitting the line around the `+`, `-`, `*`, `/`, `//`, `%`,
-    and `@` operators.
-
-`SPLIT_PENALTY_BEFORE_IF_EXPR`
-
-    The penalty for splitting right before an `if` expression.
-
-`SPLIT_PENALTY_BITWISE_OPERATOR`
-
-    The penalty of splitting the line around the `&`, `|`, and `^` operators.
-
-`SPLIT_PENALTY_COMPREHENSION`
-
-    The penalty for splitting a list comprehension or generator expression.
-
-`SPLIT_PENALTY_EXCESS_CHARACTER`
-
-    The penalty for characters over the column limit.
-
-`SPLIT_PENALTY_FOR_ADDED_LINE_SPLIT`
-
-    The penalty incurred by adding a line split to the logical line. The more
-    line splits added the higher the penalty.
-
-`SPLIT_PENALTY_IMPORT_NAMES`
-
-    The penalty of splitting a list of `import as` names. For example:
+>    For example, with `spaces_before_comment=5`:
 
 ```python
-        from a_very_long_or_indented_module_name_yada_yad import (long_argument_1,
-                                                                  long_argument_2,
-                                                                  long_argument_3)
+    1 + 1 # Adding values
 ```
 
-    would reformat to something like:
+>    will be formatted as:
 
 ```python
-        from a_very_long_or_indented_module_name_yada_yad import (
-            long_argument_1, long_argument_2, long_argument_3)
+    1 + 1     # Adding values <-- 5 spaces between the end of the statement and comment
 ```
 
-`SPLIT_PENALTY_LOGICAL_OPERATOR`
+>    with `spaces_before_comment="15, 20"`:
 
-    The penalty of splitting the line around the `and` and `or` operators.
+```python
+    1 + 1 # Adding values
+    two + two # More adding
 
-`USE_TABS`
+    longer_statement # This is a longer statement
+    short # This is a shorter statement
 
-    Use the Tab character for indentation.
+    a_very_long_statement_that_extends_beyond_the_final_column # Comment
+    short # This is a shorter statement
+```
+
+>    will be formatted as:
+
+```python
+    1 + 1          # Adding values <-- end of line comments in block aligned to col 15
+    two + two      # More adding
+
+    longer_statement    # This is a longer statement <-- end of line comments in block aligned to col 20
+    short               # This is a shorter statement
+
+    a_very_long_statement_that_extends_beyond_the_final_column  # Comment <-- the end of line comments are aligned based on the line length
+    short                                                       # This is a shorter statement
+```
+
+#### `SPLIT_ALL_COMMA_SEPARATED_VALUES`
+
+>    If a comma separated list (`dict`, `list`, `tuple`, or function `def`) is
+>    on a line that is too long, split such that each element is on a separate
+>    line.
+
+#### `SPLIT_ALL_TOP_LEVEL_COMMA_SEPARATED_VALUES`
+
+>    Variation on `SPLIT_ALL_COMMA_SEPARATED_VALUES` in which, if a
+>    subexpression with a comma fits in its starting line, then the
+>    subexpression is not split. This avoids splits like the one for
+>    `b` in this code:
+
+```python
+    abcdef(
+        aReallyLongThing: int,
+        b: [Int,
+            Int])
+```
+
+>    with the new knob this is split as:
+
+```python
+    abcdef(
+        aReallyLongThing: int,
+        b: [Int, Int])
+```
+
+#### `SPLIT_ARGUMENTS_WHEN_COMMA_TERMINATED`
+
+>    Split before arguments if the argument list is terminated by a comma.
+
+#### `SPLIT_BEFORE_ARITHMETIC_OPERATOR`
+
+>    Set to `True` to prefer splitting before `+`, `-`, `*`, `/`, `//`, or `@`
+>    rather than after.
+
+#### `SPLIT_BEFORE_BITWISE_OPERATOR`
+
+>    Set to `True` to prefer splitting before `&`, `|` or `^` rather than after.
+
+#### `SPLIT_BEFORE_CLOSING_BRACKET`
+
+>    Split before the closing bracket if a `list` or `dict` literal doesn't fit
+>    on a single line.
+
+#### `SPLIT_BEFORE_DICT_SET_GENERATOR`
+
+>    Split before a dictionary or set generator (`comp_for`). For example, note
+>    the split before the `for`:
+
+```python
+    foo = {
+        variable: 'Hello world, have a nice day!'
+        for variable in bar if variable != 42
+    }
+```
+
+#### `SPLIT_BEFORE_DOT`
+
+>    Split before the `.` if we need to split a longer expression:
+
+```python
+    foo = ('This is a really long string: {}, {}, {}, {}'.format(a, b, c, d))
+```
+
+>    would reformat to something like:
+
+```python
+    foo = ('This is a really long string: {}, {}, {}, {}'
+           .format(a, b, c, d))
+```
+
+#### `SPLIT_BEFORE_EXPRESSION_AFTER_OPENING_PAREN`
+
+>    Split after the opening paren which surrounds an expression if it doesn't
+>    fit on a single line.
+
+#### `SPLIT_BEFORE_FIRST_ARGUMENT`
+
+>    If an argument / parameter list is going to be split, then split before the
+>    first argument.
+
+#### `SPLIT_BEFORE_LOGICAL_OPERATOR`
+
+>    Set to `True` to prefer splitting before `and` or `or` rather than after.
+
+#### `SPLIT_BEFORE_NAMED_ASSIGNS`
+
+>    Split named assignments onto individual lines.
+
+#### `SPLIT_COMPLEX_COMPREHENSION`
+
+>    For list comprehensions and generator expressions with multiple clauses
+>    (e.g multiple `for` calls, `if` filter expressions) and which need to be
+>    reflowed, split each clause onto its own line. For example:
+
+```python
+    result = [
+        a_var + b_var for a_var in xrange(1000) for b_var in xrange(1000)
+        if a_var % b_var]
+```
+
+>    would reformat to something like:
+
+```python
+    result = [
+        a_var + b_var
+        for a_var in xrange(1000)
+        for b_var in xrange(1000)
+        if a_var % b_var]
+```
+
+#### `SPLIT_PENALTY_AFTER_OPENING_BRACKET`
+
+>    The penalty for splitting right after the opening bracket.
+
+#### `SPLIT_PENALTY_AFTER_UNARY_OPERATOR`
+
+>    The penalty for splitting the line after a unary operator.
+
+#### `SPLIT_PENALTY_ARITHMETIC_OPERATOR`
+
+>    The penalty of splitting the line around the `+`, `-`, `*`, `/`, `//`, `%`,
+>    and `@` operators.
+
+#### `SPLIT_PENALTY_BEFORE_IF_EXPR`
+
+>    The penalty for splitting right before an `if` expression.
+
+#### `SPLIT_PENALTY_BITWISE_OPERATOR`
+
+>    The penalty of splitting the line around the `&`, `|`, and `^` operators.
+
+#### `SPLIT_PENALTY_COMPREHENSION`
+
+>    The penalty for splitting a list comprehension or generator expression.
+
+#### `SPLIT_PENALTY_EXCESS_CHARACTER`
+
+>    The penalty for characters over the column limit.
+
+#### `SPLIT_PENALTY_FOR_ADDED_LINE_SPLIT`
+
+>    The penalty incurred by adding a line split to the logical line. The more
+>    line splits added the higher the penalty.
+
+#### `SPLIT_PENALTY_IMPORT_NAMES`
+
+>    The penalty of splitting a list of `import as` names. For example:
+
+```python
+    from a_very_long_or_indented_module_name_yada_yad import (long_argument_1,
+                                                              long_argument_2,
+                                                              long_argument_3)
+```
+
+>    would reformat to something like:
+
+```python
+    from a_very_long_or_indented_module_name_yada_yad import (
+        long_argument_1, long_argument_2, long_argument_3)
+```
+
+#### `SPLIT_PENALTY_LOGICAL_OPERATOR`
+
+>    The penalty of splitting the line around the `and` and `or` operators.
+
+#### `USE_TABS`
+
+>    Use the Tab character for indentation.
 
 
 ## (Potentially) Frequently Asked Questions