Webpage update
diff --git a/_sources/salt.txt b/_sources/salt.txt
new file mode 100644
index 0000000..2743c35
--- /dev/null
+++ b/_sources/salt.txt
@@ -0,0 +1,215 @@
+=======================
+Using reclass with Salt
+=======================
+
+.. warning::
+
+ You need Salt 0.17 to use `reclass`, as older versions do not include the
+ `reclass` adapter. You could use the ``cmd_yaml`` adapters, but at least for
+ ``ext_pillar``, they are currently not useable, as they `do not export the
+ minion ID to the command they run`_.
+
+.. _do not export the minion ID to the command they run:
+ https://github.com/saltstack/salt/issues/2276
+
+Quick start
+-----------
+The following steps should get you up and running quickly with |reclass| and
+`Salt`_. You will need to decide for yourself where to put your |reclass|
+inventory. This can be your first ``base`` ``file_root`` (the default), or it
+could be ``/etc/reclass``, or ``/srv/salt``. The following shall assume the
+latter.
+
+Or you can also just look into ``./examples/salt`` of your |reclass|
+checkout (``/usr/share/doc/examples/salt`` on Debian-systems), where the
+following steps have already been prepared.
+
+/…/reclass refers to the location of your |reclass| checkout.
+
+.. todo::
+
+ With |reclass| now in Debian, as well as installable from source, the
+ following should be checked for path consistency…
+
+#. Complete the installation steps described in the :doc:`installation section
+ <install>`.
+
+ Alternatively, you can also tell Salt via the master config file where to
+ look for |reclass|, but then you won't be able to interact with
+ |reclass| through the command line.
+
+#. Copy the two directories ``nodes`` and ``classes`` from the example
+ subdirectory in the |reclass| checkout to e.g. ``/srv/salt``.
+
+ It's handy to symlink |reclass|' Salt adapter itself to that directory::
+
+ $ ln -s /usr/share/reclass/reclass-salt /srv/salt/states/reclass
+
+ As you can now just inspect the data right there from the command line::
+
+ $ ./reclass --top
+
+ If you don't want to do this, you can also let |reclass| know where to
+ look for the inventory with the following contents in
+ ``$HOME/reclass-config.yml``::
+
+ storage_type: yaml_fs
+ base_inventory_uri: /srv/reclass
+
+ Or you can reuse the first entry of ``file_roots`` under ``base`` in the Salt
+ master config.
+
+ Note that ``yaml_fs`` is currently the only supported ``storage_type``, and
+ it's the default if you don't set it.
+
+#. Check out your inventory by invoking
+
+ ::
+
+ $ reclass-salt --top
+
+ which should return all the information about all defined nodes, which is
+ only ``localhost`` in the example. This is essentially the same information
+ that you would keep in your ``top.sls`` file.
+
+ If you symlinked the script to your inventory base directory, use
+
+ ::
+
+ $ ./reclass --top
+
+#. See the pillar information for ``localhost``::
+
+ $ reclass-salt --pillar localhost
+
+#. Now add |reclass| to ``/etc/salt/master``, like so::
+
+ reclass: &reclass
+ inventory_base_uri: /srv/salt
+ reclass_source_path: ~/code/reclass
+
+ master_tops:
+ […]
+ reclass: *reclass
+
+ ext_pillar:
+ - reclass: *reclass
+
+ .. warning::
+
+ When using ``ext_pillar`` and/or ``master_tops``, you should make sure
+ that your ``file_roots`` paths do not contain a ``top.sls`` file. Even
+ though they ought to be able to coexist, there are a few sharp edges
+ around at the moment, so beware!
+
+ If you did not install |reclass| (but you are running it from source),
+ you can either specify the source path like above, or you can add it to
+ ``PYTHONPATH`` before invoking the Salt master, to ensure that Python can
+ find it::
+
+ PYTHONPATH=/…/reclass /etc/init.d/salt-master restart
+
+#. Provided that you have set up ``localhost`` as a Salt minion, the following
+ commands should now return the same data as above, but processed through
+ salt::
+
+ $ salt localhost pillar.items # shows just the parameters
+ $ salt localhost state.show_top # shows only the states (applications)
+
+ Alternatively, if you don't have the Salt minion running yet::
+
+ $ salt-call pillar.items # shows just the parameters
+ $ salt-call state.show_top # shows only the states (applications)
+
+#. You can also invoke |reclass| directly, which gives a slightly different
+ view onto the same data, i.e. before it has been adapted for Salt::
+
+ $ reclass --inventory
+ $ reclass --nodeinfo localhost
+
+Configuration file and master configuration
+-------------------------------------------
+Even though the Salt adapter of |reclass| looks for and reads the
+:doc:`configuration file <configfile>`, a better means to pass information to
+the adapter is via Salt's master configuration file, as shown above. Not all
+configuration options can be passed this way (e.g. ``output`` is hardcoded to
+YAML, which Salt uses), but it *is* possible to specify :doc:`class mappings
+<operations>` next to all the storage-specific options.
+
+.. warning::
+
+ The Salt CLI adapter does *not* read Salt's master configuration, so if you
+ are calling ``reclass-salt`` from the command-line (the CLI exists for
+ debugging purposes, mainly), be aware that it will be run in a different
+ environment than when Salt queries reclass directly.
+
+Integration with Salt
+---------------------
+|reclass| hooks into Salt at two different points: ``master_tops`` and
+``ext_pillar``. For both, Salt provides plugins. These plugins need to know
+where to find |reclass|, so if |reclass| is not properly installed (but
+you are running it from source), make sure to export ``PYTHONPATH``
+accordingly before you start your Salt master, or specify the path in the
+master configuration file, as show above.
+
+Salt has no concept of "nodes", "applications", "parameters", and "classes".
+Therefore it is necessary to explain how those correspond to Salt. Crudely,
+the following mapping exists:
+
+================= ================
+|reclass| concept Salt terminology
+================= ================
+nodes hosts
+classes (none) [#nodegroups]_
+applications states
+parameters pillar
+environment environment
+================= ================
+
+.. [#nodegroups] See `Salt issue #5787`_ for steps into the direction of letting
+ |reclass| provide nodegroup information.
+
+.. _Salt issue #5787: https://github.com/saltstack/salt/issues/5787
+
+Whatever applications you define for a node will become states applicable to
+a host. If those applications are added via ancestor classes, then that's
+fine, but currently, Salt does not do anything with the classes ancestry.
+
+Similarly, all parameters that are collected and merged eventually end up in
+the pillar data of a specific node.
+
+The pillar data of a node include all the information about classes and
+applications, so you could theoretically use them to target your Salt calls at
+groups of nodes defined in the |reclass| inventory, e.g.
+
+::
+
+ salt -I __reclass__:classes:salt_minion test.ping
+
+Unfortunately, this does not work yet, please stay tuned, and let me know
+if you figure out a way. `Salt issue #5787`_ is also of relevance.
+
+Optionally, data from pillars that run before the |reclass| ``ext_pillar``
+(i.e. Salt's builtin ``pillar_roots``, as well as other ``ext_pillar`` modules
+listed before the ``reclass_adapter``) can be made available to |reclass|.
+Please use this with caution as referencing data from Salt in the inventory
+will make it harder or impossible to run |reclass| in other environments. This
+feature is therefore turned off by default and must be explicitly enabled in
+the Salt master configuration file, like this::
+
+ ext_pillar:
+ - reclass:
+ […]
+ propagate_pillar_data_to_reclass: True
+
+Unfortunately, to use this, currently you cannot use YAML references (i.e.
+``*reclass``) as shown above, as the ``master_tops`` subsystem does not accept
+this configuration parameter, and there seems to be no way to extend an alias.
+Specifically, the following is not possible — let me know if it is!::
+
+ ext_pillar:
+ - reclass: *reclass # WARNING: this does not work!
+ propagate_pillar_data_to_reclass: True
+
+.. include:: substs.inc
+.. include:: extrefs.inc