update docs

docs/libraries/editions.md

@@ -189,36 +189,47 @@ so edition files that already exist on disk are not redownloaded.
 Below are listed the steps that are taken when resolving an import of library
 `Foo.Bar`:
 
-1. If and only if the project has `prefer-local-libraries` set to `true` and if
-   any directory on the library path contains `Foo/Bar`, that local instance is
-   chosen as the library that should be used, regardless of the version that is
-   there;
+1. If and only if the project has `prefer-local-libraries` set to `true`, 
+   the library path is searched for sub-directories containing Enso packages.
+   If any of such packages has a `package.yaml` that defines `namespace:Foo` 
+   and `name: Bar`, that local instance of the library is chosen. In this 
+   particular scenario the version check is skipped - whatever version is 
+   present in the local library path is used.
 2. Otherwise, the list of libraries defined directly in the `edition` section of
    `package.yaml` of the current project is checked, and if the library is
    defined there, it is selected.
 3. Otherwise, any parent editions are consulted; if they too do not contain the
    library that we are searching for, an error is reported.
 4. Once we know the library version to be used:
-   1. If the repository associated with the library is `local`, the library path
-      is searched for the first directory to contain `Foo/Bar` and this path is
-      loaded. If the library is not present on the library path, an error is
-      reported.
+   1. If the repository associated with the library is `local`, the 
+      local library path is searched for the first directory to contain the 
+      requested library and this path is loaded. If the library is not 
+      present on the library path, an error is reported.
    2. Otherwise, the edition must have defined an exact `<version>` of the
       library that is supposed to be used.
-   3. If the library is already downloaded in the local repository cache, that
-      is the directory `$ENSO_DATA_DIRECTORY/lib/Foo/Bar/<version>` exists, that
+   3. If the library is already downloaded in the local repository cache 
+      (the directory `$ENSO_DATA_DIRECTORY/lib/Foo/Bar/<version>` exists), that
       package is loaded.
    4. Otherwise, the library is missing and must be downloaded from its
       associated repository (and placed in the cache as above).
 
-By default, the library path is `<ENSO_HOME>/libraries/` but it can be
-overridden by setting the `ENSO_LIBRARY_PATH` environment variable. It may
-include a list of directories (separated by the system specific path separator);
-the first directory on the list has the highest precedence.
-
-In particular, if `prefer-local-libraries` is `false`, and the edition does not
-define a library at all, when trying to resolve such a library, it is reported
-as not found even if a local version of it exists. That is because
-auto-discovery of local libraries is only done with `prefer-local-libraries` set
-to `true`. In all other cases, the `local` repository overrides should be set
-explicitly.
+By default, the local library path consists of two directories:
+- `<ENSO_HOME>/libraries/`,
+- the parent directory of the currently opened project.
+
+This allows the user to access libraries that are placed next to the current 
+project (although ones located in the Enso home still take precedence). 
+Still, to access local libraries they either have to be defined in the 
+edition, or the `prefer-local-libraries` flag must be set to `true`.
+
+The local library search path can be overridden by setting the 
+`ENSO_LIBRARY_PATH` environment variable. It may include a list of 
+directories (separated by the system specific path separator); the first
+directory on the list has the highest precedence. If the environment 
+variable is defined, it overrides the default paths.
+
+If `prefer-local-libraries` is `false`, and the edition does not define a
+library at all, when trying to resolve such a library, it is reported as not
+found even if a local version of it exists. That is because auto-discovery of 
+local libraries is only done with `prefer-local-libraries` set to `true`. In all 
+other cases, the `local` repository overrides should be set explicitly.

docs/libraries/sharing.md

@@ -23,19 +23,12 @@ To prepare the project for sharing, make sure that it has a proper `namespace`
 field set in `package.yaml`. It should be set to something unique, like your
 username.
 
-> **NOTE**: The field `namespace` is a temporary workaround and in the near
-> future it will be deprecated and handled mostly automatically. For now however
-> you need to set it properly.
-
 To share an Enso library, all you need to do is to package the project into an
 archive (for example ZIP) and share it (through e-mail, cloud drive services
 etc.) with your peers. Now to be able to use the library that was shared with
 you, you need to extract it to the directory
-`~/enso/libraries/<namespace>/<Project_Name>` (where on Windows `~` should be
-interpreted as your user home directory). To make sure that the library is
-extracted correctly, make sure that under the path
-`~/enso/libraries/<namespace>/<Project_Name>/package.yaml` and that its
-`namespace` field has the same value as the name of the `<namespace>` directory.
+`~/enso/libraries/<Project_Name>` (where on Windows `~` should be
+interpreted as your user home directory).
 
 Now you need to set up your project properly to be able to use this unpublished
 library. The simplest way to do that is to set `prefer-local-libraries` in your

lib/scala/pkg/src/main/scala/org/enso/pkg/Config.scala

@@ -90,9 +90,7 @@ object Contact {
   * @param name the package display name
   * @param normalizedName the name that will be used as a prefix to module names
   *                       of the project
-  * @param namespace package namespace. This field is a temporary workaround
-  *                  and will be removed with further improvements to the
-  *                  libraries system. The default value is `local`.
+  * @param namespace package namespace.
   * @param version package version
   * @param license package license
   * @param authors name and contact information of the package author(s)