From 72fd7c5828fdd41d8f693802909dc5a5a9665765 Mon Sep 17 00:00:00 2001 From: David Kastrup Date: Sat, 26 Dec 2009 11:52:53 +0000 Subject: [PATCH] Docs: CG: amend description of modules --- .../contributor/programming-work.itexi | 37 +++++++------------ 1 file changed, 13 insertions(+), 24 deletions(-) diff --git a/Documentation/contributor/programming-work.itexi b/Documentation/contributor/programming-work.itexi index 8f3d6a5aa1..e62abc3f57 100644 --- 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. -- 2.39.5