Re: Enhancement request: make-markup-command cleanup and docs

[David Kastrup]

Valentin Villenave <address@hidden> writes:

> On Sun, Dec 20, 2009 at 11:01 AM, David Kastrup <address@hidden> wrote:
>> The current state of make-markup-command is less than satisfactory since
>> make-markup-command and make-builtin-markup-command have different
>> syntaxes and semantics, making the latter an "insider" command that
>> complicates the transition from advanced user to Lilypond contributor.
>
> Thanks, added as http://code.google.com/p/lilypond/issues/detail?id=941

It appears that Nicolas dived in and did all of the listed job.  As a
somewhat related cleanup, independent documentation has become simpler.
After checking for disappearance of the described features in the code
with grep, I came up with the following cleanup.  If there is need for a
more elaborate form (git commit message, reviewable patch on Rietveld)
or similar, please holler.  This was just easiest to do right now.

diff --git a/Documentation/contributor/programming-work.itexi 
b/Documentation/contributor/programming-work.itexi
index 936057d..f9e8c60 100644
--- a/Documentation/contributor/programming-work.itexi
+++ b/Documentation/contributor/programming-work.itexi
@@ -1250,37 +1250,26 @@ foo = 1
 @end example
 
 @noindent with @code{\paper}, @code{\midi} and @code{\header} being
-nested scope inside the .ly file-level scope.  @address@hidden = 1}} is
-translated in to a scheme variable definition.
+nested scope inside the @file{.ly} file-level scope.  @address@hidden = 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
address@hidden 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.

-- 
David Kastrup