docs: Update documentation with new multiplexer sections

Also, remove the references to the old system.
Signed-off-by: NRuda Moura <rmoura@redhat.com>

docs/source/MultiplexConfig.rst

@@ -9,71 +9,137 @@ of key/value pairs within combination's of various categories,
 that will be passed to avocado test as parameters in a dictionary
 called ``params``. The format simplifies and condenses complex
 multidimensional arrays of test parameters into a flat list. The
-combinatorial result can be filtered and adjusted prior to testing,
-with filters, dependencies, and key/value substitutions.
+combinatorial result can be filtered and adjusted prior to testing.
 
-The parser relies on indentation, and is very sensitive to misplacement
-of tab and space characters. It's highly recommended to edit/view
-Multiplex Configuration files in an editor capable of collapsing tab
-characters into four space characters. Improper attention to column
-spacing can drastically affect output.
+The parser relies on `YAML <http://www.yaml.org/>`_, a human friendly
+markup language.  The YAML format allows one to create, manually or
+with code automation, multiple configurations for the tests. You can use any
+text editor to write YAML files, but choose one that supports syntax
+enhancements and basic validation, it saves time!
+
+Here is how a simple and valid multiplex configuration looks like::
+
+    # Multiplex config example, file sleep.yaml
+    short:
+        sleep_length: 1
+    medium:
+        sleep_length: 60
+    long:
+        sleep_length: 600
+
+The key concepts here are ``nodes`` (provides context and scope), ``keys`` (think of variables) and ``values`` (scalar or lists).
+In the next section, we will describe these concepts in more details.
+
+.. _nodes:
+
+Nodes
+=====
+
+Nodes servers for two purposes, to name or describe a discrete point of information
+and to store in a set of key/values (possibly empty). Basically nodes can contains
+other nodes, so will have the parent and child relationship in a tree structure.
+
+The tree node structure can be obtained by using the command line
+``avocado plugins --tree <file>`` and for previous example,
+it looks just like this::
+
+    avocado multiplex --tree sleep.yaml
+    Config file tree structure:
+
+         /-short
+        |
+    -/root-medium
+        |
+         \-long
+
+The node structure contains a special node ``/root``, which is
+implicitly included in every file parsed file by the multiplexer and
+the nodes that we have created, which are ``short``, ``medium`` and ``long``.
+
+It helps if you see the tree structure as a set of paths
+separated by ``/``, much like paths in the file system.
+
+In the example we have being working on, there are only three paths:
+
+- ``//root/short``
+- ``//root/medium``
+- ``//root/long``
+
+The ending nodes (the leafs on the tree) will become part of all lower-level
+(i.e. further indented) variant stanzas (see section variants_).
+However, the precedence is evaluated in top-down or ``last defined`` order.
+In other words, the last parsed has precedence over earlier definitions.
 
 .. _keys_and_values:
 
-Keys and values
+Keys and Values
 ===============
 
 Keys and values are the most basic useful facility provided by the
-format. A statement in the form ``<key> = <value>`` sets ``<key>`` to
-``<value>``. Values are strings, terminated by a linefeed, with
-surrounding quotes completely optional (but honored). A reference of
-descriptions for most keys is included in section Configuration Parameter
-Reference.
+format. A statement in the form ``<key>: <value>`` sets ``<key>`` to
+``<value>``.
+
+Values are numbers, strings and lists. Some examples of literal values:
+
+- Booleans: ``true`` and ``false``.
+- Numbers: 123 (integer), 3.1415 (float point)
+- Strings: 'This is a string'
+
+And lists::
+
+    cflags:
+        - '-O2'
+        - '-g'
+        - '-Wall'
+
+The list above will become ``['-O2', '-g', '-Wall']`` to Python. In fact,
+YAML is compatible to JSON.
+.. _environment:
+
+Environment
+===========
+
+The environment is a set of key/values constructed by the moment
+we walk the path (beginning from the root) until we reach a specific node.
+
+Given the node structure bellow::
+
+    devtools:
+        compiler: 'cc'
+        flags:
+            - '-O2'
+        debug: '-g'
+        fedora:
+            compiler: 'gcc'
+            flags:
+                - '-Wall'
+        osx:
+            compiler: 'clang'
+            flags:
+                - '-arch i386'
+                - '-arch x86_64'
+
+And the rules defined as:
 
-The key will become part of all lower-level (i.e. further indented) variant
-stanzas (see section variants_). However, key precedence is evaluated in
-top-down or ``last defined`` order. In other words, the last parsed key has
-precedence over earlier definitions.
+* Scalar values (Booleans, Numbers and Strings) are overwritten by walking from the root until the final node.
+* Lists are appended (to the tail) whenever we walk from the root to the final node.
+
+The environment created for the nodes ``fedora`` and ``osx`` are:
+
+- Node ``//root/devtools/fedora`` environment ``compiler: 'gcc'``, ``flags: ['-O2', '-Wall']``
+- None ``//root/devtools/osx`` environment ``compiler: 'clang'``, ``flags: ['-O2', '-arch i386', '-arch x86_64']``
 
 .. _variants:
 
 Variants
 ========
 
-A ``variants`` stanza is opened by a ``variants:`` statement. The contents
-of the stanza must be indented further left than the ``variants:``
-statement. Each variant stanza or block defines a single dimension of
-the output array. When a Multiplex Configuration file contains
-two variants stanzas, the output will be all possible combination's of
-both variant contents. Variants may be nested within other variants,
-effectively nesting arbitrarily complex arrays within the cells of
-outside arrays.  For example::
-
-    variants:
-        - one:
-            key1 = Hello
-        - two:
-            key2 = World
-        - three:
-    variants:
-        - four:
-            key3 = foo
-        - five:
-            key3 = bar
-        - six:
-            key1 = foo
-            key2 = bar
-
-While combining, the parser forms names for each outcome based on
-prepending each variant onto a list. In other words, the first variant
-name parsed will appear as the left most name component. These names can
-become quite long, and since they contain keys to distinguishing between
-results, a 'short-name' key is also used.
+To be written.
 
 Avocado comes equipped with a plugin to parse multiplex files. The appropriate
 subcommand is::
 
-    avocado multiplex /path/to/multiplex.mplx [-c]
+    avocado multiplex /path/to/multiplex.yaml [-c]
 
 Note that there's no need to put extensions to a multiplex file, although
 doing so helps with organization. The optional -c param is used to provide
@@ -93,172 +159,5 @@ combinations and names::
         dict 8:    six.two
         dict 9:    six.three
 
-Variant shortnames represent the ``<TESTNAME>`` value used when results are
-recorded (see section Job Names and Tags). For convenience
-variants whose name begins with a ``@`` do not prepend their name to
-``shortname``, only 'name'. This allows creating ``shortcuts`` for
-specifying multiple sets or changes to key/value pairs without changing
-the results directory name. For example, this is often convenient for
-providing a collection of related pre-configured tests based on a
-combination of others.
-
-.. _filters:
-
-Filters
-=======
-
-Filter statements allow modifying the resultant set of keys based on the
-name of the variant set (see section variants_). Filters can be used in 3 ways:
-Limiting the set to include only combination names matching a pattern.
-Limiting the set to exclude all combination names not matching a
-pattern. Modifying the set or contents of key/value pairs within a
-matching combination name.
-
-Names are matched by pairing a variant name component with the
-character(s) ``,`` meaning ``OR``, ``..`` meaning ``AND``, and ``.`` meaning
-``IMMEDIATELY-FOLLOWED-BY``. When used alone, they permit modifying the list
-of key/values previously defined. For example:
-
-::
-
-    Linux..OpenSuse:
-    initrd = initrd
-
-Modifies all variants containing ``Linux`` followed anywhere thereafter
-with ``OpenSuse``, such that the ``initrd`` key is created or overwritten
-with the value ``initrd``.
-
-When a filter is preceded by the keyword ``only`` or ``no``, it limits the
-selection of variant combination's This is used where a particular set
-of one or more variant combination's should be considered selectively or
-exclusively. When given an extremely large matrix of variants, the
-``only`` keyword is convenient to limit the result set to only those
-matching the filter. Whereas the ``no`` keyword could be used to remove
-particular conflicting key/value sets under other variant combination
-names. For example:
-
-::
-
-    only Linux..Fedora..64
-
-Would reduce an arbitrarily large matrix to only those variants whose
-names contain Linux, Fedora, and 64 in them.
-
-However, note that any of these filters may be used within named
-variants as well. In this application, they are only evaluated when that
-variant name is selected for inclusion (implicitly or explicitly) by a
-higher-order. For example:
-
-::
-
-    variants:
-        - one:
-            key1 = Hello
-    variants:
-        - two:
-            key2 = Complicated
-        - three: one two
-            key3 = World
-    variants:
-        - default:
-            only three
-            key2 =
-
-    only default
-
-Results in the following outcome (using -c):
-
-::
-
-    Dictionaries generated:
-        dict 1:    default.three.one
-            _name_map_file = {'docs.mplx': 'default.three.one'}
-            _short_name_map_file = {'docs.mplx': 'default.three.one'}
-            dep = ['default.one', 'default.two']
-            key1 = Hello
-            key2 =
-            key3 = World
-            name = default.three.one
-            shortname = default.three.one
-
-.. _value_substitutions:
-
-Value Substitutions
-===================
-
-Value substitution allows for selectively overriding precedence and
-defining part or all of a future key's value. Using a previously defined
-key, it's value may be substituted in or as a another key's value. The
-syntax is exactly the same as in the bash shell, where as a key's value
-is substituted in wherever that key's name appears following a ``$``
-character. When nesting a key within other non-key-name text, the name
-should also be surrounded by ``{``, and ``}`` characters.
-
-Replacement is context-sensitive, thereby if a key is redefined within
-the same, or, higher-order block, that value will be used for future
-substitutions. If a key is referenced for substitution, but hasn``t yet
-been defined, no action is taken. In other words, the $key or ${key}
-string will appear literally as or within the value. Nesting of
-references is not supported (i.e. key substitutions within other
-substitutions.
-
-For example, if ``one = 1``, ``two = 2``, and ``three = 3``; then,
-``order = ${one}${two}${three}`` results in ``order = 123``. This is
-particularly handy for rooting an arbitrary complex directory tree
-within a predefined top-level directory.
-
-An example of context-sensitivity,
-
-::
-
-    key1 = default value
-    key2 = default value
-
-    sub = "key1: ${key1}; key2: ${key2};"
-
-    variants:
-        - one:
-            key1 = Hello
-            sub = "key1: ${key1}; key2: ${key2};"
-        - two: one
-            key2 = World
-            sub = "key1: ${key1}; key2: ${key2};"
-        - three: one two
-            sub = "key1: ${key1}; key2: ${key2};"
-
-Results in the following (using -c)
-
-::
-
-    Dictionaries generated:
-        dict 1:    one
-            _name_map_file = {'docs.mplx': 'one'}
-            _short_name_map_file = {'docs.mplx': 'one'}
-            dep = []
-            key1 = Hello
-            key2 = default value
-            name = one
-            shortname = one
-            sub = key1: Hello; key2: default value;
-        dict 2:    two
-            _name_map_file = {'docs.mplx': 'two'}
-            _short_name_map_file = {'docs.mplx': 'two'}
-            dep = ['one']
-            key1 = default value
-            key2 = World
-            name = two
-            shortname = two
-            sub = key1: default value; key2: World;
-        dict 3:    three
-            _name_map_file = {'docs.mplx': 'three'}
-            _short_name_map_file = {'docs.mplx': 'three'}
-            dep = ['one', 'two']
-            key1 = default value
-            key2 = default value
-            name = three
-            shortname = three
-            sub = key1: default value; key2: default value;
-
-With Keys, Values, Variants, Filters and Value Substitutions, we have most of what you
-actually need to construct most multiplex files. The format also has some extra features,
-that you can find in :doc:`MultiplexConfigAdvanced` should you need them.
+With Nodes, Keys, Values & Filters, we have most of what you
+actually need to construct most multiplex files.

docs/source/index.rst

@@ -18,7 +18,6 @@ Contents:
    WritingTests
    ResultsSpecification
    MultiplexConfig
-   MultiplexConfigAdvanced
    Plugins
    OutputPlugins
    api/modules
@@ -29,4 +28,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-