Improve documentation on how to use aliases with source plugins

doc/source/format_declaring.rst

@@ -260,10 +260,40 @@ in order to build itself, in this case the sources might be listed as:
      ref: 9d4b1147f8cf244b0002ba74bfb0b8dfb3...
 
 Like Elements, Source types are plugins which are indicated by the ``kind`` attribute.
-Asides from the common ``kind`` and ``directory`` attributes which may be applied to all
-Sources, refer to the Source specific documentation for meaningful attributes for the
-particular Source.
+The ``kind``, ``directory`` and ``provenance`` attributes may be applied to all :ref:`Sources <core_source_builtins>`.
 
+Another common attribute that a number of source plugins share is the ``url`` attribute.
+These source plugins deal with downloading files from a url.
+The ``url`` attribute can be a bare-url such as:
+
+.. code:: yaml
+
+   sources:
+
+   # Specify the source which should be built
+   - kind: git
+     url: https://my-upstream-forge.com/bananas/modulename.git
+     track: master
+     ref: d0b38561afb8122a3fc6bafc5a733ec502fcaed6
+
+Alternatively the ``url`` attribute can make use of
+:ref:`Source aliases declared in the project.conf <project_source_aliases>`
+to abstract the download location, to enable the use of mirrors.
+This is done by replacing the start of the url (e.g. ``https://my-upstream-forge.com/bananas/``)
+with the name of the alias followed by a colon (e.g ``upstream:``), as complete example:
+
+.. code:: yaml
+
+   sources:
+
+   # Specify the source which should be built
+   - kind: git
+     url: upstream:bananas/modulename.git
+     track: master
+     ref: d0b38561afb8122a3fc6bafc5a733ec502fcaed6
+
+For ``url`` support and all other attributes refer to the :ref:`Source specific documentation <plugins_sources>` for meaningful attributes for the
+particular Source plugin.
 
 Variables
 ~~~~~~~~~

doc/source/format_project.rst

@@ -204,9 +204,14 @@ URLs which are to be used in the individual ``.bst`` files.
      foo: git://git.foo.org/
      bar: http://bar.com/downloads/
 
+If you want to use this project's alias definitions in source plugin ``url``\s,
+see :ref:`Declaring Sources for elements <format_sources>`.
+
 If you want this project's alias definitions to also be used for subprojects,
 see :ref:`Mapping source aliases of subprojects <project_junctions_source_aliases>`.
 
+If you want to map this project's alias definitions to mirrors,
+see :ref:`project_essentials_mirrors`.
 
 Sandbox options
 ~~~~~~~~~~~~~~~

doc/source/tutorial/running-commands.rst

@@ -105,6 +105,11 @@ This tarball is a sysroot which provides the C runtime libraries
 and some programs - this is what will be providing the programs we're
 going to run in this example.
 
+.. tip::
+   Note how we use the source alias ``alpine`` as part of the url
+   instead of the full url with the tar plugin.
+   For further information see see :ref:`Declaring Sources for elements <format_sources>`
+
 
 ``elements/base.bst``
 ~~~~~~~~~~~~~~~~~~~~~
@@ -170,7 +175,7 @@ The :mod:`manual <elements.manual>` element however is the most basic
 and does not provide any default commands, so we have instructed it
 to use ``make`` to build and install our program.
 
-     
+
 Using the project
 -----------------