fix issue #51: separate indent levels for mappings and sequences0.15.29

**When this resolves the reported problem, please close this issue**

4 files changed, 21 insertions, 21 deletions

diff --git a/_doc/api.ryd b/_doc/api.ryd
index c03355a..6a94044 100644
--- a/_doc/api.ryd
+++ b/_doc/api.ryd
@@ -183,8 +183,7 @@ if ruamel.yaml.version_info < (0, 15):
         def __init__(self):
             yaml.YAML.__init__(self)
             self.preserve_quotes = True
-            self.indent = 4
-            self.block_seq_indent = 2
+            self.indent(mapping=4, sequence=4, offset=2)
 # in your code
 try:
     from myyaml import MyYAML
diff --git a/_doc/detail.ryd b/_doc/detail.ryd
index e3243a2..7867169 100644
--- a/_doc/detail.ryd
+++ b/_doc/detail.ryd
@@ -55,7 +55,8 @@ back to::
   -   b: 1
   -   2
 
-if you specify ``yaml.indent = 4``.
+if you specify ``yaml.indent(sequence=4)`` (indentation is counted to the
+beginning of the sequence element).
 
 PyYAML (and older versions of ruamel.yaml) gives you non-indented
 scalars (when specifying default_flow_style=False)::
@@ -64,27 +65,30 @@ scalars (when specifying default_flow_style=False)::
   -   b: 1
   - 2
 
-The dump also observes an additional ``block_seq_indent`` settingr that
-can be used to push the dash inwards, *within the space defined by* ``indent``.
+You can use ``mapping=4`` to also have the mappings values indented.
+The dump also observes an additional ``offset=2`` setting that
+can be used to push the dash inwards, *within the space defined by* ``sequence``.
 
-The above example with the often seen ``yaml.indent = 4; yaml.block_seq_indent = 2``
+The above example with the often seen ``yaml.indent(mapping=2, sequence=4, offset=2)``
 indentation::
 
   x:
-    - b: 1
-    - 2
+    y:
+      - b: 1
+      - 2
 
+The defaults are as if you specified ``yaml.indent(mapping=2, sequence=2, offset=0)``.
 
-If the ``block_seq_indent`` equals ``indent``, there is not enough
-room for the dash and the space that has to follow. In that case the
+If the ``offset`` equals ``sequence``, there is not enough
+room for the dash and the space that has to follow it. In that case the
 element itself would normally be pushed to the next line (and older versions
 of ruamel.yaml did so). But this is
 prevented from happening. However the ``indent`` level is what is used
 for calculating the cumulative indent for deeper levels and specifying
-``yaml.indent = 3`` resp. ``yaml.block_seq_indent = 2``, migth give correct, but counter
+``sequence=3`` resp. ``offset=2``, might give correct, but counter
 intuitive results.
 
-**It is best to always have** ``indent >= block_seq_indent + 2``
+**It is best to always have** ``sequence >= offset + 2``
 **but this is not enforced**. Depending on your structure, not following
 this advice **might lead to invalid output**.
 
diff --git a/_doc/example.ryd b/_doc/example.ryd
index 83681e3..58a5a1e 100644
--- a/_doc/example.ryd
+++ b/_doc/example.ryd
@@ -136,8 +136,7 @@ The following program with three dumps::
   yaml = YAML()
   yaml.explicit_start = True
   yaml.dump(data, sys.stdout)
-  yaml.indent = 4
-  yaml.block_seq_indent = 2
+  yaml.indent(sequence=4, offset=2)
   yaml.dump(data, sys.stdout)
 
 
@@ -204,7 +203,7 @@ you really need to have it (or think you do)::
 
 --- !python |
 import sys
-from ruamel.yaml import YAML 
+from ruamel.yaml import YAML
 from ruamel.yaml.compat import StringIO
 
 class MyYAML(YAML):
diff --git a/_doc/overview.ryd b/_doc/overview.ryd
index 914d909..de51ddd 100644
--- a/_doc/overview.ryd
+++ b/_doc/overview.ryd
@@ -28,12 +28,10 @@ Reassigning values or replacing list items, etc., is fine.
 
 For the specific 1.2 differences see :ref:`yaml-1-2-support`
 
-Although individual indentation of lines is not preserved, you can
-specify both indentation (counting for this does **not** include the
-dash for a sequence element) and specific offset of block sequence
-dashes within that indentation. There is a utility function that tries
-to determine the correct values for ``indent`` and
-``block_seq_indent`` that can then be passed to the dumper.
+Although individual indentation of lines is not preserved, you can specify
+separate indentation levels for mappings and sequences (counting for sequences
+does **not** include the dash for a sequence element) and specific offset of
+block sequence dashes within that indentation.
 
 
 Although ``ruamel.yaml`` still allows most of the PyYAML way of doing