docs: Updating documentation regarding element names and addressing.

This commit does the following:

  * Move the section about rules on element naming to the beginning
    of the document instead of the end.

    Element names are probably the first thing you need to know about
    elements, not the last.

  * Expand this element naming section to also speak about element
    addressing, and how to express element paths and how these
    can be used across the boundaries of multiple junctions.

    It helps to have a single place to discuss this and link to
    in the documentation, instead of repetitively explaining in
    multiple places that one must specify a filename relative
    to a project's element path.

  * Update documentation about dependencies to refer to the
    element naming and addressing documentation.

  * Update the documentation in the `link` and `junction`
    elements to link back to the element name documentation.

1 files changed, 74 insertions, 53 deletions

diff --git a/doc/source/format_declaring.rst b/doc/source/format_declaring.rst
index 7514d43e1..d8414c2bd 100644
--- a/doc/source/format_declaring.rst
+++ b/doc/source/format_declaring.rst
@@ -60,6 +60,60 @@ details here in order to have a more complete initial example.
 Let's break down the above and give a brief explanation of what these attributes mean.
 
 
+.. _format_element_names:
+
+Element names and paths
+~~~~~~~~~~~~~~~~~~~~~~~
+An *element name* is the filename of an element relative to the project's
+:ref:`element path <project_element_path>`.
+
+Element names are the identifiers used to refer to elements, they are used
+to specify an element's :ref:`dependencies <format_dependencies>`, to select
+elements to build on the :ref:`command line <commands>`, and they are arbitrarily
+used in various element specific configuration surfaces, for example the
+*target* configuration of the :mod:`link <elements.link>` element is also
+an *element name*.
+
+
+Addressing elements
+'''''''''''''''''''
+When addressing elements in a single project, it is sufficient to use
+the *element name* as a dependency or configuration parameter.
+
+When muliple projects are connected through :mod:`junction <elements.junction>`
+elements, there is a need to address elements which are not in the same
+project but in a junctioned *subproject*. In the case that you need to
+address elements across junction boundaries, one must use *element paths*.
+
+An *element path* is a path to the element indicating the junction
+elements leading up to the project, separated by ``:`` symbols, e.g.:
+``junction.bst:element.bst``.
+
+Elements can be address across multiple junction boundaries with multiple
+``:`` separators, e.g.: ``junction.bst:junction.bst:element.bst``.
+
+
+Element naming rules
+''''''''''''''''''''
+When naming the elements, use the following rules:
+
+* The name of the file must have ``.bst`` extension.
+
+* All characters in the name must be printable 7-bit ASCII characters.
+
+* Following characters are reserved and must not be part of the name:
+
+  - ``<`` (less than)
+  - ``>`` (greater than)
+  - ``:`` (colon)
+  - ``"`` (double quote)
+  - ``/`` (forward slash)
+  - ``\`` (backslash)
+  - ``|`` (vertical bar)
+  - ``?`` (question mark)
+  - ``*`` (asterisk)
+
+
 Kind
 ~~~~
 
@@ -92,8 +146,8 @@ Depends
    - element2.bst
 
 Relationships between elements are specified with the ``depends`` attribute. Elements
-may depend on other elements by specifying the :ref:`element path <project_element_path>`
-relative filename to the elements they depend on here.
+may depend on other elements by specifying the :ref:`element names <format_element_names>`
+they depend on here.
 
 See :ref:`format_dependencies` for more information on the dependency model.
 
@@ -228,7 +282,6 @@ Environment variables can be set to literal values here, these environment
 variables will be effective in the :mod:`Sandbox <buildstream.sandbox>` where
 build instructions are run for this element.
 
-
 Environment variables can also be declared and overridden in the :ref:`projectconf`
 
 
@@ -364,8 +417,7 @@ Attributes:
 
 * ``filename``
 
-  The :ref:`element path <project_element_path>` relative filename of the element to
-  depend on in the project.
+  The :ref:`element name <format_element_names>` to depend on.
 
 * ``type``
 
@@ -375,15 +427,15 @@ Attributes:
 
 * ``junction``
 
-  This attribute can be used to depend on elements in other projects.
+  This attribute can be used to specify the junction portion of the :ref:`element name <format_element_names>`
+  separately from the project local element name.
 
-  If a junction is specified, then it must be an :ref:`element path <project_element_path>`
-  relative filename of the junction element in the project.
+  This should be the *element name* of the :mod:`junction <elements.junction>` element
+  in the local project, possibly followed by other junctions in subprojects leading
+  to the project in which the element you want to depend on resides.
 
-  In the case that a *junction* is specified, the ``filename`` attribute indicates an element
-  in the *junctioned project*.
-
-  See :mod:`junction <elements.junction>`.
+  In the case that a *junction* is specified, the ``filename`` attribute indicates an
+  element in the *junctioned project*.
 
 * ``strict``
 
@@ -398,33 +450,26 @@ Attributes:
 
 Cross-junction dependencies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-As mentioned above, cross-junction dependencies can be specified using the
-``junction`` attribute. They can also be expressed as simple strings as a
-convenience shorthand. You can refer to cross-junction elements using the
-syntax ``{junction-name}:{element-name}``.
+As explained in the :ref:`element name <format_element_names>` section
+on element addressing, elements can be addressed across junction boundaries
+using *element paths* such as ``junction.bst:element.bst``. An element
+at any depth can be specified by specifying multiple junction elements.
 
-For example, the following is logically same as the example above:
+For example, one can specify a subproject element dependency with
+the following syntax:
 
 .. code:: yaml
 
    build-depends:
-   - baseproject.bst:foo.bst
+   - baseproject.bst:element.bst
 
-Similarly, you can also refer to cross-junction elements via the ``filename``
-attribute, like so:
+And one can specify an element residing in a sub-subproject as a
+dependency like so:
 
 .. code:: yaml
 
    depends:
-   - filename: baseproject.bst:foo.bst
-     type: build
-
-.. note::
-
-   BuildStream does not allow recursive lookups for junction elements. If a
-   filename contains more than one ``:`` (colon) character, an error will be
-   raised. See :ref:`nested junctions <core_junction_nested>` for more details
-   on nested junctions.
+   - baseproject.bst:middleproject.bst:element.bst
 
 
 .. _format_dependencies_types:
@@ -552,27 +597,3 @@ read-only variables are also dynamically declared by BuildStream:
   build, support for this is conditional on the element type
   and the build system used (any element using 'make' can
   implement this).
-
-
-Naming elements
----------------
-When naming the element files, use the following rules:
-
-* The name of the file must have ``.bst`` extension.
-
-* All characters in the name must be printable 7-bit ASCII characters.
-
-* Following characters are reserved and must not be part of the name:
-
-  - ``<`` (less than)
-  - ``>`` (greater than)
-  - ``:`` (colon)
-  - ``"`` (double quote)
-  - ``/`` (forward slash)
-  - ``\`` (backslash)
-  - ``|`` (vertical bar)
-  - ``?`` (question mark)
-  - ``*`` (asterisk)
-
-BuildStream will attempt to raise warnings when any of these rules are violated
-but that may not always be possible.