Update userguide on `miscellaneous` and `extension`

This is a continuation of the update effort to de-emphasize `distutils`
and make the documentation more consistent.

The main targets of the changes are the files
`docs/userguide/miscellaneous` and `docs/userguide/extension`.

Changes:

- Extracted text about automatic resource extraction and the zip-safe flag
  from `userguide/miscellaneous` to `deprecated/resource_extraction` and
  `deprecated/zip_safe`.
  - These configuration parameters are commonly associated with
    ``eggs``/``easy_install``/``pkg_resources``, and therefore are
    obsolete. Leaving them around in the main parts of the documentation
    just confuses users.
  - The text in the new files were updated.
- Extracted text about additional metadata from
  `userguide/miscellaneous` into the existing `userguide/extension`
  document.
- Updated `userguide/extension` to better reflect the status of the
  setuptools project.
  The text was also changed to explain a little bit more what is the
  relationship between ``setuptools`` and ``distutils``.
- Removed `userguide/functionalities_rewrite`.
  This file was virtually empty and not bringing any extra value to the
  docs.

3 files changed, 130 insertions, 0 deletions

diff --git a/docs/deprecated/index.rst b/docs/deprecated/index.rst
index 8169b3b7..96bdb313 100644
--- a/docs/deprecated/index.rst
+++ b/docs/deprecated/index.rst
@@ -16,6 +16,8 @@ objectives.
     changed_keywords
     python_eggs
     easy_install
+    zip_safe
+    resource_extraction
     distutils/index
     distutils-legacy
     functionalities
diff --git a/docs/deprecated/resource_extraction.rst b/docs/deprecated/resource_extraction.rst
new file mode 100644
index 00000000..19190baf
--- /dev/null
+++ b/docs/deprecated/resource_extraction.rst
@@ -0,0 +1,54 @@
+.. _Automatic Resource Extraction:
+
+Automatic Resource Extraction
+=============================
+
+In a modern setup, Python packages are usually installed as directories,
+and all the files can be found on deterministic locations on the disk.
+This means that most of the tools expect package resources to be "real" files.
+
+There are a few occasions however that packages are loaded in a different way
+(e.g. from a zip file), which is incompatible with the assumptions mentioned above.
+Moreover, a package developer may also include non-extension native libraries or other files that
+C extensions may expect to be able to access.
+
+In these scenarios, the use of :mod:`importlib.resources` is recommended.
+
+Old implementations (prior to the advent of :mod:`importlib.resources`) and
+long-living projects, however, may still rely on the library ``pkg_resources``
+to access these files.
+
+If you have to support such systems, or want to provide backward compatibility
+for ``pkg_resources``, you may need to add an special configuration
+to ``setuptools`` when packaging a project.
+This can be done by listing as ``eager_resources`` (argument to ``setup()``
+in ``setup.py`` or field in ``setup.cfg``) all the files that need to be
+extracted together, whenever a C extension in the project is imported.
+
+This is especially important if your project includes shared libraries *other*
+than ``distutils``/``setuptools``-built C extensions, and those shared libraries use file
+extensions other than ``.dll``, ``.so``, or ``.dylib``, which are the
+extensions that setuptools 0.6a8 and higher automatically detects as shared
+libraries and adds to the ``native_libs.txt`` file for you.  Any shared
+libraries whose names do not end with one of those extensions should be listed
+as ``eager_resources``, because they need to be present in the filesystem when
+he C extensions that link to them are used.
+
+The ``pkg_resources`` runtime for compressed packages will automatically
+extract *all* C extensions and ``eager_resources`` at the same time, whenever
+*any* C extension or eager resource is requested via the ``resource_filename()``
+API.  (C extensions are imported using ``resource_filename()`` internally.)
+This ensures that C extensions will see all of the "real" files that they
+expect to see.
+
+Note also that you can list directory resource names in ``eager_resources`` as
+well, in which case the directory's contents (including subdirectories) will be
+extracted whenever any C extension or eager resource is requested.
+
+Please note that if you're not sure whether you need to use this argument, you
+don't!  It's really intended to support projects with lots of non-Python
+dependencies and as a last resort for crufty projects that can't otherwise
+handle being compressed.  If your package is pure Python, Python plus data
+files, or Python plus C, you really don't need this.  You've got to be using
+either C or an external program that needs "real" files in your project before
+there's any possibility of ``eager_resources`` being relevant to your project.
diff --git a/docs/deprecated/zip_safe.rst b/docs/deprecated/zip_safe.rst
new file mode 100644
index 00000000..1b299b3c
--- /dev/null
+++ b/docs/deprecated/zip_safe.rst
@@ -0,0 +1,74 @@
+Understanding the ``zip_safe`` flag
+===================================
+
+The ``zip_safe`` flag is a ``setuptools`` configuration mainly associated
+with the ``egg`` distribution format
+(which got replaced in the ecosystem by the newer ``wheel`` format) and the
+``easy_install`` command (deprecated in ``setuptools`` v58.3.0).
+
+It is very unlikely that the values of ``zip_safe`` will affect modern
+deployments that use :pypi:`pip` for installing packages.
+Moreover, new users of ``setuptools`` should not attempt to create egg files
+using the deprecated ``build_egg`` command.
+Therefore, this flag is considered **obsolete**.
+
+This document, however, describes what was the historical motivation behind
+this flag, and how it was used.
+
+Historical Motivation
+---------------------
+
+For some use cases (such as bundling as part of a larger application), Python
+packages may be run directly from a zip file.
+Not all packages, however, are capable of running in compressed form, because
+they may expect to be able to access either source code or data files as
+normal operating system files.
+
+In the past, ``setuptools`` would install an project distributed
+as a zipfile or a directory (via the ``easy_install`` command or
+``python setup.py install``),
+the default choice being determined by the project's ``zip_safe`` flag.
+
+How the ``zip_safe`` flag was used?
+-----------------------------------
+
+To set this flag, a developer would pass a boolean value for the ``zip_safe`` argument to the
+``setup()`` function, or omit it.  When omitted, the ``bdist_egg``
+command would analyze the project's contents to see if it could detect any
+conditions that preventing the project from working in a zipfile.
+
+This was extremely conservative: ``bdist_egg`` would consider the
+project unsafe if it contained any C extensions or datafiles whatsoever.  This
+does *not* mean that the project couldn't or wouldn't work as a zipfile!  It just
+means that the ``bdist_egg`` authors were not yet comfortable asserting that
+the project *would* work.  If the project did not contain any C or data files, and did not
+attempt to perform ``__file__`` or ``__path__`` introspection or source code manipulation, then
+there was an extremely solid chance the project will work when installed as a
+zipfile.  (And if the project used ``pkg_resources`` for all its data file
+access, then C extensions and other data files shouldn't be a problem at all.
+See the :ref:`Accessing Data Files at Runtime` section for more information.)
+
+The developer could manually set ``zip_safe`` to ``True`` to perform tests,
+or to override the default behaviour (after checking all the warnings and
+understanding the implications), this would allow ``setuptools`` to install the
+project as a zip file. Alternatively, by setting ``zip_safe`` to ``False``,
+developers could force ``setuptools`` to always install the project as a
+directory.
+
+Modern ways of loading packages from zip files
+----------------------------------------------
+
+Currently, popular Python package installers (such as :pypi:`pip`) and package
+indexes (such as PyPI_) consider that distribution packages are always
+installed as a directory.
+It is however still possible to load packages from zip files added to
+:obj:`sys.path`, thanks to the :mod:`zipimport` module 
+and the :mod:`importlib` machinery provided by Python standard library.
+
+When working with modules loaded from a zip file, it is important to keep in
+mind that values of ``__file__`` and ``__path__`` might not work as expected.
+Please check the documentation for :mod:`importlib.resources`, if file
+locations are important for your use case.
+
+
+.. _PyPI: https://pypi.org