Docs: CG: amend description of modules

diff --git a/Documentation/contributor/programming-work.itexi b/Documentation/contributor/programming-work.itexi
index 8f3d6a5aa132cfeb6edbfb533704c334ed3450e1..e62abc3f5712a2084f6d4e14dc1667d190967171 100644 (file)
--- a/Documentation/contributor/programming-work.itexi
+++ b/Documentation/contributor/programming-work.itexi
@@ -1251,37 +1251,26 @@ foo = 1
 @end example
 
 @noindent with @code{\paper}, @code{\midi} and @code{\header} being
-nested scope inside the .ly file-level scope.  @w{@code{foo = 1}} is
-translated in to a scheme variable definition.
+nested scope inside the @file{.ly} file-level scope.  @w{@code{foo = 1}}
+is translated in to a scheme variable definition.
 
 This implemented using modules, with each scope being an anonymous
 module that imports its enclosing scope's module.
 
-The reason to put some functions (@qq{builtin}) outside the .ly level,
-is that in case of
+Lilypond's core, loaded from @file{.scm} files, is usually placed in the
+@code{lily} module, outside the @file{.ly} level.  In the case of
 
 @example
 lilypond a.ly b.ly
 @end example
 
 @noindent
-we want to reuse the built-in definitions, without changes
-effected in a.ly leaking into the processing of b.ly.
-
-Maintaining this scoping when one .ly file can be included in another
-.ly file can be challenging.  A @code{define-public-toplevel} macro
-has been created in order to handle a difficulty caused by the modules
-being not the same when a .ly file is included into another.
-This provided a way to define all markup commands in the same module.
-At this time, we have found no easier way to define a function in a given
-module (not the current one) than to define this macro.
-
-With this architecture, the guile module system is not bypassed:
-module-define!, module-export!  and module-ref are all guile module
-primitives.
-
-A second reason for using this current architecture is to avoid memory
-leaks that could occur when running multiple files if toplevel
-functions were registered permanently.
-
-
+we want to reuse the built-in definitions, without changes effected in
+user-level @file{a.ly} leaking into the processing of @file{b.ly}.
+
+The user-accessible definition commands have to take care to avoid
+memory leaks that could occur when running multiple files.  All
+information belonging to user-defined commands and markups is stored in
+a manner that allows it to be garbage-collected when the module is
+dispersed, either by being stored module-locally, or in weak hash
+tables.