projectconf.rst: Change where literal include points tomake-source-dir-resemble-ToC

1 files changed, 23 insertions, 27 deletions

diff --git a/doc/source/index/authoring/projectconf.rst b/doc/source/index/authoring/projectconf.rst
index 9fe28cea2..8ecd30b06 100644
--- a/doc/source/index/authoring/projectconf.rst
+++ b/doc/source/index/authoring/projectconf.rst
@@ -24,6 +24,12 @@ Essentials
 
 Project Name
 ~~~~~~~~~~~~
+The project name is a unique symbol for your project and will
+be used to distinguish your project from others in user preferences,
+namspaceing of your project's artifacts in shared artifact caches,
+and in any case where BuildStream needs to distinguish between multiple
+projects.
+
 The first thing to setup in your ``project.conf`` should be the name
 of your project.
 
@@ -31,8 +37,10 @@ of your project.
 
    name: my-project-name
 
-The project name will be used in user configuration and anywhere
-that a project needs to be specified.
+.. note::
+
+   The project name may contain alphanumeric characters, dashes and
+   underscores, and may not start with a leading digit.
 
 
 .. _project_format_version:
@@ -55,7 +63,7 @@ to support a new feature.
 
 .. note::
 
-   :mod:`Element <buildstream.element>` and :mod:`Source <buildstream.source>`
+   External :mod:`Element <buildstream.element>` and :mod:`Source <buildstream.source>`
    plugins also implement their own YAML configuration fragments and as
    such are revisioned separately from the core format. See :ref:`project_plugins`
    for details on specifying a minimum version of a specific plugin.
@@ -193,34 +201,11 @@ External Plugins
 ----------------
 If your project makes use of any custom :mod:`Element <buildstream.element>` or
 :mod:`Source <buildstream.source>` plugins, then the project must inform BuildStream
-of the plugins it means to make use of and the origin from which it can be loaded.
+of the plugins it means to make use of and the origin from which they can be loaded.
 
 Note that plugins with the same name from different origins are not permitted.
 
 
-Core plugins
-~~~~~~~~~~~~
-Plugins provided by the BuildStream core need not be explicitly specified
-here, but you may use this section to specify a minimal format version
-to ensure that they provide the features which your project requires.
-
-.. code:: yaml
-
-   plugins:
-   - origin: core
-
-     # We require a new feature of the `git` source plugin, and
-     # a new feature introduced in version 2 of the `patch` plugin.
-     sources:
-       git: 1
-       patch: 2
-
-     # ... And a new feature of the `script` element, added
-     # in version 2 of it's own format version.
-     elements:
-       script: 2
-
-
 Local Plugins
 ~~~~~~~~~~~~~
 Local plugins are expected to be found in a subdirectory of the actual
@@ -296,6 +281,11 @@ Users can configure those options when invoking BuildStream with the
 
     $ bst --option debug True ...
 
+.. note::
+
+   The name of the option may contain alphanumeric characters
+   underscores, and may not start with a leading digit.
+
 
 Common Properties
 ~~~~~~~~~~~~~~~~~
@@ -319,6 +309,12 @@ All option types accept the following common attributes
   variable declared in ``project.conf``, and will be overridden in
   the regular :ref:`composition order <format_composition>`.
 
+  .. note::
+
+     The name of the variable to export may contain alphanumeric
+     characters, dashes, underscores, and may not start with a leading
+     digit.
+
 
 Boolean
 ~~~~~~~