doc: Update information on how plugin configuration is composed

It previously neglected to describe how sources were composed, and we've
changed how sources are composed, recently.

In addition, it was slightly confusing to have the project conf be the
title of two different stages of composition.

1 files changed, 34 insertions, 19 deletions

diff --git a/doc/source/formatintro.rst b/doc/source/formatintro.rst
index 6d1f234d5..427a29597 100644
--- a/doc/source/formatintro.rst
+++ b/doc/source/formatintro.rst
@@ -58,13 +58,19 @@ a project relative path to the element one depends on must be provided.
 
 Composition
 -----------
-Below are the various sources of configuration which go into an element in the order
-in which they are applied. Configurations which are applied later have a higher priority
-and override configurations which precede them.
+Below are the various sources of configuration which go into an element or source in the
+order in which they are applied. Configurations which are applied later have a higher
+priority and override configurations which precede them.
 
 
-1. Builtin Defaults
-~~~~~~~~~~~~~~~~~~~
+0. Hard-coded Defaults
+~~~~~~~~~~~~~~~~~~~~~~
+Where a config field is optional, a hard-coded default will
+be present.
+
+
+1. Builtin Default Project Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The :ref:`projectconf` provides a set of default values for *variables*
 and the *environment* which are all documented with your copy of BuildStream. 
 
@@ -76,27 +82,36 @@ anything in the *variables* or *environment* sections in your ``project.conf`` t
 will override the builtin defaults.
 
 
-3. Element Defaults
-~~~~~~~~~~~~~~~~~~~
-Elements are all implemented as plugins. Each plugin installs a ``.yaml`` file along side
-their plugin to define the default *variables*, *environment* and *config*. The *config*
-is element specific and as such this is the first place where defaults can be set on the
-*config* section.
+3. Plugin Defaults
+~~~~~~~~~~~~~~~~~~
+Elements and Sources are all implemented as plugins.
 
-The *variables* and *environment* specified in the declaring plugin's defaults here override
-the project configuration defaults for the given element ``kind``.
+Each Element plugin installs a ``.yaml`` file along side their plugin to
+define the default *variables*, *environment* and *config*.  The *config*
+is element specific and as such this is the first place where defaults
+can be set on the *config* section.
 
+The *variables* and *environment* specified in the declaring plugin's
+defaults here override the project configuration defaults for the given
+element ``kind``.
 
-4. Project Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~
+Source plugins do not have a ``.yaml`` file, and do not have *variables* or
+*environment*.
+
+
+4. Project Configuration Overrides
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The ``project.conf`` now gives you another opportunity to override *variables*, *environment*
-and *config* sections on a per element basis.
+and *config* sections on a per plugin basis.
+
+Configurations specified in the *elements* or *sources* sections of the ``project.conf``
+will override the given plugin's default.
 
-Configurations specified in the *elements* section of the ``project.conf`` will override
-the given element's default.
+See also :ref:`Source Overrides<project_source_overrides>` and
+:ref:`Element Overrides<project_element_overrides>`
 
 
-5. Element Declarations
+5. Plugin Declarations
 ~~~~~~~~~~~~~~~~~~~~~~~
 Finally, after having resolved any :ref:`conditionals <format_directives_conditional>`
 in the parsing phase of loading element declarations; the configurations specified in a