From 3025442087de8dd3f88736290887ced86e360c25 Mon Sep 17 00:00:00 2001 From: James Lowe Date: Sun, 31 Jul 2016 17:32:44 +0100 Subject: Doc: Extending - rewrite - LilyPond Variables Issue 4948 Last para of Extending/LP variables rewrite for clarity. --- Documentation/extending/scheme-tutorial.itely | 33 ++++++++++++++++++--------- 1 file changed, 22 insertions(+), 11 deletions(-) (limited to 'Documentation/extending/scheme-tutorial.itely') diff --git a/Documentation/extending/scheme-tutorial.itely b/Documentation/extending/scheme-tutorial.itely index fd0beaa9e1..5984c4f038 100644 --- a/Documentation/extending/scheme-tutorial.itely +++ b/Documentation/extending/scheme-tutorial.itely @@ -777,17 +777,28 @@ twentyFour = #(* 2 twelve) @end example @noindent -which would result in the number 24 being stored in the -LilyPond (and Scheme) variable @code{twentyFour}. - -The usual way to refer to LilyPond variables is to call them using a -backslash, i.e., @code{\twentyFour} (see @ref{LilyPond Scheme syntax}). -Since this creates a copy of the value for most of LilyPond's internal -types, in particular music expressions, music functions don't usually -create copies of material they change. For this reason, music -expressions given with @code{#} should usually not contain material that -is not either created from scratch or explicitly copied rather than -directly referenced. +which would result in the number @emph{24} being stored in the LilyPond +(and Scheme) variable @code{twentyFour}. + +Scheme allows modifying complex expressions in-place and LilyPond makes +use of this @q{in-place modification} when using music functions. But +when music expressions are stored in variables rather than entered +directly the usual expectation, when passing them to music functions, +would be that the original value is unmodified. So when referencing a +music variable with leading backslash (such as @code{\twentyFour}), +LilyPond creates a copy of that variable's music value for use in the +surrounding music expression rather than using the variable's value +directly. + +Therefore, Scheme music expressions written with the @code{#} syntax +should be used for material that is created @q{from scratch} (or that is +explicitly copied) rather than being used, instead, to directly +reference material. + +@seealso +Extending: +@ref{LilyPond Scheme syntax}. + @node Input variables and Scheme @subsection Input variables and Scheme -- cgit v1.2.3