diff --git a/source/index.rst b/source/index.rst
index af7bb20..aaa5dd7 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -41,6 +41,9 @@ inclusion of 3rd-party elements and complex dependency structures.
    getting_started
    advanced
    updating
+
+   reference
+
    faq
 
 .. toctree::
diff --git a/source/reference.rst b/source/reference.rst
new file mode 100644
index 0000000..38ac793
--- /dev/null
+++ b/source/reference.rst
@@ -0,0 +1,8 @@
+Reference
+=========
+
+.. toctree::
+   :maxdepth: 1
+
+   reference/recipes
+   reference/language
diff --git a/source/reference/recipes.rst b/source/reference/recipes.rst
new file mode 100644
index 0000000..aca8a28
--- /dev/null
+++ b/source/reference/recipes.rst
@@ -0,0 +1,228 @@
+.. _recipes:
+
+=========
+ Recipes
+=========
+
+..
+   TODO turn this into an overview page with four children:
+   recipes-basics, recipes-project recipes-distribution
+   recipes-template
+
+.. toctree::
+   :hidden:
+
+   recipes/project
+   recipes/distribution
+   recipes/template
+
+Kinds of recipes:
+
+:ref:`Project Recipes <recipes-project>`
+
+  Descriptions of :term:`projects <project>`
+
+:ref:`Distribution Recipes <recipes-distribution>`
+
+  Descriptions of :term:`distributions <distribution>` which are
+  groups of :term:`project` versions that can be built and used
+  together.
+
+:ref:`Template Recipes <recipes-template>`
+
+  Descriptions of common :term:`project` kinds including how to build
+  and install the respective kinds of :term:`projects <project>`
+  depending on the overall development mode.
+
+On the syntactic level, all descriptions are currently based on
+`YAML`_.
+
+Variables and the Substitution Sub-Language
+===========================================
+
+Objects such as :term:`projects <project>`, :term:`distributions
+<distribution>` are basically named entities with a dictionary of
+variable names and their values. In `JSON`_, this translates into
+
+.. parsed-literal::
+
+   …
+
+   variables:
+     :samp:`"{NAME₁}"`: :samp:`{VALUE₁}`
+     :samp:`"{NAME₂}"`: :samp:`{VALUE₂}`
+     …
+
+The value part of a variable definition is either a string or a list
+of values. A small substitution sub-language, syntactically similar to
+"parameter expansion" in UNIX shells, can be used to refer to values
+of other variables. To this end we distinguish ``${}`` and ``@{}``
+substitution, which act differently on strings and lists.
+
+Some examples of variable definitions
+
+.. code-block:: yaml
+
+   list.a:  [ "abc", "def" ]
+   list.b:  [ "123", "456" ]
+   list.c:  [ "@{list.a}", "@{list.b}", "uvw", "${text}" ]
+   text:    "xyz"
+
+   dashed:  "${list.c}-"
+   product: "(${list.a} * ${list.b})"
+
+The basic syntax is as follows:
+
+* Scalar substitution
+
+  :samp:`$\{{NAME}\}`
+
+    Expands to the value of the variable named :samp:`{NAME}`.
+
+    Lists stay lists. However, ultimately a list is flattened into a
+    string by concatenating all quoted items with a space used as
+    delimiter.
+
+  :samp:`$\{{NAME}|\}` or :samp:`$\{{NAME}|{DEFAULT}\}`
+
+    Expands to the value of the variable named :samp:`{NAME}` if there
+    is one and :samp:`{DEFAULT}` otherwise.
+
+  :samp:`$\{next-value|{DEFAULT}\}`
+
+    Expands to the value of the variable being defined in the parent
+    scope if there is such a value and :samp:`{DEFAULT}` otherwise. As
+    before, :samp:`{DEFAULT}` can be empty or omitted entirely.
+
+* List substitution
+
+  Concatenates the elements of a list into a single string if there is
+  surrounding text. Otherwise, i.e. if there is no surrounding text,
+  it evaluates to the first element of the list. Obviously, this only
+  applies to list variables.
+
+  :samp:`@\{{NAME}\}`
+
+    In string context, expands to the first item of list variable
+    :samp:`{NAME}`.
+
+    In list context, expands to the list of items of list variable
+    :samp:`{NAME}`, which allows to extend lists this:
+
+    .. code-block:: json
+
+       [ "@{list.a}", "@{list.b|[]}", "new item" ]
+
+
+  :samp:`{TEXT₁}@{{NAME}}{TEXT₂}`
+
+    Expands to the string concatenated from :samp:`{TEXT₁}`, elements
+    of list variable :samp:`{NAME}` and :samp:`{TEXT₂}`.
+
+  :samp:`@\{{NAME}|[]\}`
+
+    Expands to the value of the variable named :samp:`{NAME}` if there
+    is one and the empty list of values (as indicated by ``[]``)
+    otherwise.
+
+  ``@{next-value|[]}``
+
+    Expands to the value of the variable being defined in the parent
+    scope if there is such a value and the empty list (``[]``)
+    otherwise. As before, ``[]`` can be omitted.
+
+* Products
+
+  If the evaluation of a variable results in a list, this list is
+  "multiplied" with the rest of the value string.
+
+* Examples
+
+  Assuming the following variables are defined (repeated from above):
+
+  .. code-block:: yaml
+
+     list.a:  [ "abc", "def" ]
+     list.b:  [ "123", "456" ]
+     list.c:  [ "@{list.a}", "@{list.b}", "uvw", "${text}" ]
+     text:    "xyz"
+     dashed:  "${list.c}-"
+     product: "(${list.a} * ${list.b})"
+
+  , the following results would be produced::
+
+    "${list.a}"           => [ "abc", "def" ]
+    "@{list.a}"           => "abc"
+    "@{list.a} foo"       => "abcdef foo"
+
+    "@{list.a} @{list.b}" => "abcdef 123456"
+    "@{list.c|[]} "       => "abcdef123456uvwxyz"
+
+    "${dashed}"           => [ "abc-", "def-", "123-", "456-", "uvw-", "xyz-" ]
+    "@{dashed} "          => "abc-def-123-456-uvw-xyz-"
+
+    "${product}"          => [ "(abc * 123)", "(abc * 456)", "(def * 123)", "(def * 456)" ]
+    "@{product} "         => "(abc * 123)(abc * 456)(def * 123)(def * 456)"
+
+Like in UNIX shells, substitutions are performed recursively, that is
+:samp:`${{${NAME}}}` expands to the value of the variable named by the
+value of the variable :samp:`{NAME}`. The same is true for
+:samp:`{DEFAULT}`.
+
+Variable Scopes
+---------------
+
+TODO Different objects in the description language like projects or
+distributions have separate variable sections. However, all these
+sections are effectively considered when generating a build job and
+thereby resolving to the values of required variables. This resolution
+process is determined by the parent-child relation of the different
+objects. This relation is as follow (``->`` indicates that the left
+side is a parent of the right side)::
+
+  DISTRIBUTION -> PROJECT -> VERSION -> JOB[including template]
+
+TODO When a variable needs to be resolved the resolution process iterates
+from the most specific object (e.g. a ``JOB``) to the most general
+object until the first definition is found. This definition sets the
+variable value. In case this definition contains a ``next-value`` (see
+above), the iteration continues on the next level to resolve the
+``next-value`` part.
+
+Access and Credentials
+======================
+
+:ref:`Project Descriptions <recipes-project>` and :ref:`Distribution
+Descriptions <recipes-distribution>` can specify whether the described
+:term:`project` or :term:`distribution` is publicly accessible. For a
+publicly accessible :term:`project` or :term:`distribution`, the
+entire associated source code can be obtained without any
+authentication.
+
+Conversely, if project source code has to be obtained from a
+repository that requires authentication, the necessary authentication
+can be configured.
+
+For access and credentials specification, the following variables are
+important:
+
+``variables`` » ``access``
+
+    Specifies access restrictions of the :term:`project` or
+    :term:`distribution`. If present, has to have one of the values
+    ``private`` and ``public``. Omitting the variable is equivalent to
+    ``public``.
+
+``variables`` » ``scm.credentials``
+
+    The value of this variable names an entry in Jenkins' global
+    credentials store that should be associated to the repository of
+    this project in generated Jenkins jobs.
+
+The following rules apply:
+
+* :term:`Projects <project>` with ``scm.credentials`` entries must
+  specify ``private`` ``access``.
+
+* :term:`Distributions <distribution>` with one or more ``private``
+  projects must specify ``private`` ``access``.
diff --git a/source/reference/recipes/distribution.rst b/source/reference/recipes/distribution.rst
new file mode 100644
index 0000000..32886f1
--- /dev/null
+++ b/source/reference/recipes/distribution.rst
@@ -0,0 +1,93 @@
+.. _recipes-distribution:
+
+======================
+ Distribution Recipes
+======================
+
+TODO introduction see project-recipe
+
+A basic :term:`distribution` description, which in this case would be
+stored in a file named :file:`toolkit.distribution`, looks like this:
+
+.. code-block:: yaml
+
+   variables:
+     …
+
+   include:
+     …
+
+   versions:
+     - project₁@version₁
+     - project₂@version₂
+     …
+
+The following fields are most important:
+
+:samp:`{FILENAME}`
+
+  This is not an actual field but the name of the :term:`recipe file
+  <recipe>` with its extension removed (e.g. ``rsb`` for a
+  :term:`recipe file <recipe>` named :file:`rsb.distribution`).
+
+  TODO
+
+``variables``
+
+  TODO
+
+``include``
+
+  TODO
+
+``versions``
+
+  A list of :term:`project` names and versions with elements of the
+  form
+
+  .. parsed-literal::
+
+     :samp:`{NAME}@{VERSION}`
+     :samp:`name: "{NAME}" versions: - {VERSION₁} - {VERSION₂}`
+
+  which should be part the :term:`distribution`. Note that multiple
+  versions of a :term:`project` can be specified in one entry but
+  multiple entry for the same :term:`project` are not allowed.
+
+``versions`` » ``name``
+
+  TODO
+
+``versions`` » ``match``
+
+  TODO
+
+  Example:
+
+  .. code-block:: yaml
+
+     versions:
+     - pattern: "^(([^-]+)-stable)$"
+       variables:
+         name: "${match:1}"
+         numeric: "${match:2}"
+
+``versions`` » ``variables``
+
+  TODO
+
+``versions`` » ``include`` » ``distributions``
+
+  Like the global ``include`` » ``distributions`` field, but specific
+  to a versions. The value can refer to the value of the global
+  variable via ``${next-value}``.
+
+  TODO overwriting entries?
+
+``versions`` » ``include`` » ``projects``
+
+  Like the global ``include`` » ``projects`` field, but specific to a
+  versions. The value can refer to the value of the global variable
+  via ``${next-value}``.
+
+  TODO overwriting entries?
diff --git a/source/reference/recipes/project.rst b/source/reference/recipes/project.rst
new file mode 100644
index 0000000..846598b
--- /dev/null
+++ b/source/reference/recipes/project.rst
@@ -0,0 +1,143 @@
+.. _recipes-project:
+
+=================
+ Project Recipes
+=================
+
+Project :term:`recipes <recipe>` include some aspects of software
+projects:
+
+* Name of the :term:`project`
+
+* :term:`Nature` of the :term:`project` (e.g. `CMake`_, Python
+  setuptools, …)
+
+* Repository URL
+
+* Specific build instructions if different from default build
+  instructions for the :term:`project's <project>`
+  :term:`nature`. Moreover, customizations are possible.
+
+A basic :term:`project` :term:`recipe`, which in this case would be
+stored in a file named :file:`rsb-cpp.project`, looks like this:
+
+.. code-block:: yaml
+
+   templates:
+   - code-cor-lab
+   - cmake-cpp
+   - base
+
+   variables:
+     description: >-
+       C++ implementation of the robotics service bus (RSB)
+     keywords:
+     - middleware
+     - integration
+     - robotics
+
+     repository: https://code.cor-lab.org/git/rsb.git.cpp
+
+     redmine-project: rsb
+
+     cmake.options:
+     - BUILD_TESTS=OFF
+     - BUILD_EXAMPLES=OFF
+     - "@{next-value|[]}"
+
+The following fields are most important:
+
+:samp:`{FILENAME}`
+
+  This is not an actual field but the name of the :term:`recipe file
+  <recipe>` with its extension removed (e.g. ``rsb-cpp`` for a
+  :term:`recipe file <recipe>` named :file:`rsb-cpp.project`).
+
+  Must be unique w.r.t. to all other :term:`projects <project>` in the
+  repository. Should in general not contain any version information
+  (unless particular versions of a project genuinely constitute their
+  own :term:`projects <project>`).
+
+``templates``
+
+  TODO A list of :term:`template` names characterizing the technical
+  and organizational nature of the project. For most basic purposes,
+  it is sufficient to choose a suitable :term:`template` for the build
+  system used by the project and the ``base`` :term:`template` to
+  inherit specifications for the general nature of build jobs to
+  create.
+
+  TODO It is important to note that :term:`templates <template>` first
+  mentioned have higher precedence for defining variables then
+  :term:`templates <template>` further to the end of the
+  list. Therefore, the ``base`` :term:`template` should always be
+  listed last so that more specific :term:`templates <template>` can
+  override variables defined in the base :term:`template`.
+
+Repository Information
+======================
+
+``variables`` » ``scm``
+
+  Kind of the repository from which a copy of the :term:`project` can
+  be obtained.
+
+  Only needed if the repository kind cannot be guessed from the value
+  of the ``repository`` field.
+
+  Currently supported values: ``git``, ``svn``, ``mercurial``,
+  ``archive``.
+
+``variables`` » ``repository``
+
+  URL of the repository from which a copy of the :term:`project` can
+  be obtained.
+
+  When omitted, automatic analysis of the project will not be
+  performed and the generated Jenkins job will not obtain a copy of
+  the project as the first build step.
+
+Project Description
+===================
+
+``variables`` » ``natures``
+
+  A list of :term:`natures <nature>` of the :term:`project`, for
+  example `CMake`_ project, `Maven`_ project, etc.
+
+  The :term:`nature` of a :term:`project` can guide the analysis of
+  the associated repository.
+
+  This information is usually provided by :term:`templates <template>`
+  specified in the ``template`` field, but can be overriden, for
+  example in "freestyle" projects or other more complicated projects.
+
+``variables`` » ``description``
+
+  A description of the :term:`project` can be multiple lines or even
+  paragraphs.
+
+``variables`` » ``keywords``
+
+  A list of keywords characterizing the :term:`project`.
+
+Dependencies
+============
+
+.. seealso::
+
+   :ref:`concept-dependencies`
+     TODO
+
+There are two ways determining :
+
+Dependency information for a given project can be manually specified
+in the fields
+
+``variables`` » ``extra-requires``
+
+  TODO
+
+``variables`` » ``extra-provides``
+
+  TODO
diff --git a/source/reference/recipes/template.rst b/source/reference/recipes/template.rst
new file mode 100644
index 0000000..565b000
--- /dev/null
+++ b/source/reference/recipes/template.rst
@@ -0,0 +1,135 @@
+.. _recipes-template:
+
+===========
+ Templates
+===========
+
+Templates describe generic properties for certain recurring aspects of
+:term:`projects <project>`. These could be build system instructions
+or common settings for redmine instances.
+
+Templates are separated into distinct modes which describe completely
+disparate usage purposes and therefore end up in differently
+configured Jenkins build jobs. This separation is achieved through
+distinct directory structures. The different directories are described
+in the following:
+
+:file:`_common`
+
+  Contains templates that are shared by all distinct modes. This
+  directory cannot be used as a generator mode. In case a specific
+  mode uses a template from this directory, it is symlinked into that
+  mode's directory.
+
+:file:`toolkit`
+
+  Describes a mode that can be used to generate build jobs which are
+  able to bootstrap a complete software distribution from scratch by
+  installing it to a shared filesystem prefix.  Therefore, the Jenkins
+  jobs are orchestrated by a buildflow job which triggers the distinct
+  jobs per software project in the appropriate order. No polling of
+  SCM is performed in this mode and jobs have to be triggered manually
+  via the Jenkins interface.
+
+:file:`ci-deploy`
+
+  This mode is used to continuously update a software distribution
+  installed in a shared prefix whenever an SCM change to a software
+  component appeared. This mode does not handle the bootstrapping
+  phase correctly as it starts building software projects whenever a
+  change is detected or an upstream project's build finished.
+
+:file:`ci`
+
+  Continuous integration mode for continuously building and testing
+  software without installing it to a distinct filesystem prefix.
+  Artifact copying is used between build job workspaces to handle
+  dependency resolution.
+
+Template Syntax
+---------------
+
+A typical template description looks as follows
+
+.. code-block:: yaml
+
+   inherit:
+     - foo-template
+
+   variables:
+     natures:
+       - cmake
+
+   aspects:
+     - name:   cmake-cpp.cmake/unix
+       aspect: cmake/unix
+       conditions:
+         unix: .*
+       variables:
+         aspect.cmake.environment: ${cmake.environment|}
+         aspect.cmake.options:     ${cmake.options}
+         aspect.cmake.targets:     ${cmake.targets}
+
+     jobs:
+       - name: toolkit
+         tags:
+         - toolkit
+         - architecture-dependent
+         - gcc
+         - unix
+         - linux
+         variables:
+           build-job-name: ${project-name}-${version-name}-toolkit-${distribution-name}
+           cmake.environment:
+             - PKG_CONFIG_PATH="${toolkit.dir}/lib/pkgconfig:\${PKG_CONFIG_PATH}"
+             - "@{next-value|[]}"
+           cmake.options:
+             - CMAKE_INSTALL_PREFIX="${toolkit.dir}"
+
+             - CMAKE_BUILD_TYPE=RelWithDebInfo
+
+             - CMAKE_SKIP_BUILD_RPATH=FALSE
+             - CMAKE_BUILD_WITH_INSTALL_RPATH=FALSE
+             - CMAKE_INSTALL_RPATH="${toolkit.dir}/lib"
+
+             - "@{next-value|[]}"
+           cmake.targets:
+             - install
+
+The following fields are most important:
+
+:samp:`{FILENAME}`
+
+  This is not an actual field but the name of the :term:`recipe file
+  <recipe>` with its extension removed (e.g. ``cmake-cpp`` for a
+  :term:`recipe file <recipe>` named :file:`cmake-cpp.template`).
+
+  Name of the template describing its purpose.
+
+``variables``
+
+  Variables specific to this template.
+
+``variables`` » ``kind``
+
+  ``"project"``
+
+    "normal" project job
+
+  ``"matrix"``
+
+    matrix job
+
+  :samp:`[ "{ELEMENT-NAME}", "{PLUGIN-NAME@PLUGIN-VERSION}" ]`
+
+    arbitrary kind
+
+``aspects``
+
+  :term:`Aspects <aspect>` are specific configuration fragments to
+  include in the generated Jenkins jobs.
+
+``jobs``
+
+  The kind of Jenkins jobs to generate for projects that have this
+  template assigned.