rework the documentation of scopes

doc/jbuild.rst

@@ -639,24 +639,6 @@ are part of the installed world, you need to use the public name. For instance:
 When resolving libraries, libraries that are part of the workspace are always
 prefered to ones that are part of the installed world.
 
-Scope of internal library names
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The scope of internal library names is not the whole workspace. It is restricted
-to the subtree starting from the closest parent containing a ``<package>.opam``
-file, or the whole workspace if no such directory exist. Moreover, a subtree
-containing ``<package>.opam`` doesn' t inherit the internal names available in
-its parent scope.
-
-The idea behing this rule is that public library names must be universally
-unique, but internal ones don't need to. In particular you might have private
-libraries that are only used for tests or building an executable.
-
-As a result, when you create a workspace including several projects there might
-be a name clash between internal library names.
-
-This scoping rule ensure that this won't be a problem.
-
 .. _alternative-deps:
 
 Alternative dependencies

doc/project-layout-specification.rst

@@ -71,15 +71,33 @@ Declaring a package this way will allow you to add elements such as
 libraries, executables, documentations, ... to your package by declaring
 them in ``jbuild`` files.
 
-Jbuilder will only register the existence of ``<package>`` in the
-subtree starting where the ``<package>.opam`` file lives, so you can
-only declare parts of the packages in this subtree. Typically your
+Such elements can only be declared in the scope defined by the
+corresponding ``<package>.opam`` file. Typically your
 ``<package>.opam`` files should be at the root of your project, since
 this is where ``opam pin ...`` will look for them.
 
 Note that ``<package>`` must be non empty, so in particular ``.opam``
 files are ignored.
 
+.. _scopes:
+
+Scopes
+------
+
+Any directory containing at least one ``<package>.opam`` file defines
+a scope. This scope is the sub-tree starting from this directory,
+excluding any other scopes rooted in sub-direcotries.
+
+Typically, any given project will define a single scope. Libraries and
+executables that are not meant to be installed will be visible inside
+this scope only.
+
+Because scopes are exclusive, if you whish to include the dependencies
+of the project you are currently working on into your workspace, you
+may copy them in a ``vendor`` directory, or any other name of your
+choice. Jbuilder will look for them there rather than in the installed
+world and there will be no overlap between the various scopes.
+
 Package version
 ---------------
 

doc/terminology.rst

@@ -21,6 +21,17 @@ Terminology
 -  **installed world**: anything outside of the workspace, that Jbuilder
    takes for granted and doesn't know how to build
 
+-  **installation**: this is the action of copying build artifacts or
+   other files from the ``<root>/_build`` directory to the installed
+   world
+
+-  **scope**: a scope determines where private items are
+   visible. Private items include libraries or binaries that will not
+   be installed. In Jbuilder, scopes are sub-trees rooted where at
+   least one ``<package>.opam`` file is present. Moreover, scopes are
+   exclusive. Typically every project defines a single scope. See
+   :ref:`scopes` for more details
+
 -  **build context**: a build context is a subdirectory of the
    ``<root>/_build`` directory. It contains all the build artifacts of
    the workspace built against a specific configuration. Without