doc: intro-dylan/modules-libraries.rst: clarifications

Note in particular the removal of the verbiage about there being a dylan-user
library, which there does not appear to be, and removal of the pretense that
one might write simple programs purely in the dylan-user module. This is never
done in practice and seems unlikely to be very useful without access to any I/O.

documentation/source/intro-dylan/modules-libraries.rst

@@ -3,9 +3,10 @@ Modules & Libraries
 *******************
 
 Modules and libraries provide the structure of a Dylan program. Modules
-represent namespaces and control access to objects and functions.
-Libraries contain modules, and act as units of compilation in a Dylan
-program.
+represent namespaces and control access to objects such as classes, functions,
+variables, and constants.  Libraries are the unit of compilation in a Dylan
+program. A library contains any number of modules, which may or may not be
+exported for other libraries to use.
 
 Simple Modules
 ==============
@@ -26,32 +27,32 @@ chapters might look like this:
       use dylan;
       export
         <vehicle>,
-          serial-number,
-          owner, owner-setter,
-          tax,
+        serial-number,
+        owner,
+        owner-setter,
+        tax,
         <car>,
         <truck>,
-          capacity;
+        capacity;
     end module;
 
 Like all normal modules, this one uses the ``dylan`` module, which
 contains all of the standard built-in functions and classes. In turn,
 the ``vehicles`` module exports all three of the vehicle classes, the
-generic function ``tax``, several getter functions and a single
-setter function.
+generic function ``tax``, several getter functions, and a single
+:drm:`setter <setters>` function.
 
-To control access to a slot, export some combination of its getter and
-setter functions. To make a slot public, export both. To make it
-read-only, export just the getter function. To make it private, export
-neither. In the above example, the slot ``serial-number`` is read-only,
+To make a :drm:`slot <slots>` public export its getter and setter functions. To
+make the slot read-only, export just the getter function. To make it private,
+export neither. In the above example, the slot ``serial-number`` is read-only,
 while the slot ``owner`` is read/write.
 
 Note that when a module adds a method to an imported generic function,
 the change affects all modules using that function. :drm:`define method`
 adds the new method to the existing generic function object, which may
 be referenced by any module importing its binding. The module that
 originally defined the generic function may prevent this behavior by
-"sealing" it over specific argument types.
+:drm:`sealing` it over specific argument types.
 
 Import Options
 ==============
@@ -60,40 +61,35 @@ Dylan allows very precise control over how bindings are imported from
 other modules. For example, individual bindings may be imported by
 name. They may be renamed, either one at a time, or by adding a prefix
 to all of a module's names at once. Some or all of them may be
-re-exported immediately. See the DRM for specific examples.
+re-exported immediately. See the DRM for :drm:`specific examples <define module>`.
 
-Dylan's import system has a number of advantages. Name conflicts
+Dylan's module system has a number of advantages. Name conflicts
 occur rarely. Programmers don't need to define or maintain function
 prototypes. There's no need for header files. Modules may
 also provide different interfaces to the same objects -- one module
 exports a complete interface, which another module imports, redefines
-and re-exports.
+and re-exports. For example, it is common to use one or more unexported modules
+for implementation and export a separate public API module.
 
 Libraries
 =========
 
 Libraries contain modules. For example, the ``dylan``
 library contains the ``dylan`` module
-described earlier, the ``extensions`` module, and
-possibly several other implementation-dependent modules. Note that
+described earlier, the ``dylan-extensions`` module, and
+several other implementation-dependent modules. Note that
 a library and a module may share the same name. Modules with the
 same name may also appear in more than one library.
 
-By default, a Dylan environment provides a library called
-``dylan-user`` for the convenience of the programmer.
-This is typically used for short, single library programs which
-depend only on modules found in the Dylan library.
-
-Additionally, every library contains an implicit module, also
-known as ``dylan-user``, which imports all of the
-modules found in the ``dylan`` library. This may be
-used for single module programs. Many Dylan environments, however,
-use it to bootstrap new library definitions. The vehicle library,
-for example, might be defined as follows in a ``dylan-user``
-module:
+Every library contains an implicit module called ``dylan-user`` which imports
+all the names from the ``dylan`` module. This module is only used to define
+your library and module definitions. The ``vehicle`` library, for example, might be
+defined as follows in the ``dylan-user`` module:
 
 .. code-block:: dylan
 
+    Module: dylan-user
+
     define library vehicles
       use dylan;            // This is the library!
       export                // These are modules.
@@ -107,35 +103,39 @@ This library could in turn be imported by another library:
 
 .. code-block:: dylan
 
+    Module: dylan-user
+
     define library vehicle-application
       use dylan;
       use my-gui-classes;
       use vehicles;
     end;
 
-Libraries import other libraries and export modules, whereas
-modules import other modules and export variables. In general, a
-module may import any module found in its own library or exported
+Libraries use other libraries and export modules, whereas
+modules use other modules and export bindings. In general, a
+module may use any module found in its own library or exported
 from a library imported by its own library. The following module, for
 example, could belong to the ``vehicle-application`` library.
 
 .. code-block:: dylan
 
+    Module: dylan-user
+
     define module sample-module
-      // module name         source library
-      use dylan;          // dylan
-      use extensions;     // dylan
-      use menus;          // my-gui-classes
-      use vehicles;       // vehicles
-      use inspection;     // vehicles
+      // module name        source library
+      use dylan;            // dylan
+      use dylan-extensions; // dylan
+      use menus;            // my-gui-classes
+      use vehicles;         // vehicles
+      use inspection;       // vehicles
     end module;
 
 Sealing
 =======
 
 Classes and generic functions may be :drm:`sealed <sealing>`, preventing code
 in other libraries from subclassing objects or adding methods to generic
-functions. This allows the compiler optimize more effectively. Both classes and
+functions. This allows the compiler to optimize more effectively. Both classes and
 generic functions are sealed by default.
 
 To allow code in other libraries to subclass a given class,