Allow immediate Scheme expressions with splicing and multiple values

Documentation/extending/scheme-tutorial.itely

 @c -*- coding: utf-8; mode: texinfo; -*-
 
 @ignore
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
     When revising a translation, copy the HEAD committish of the
     version that you are working on.  For details, see the Contributors'
     Guide, node Updating translation committishes..
 @end ignore
 
@@ skipping 593 matching lines @@
 @end lisp
 
 @node Scheme in LilyPond
 @section Scheme in LilyPond
 
 
 @menu
 * LilyPond Scheme syntax::
 * LilyPond variables::
 * Input variables and Scheme::
+* Importing Scheme in LilyPond::
 * Object properties::
 * LilyPond compound variables::
 * Internal music representation::
 @end menu
 
 @node LilyPond Scheme syntax
 @subsection LilyPond Scheme syntax
 @funindex $
 @funindex #
 
@@ skipping 30 matching lines @@
 expressions.  In this case, Lilypond evaluates the code right after the
 lexer has read it.  It checks the resulting type of the Scheme
 expression and then picks a token type (one of several
 @code{xxx_IDENTIFIER} in the syntax) for it.  It creates a @emph{copy}
 of the value and uses that for the value of the token.  If the value of
 the expression is void (Guile's value of @code{*unspecified*}), nothing
 at all is passed to the parser.
 
 This is, in fact, exactly the same mechanism that Lilypond employs when
 you call any variable or music function by name, as @code{\name}, with
-the only difference that its end is determined by the Lilypond lexer
+the only difference that the name is determined by the Lilypond lexer
 without consulting the Scheme reader, and thus only variable names
 consistent with the current Lilypond mode are accepted.
 
 The immediate action of @code{$} can lead to surprises, @ref{Input
 variables and Scheme}.  Using @code{#} where the parser supports it is
 usually preferable.
+
+@funindex $@@
+@funindex #@@
+There are also @q{list splicing} operators @code{$@@} and @code{#@@}
+that insert all elements of a list in the surrounding context.
 
 Now let's take a look at some actual Scheme code.  Scheme procedures can
 be defined in LilyPond input files:
 
 @example
 #(define (average a b c) (/ (+ a b c) 3))
 @end example
 
 Note that LilyPond comments (@code{%} and @code{%@{ %@}}) cannot
 be used within Scheme code, even in a LilyPond input file, because
@@ skipping 112 matching lines @@
 @code{twice}:
 
 @lilypond[verbatim]
 traLaLa = { c'4 d'4 }
 
 #(define newLa (map ly:music-deep-copy
   (list traLaLa traLaLa)))
 #(define twice
   (make-sequential-music newLa))
 
-{ \twice }
+\twice
 @end lilypond
 
 @c Due to parser lookahead
 
 This is actually a rather interesting example.  The assignment will only
 take place after the parser has ascertained that nothing akin to
 @code{\addlyrics} follows, so it needs to check what comes next.  It
 reads @code{#} and the following Scheme expression @emph{without}
 evaluating it, so it can go ahead with the assignment, and
 @emph{afterwards} execute the Scheme code without problem.
 
+@node Importing Scheme in LilyPond
+@subsection Importing Scheme in LilyPond
+@funindex $
+@funindex #
+
 The above example shows how to @q{export} music expressions from the
 input to the Scheme interpreter.  The opposite is also possible.  By
 placing it after @code{$}, a Scheme
 value is interpreted as if it were entered in LilyPond syntax.
 Instead of defining @code{\twice}, the example above could also have
 been written as
 
 @example
 ...
-@{ $(make-sequential-music (list newLa)) @}
+$(make-sequential-music newLa)
 @end example
 
 You can use @code{$} with a Scheme expression anywhere you could use
 @code{\@var{name}} after having assigned the Scheme expression to a
 variable @var{name}.  This replacement happens in the @q{lexer}, so
 Lilypond is not even aware of the difference.
 
 One drawback, however, is that of timing.  If we had been using @code{$}
 instead of @code{#} for defining @code{newLa} in the above example, the
 following Scheme definition would have failed because @code{traLaLa}
 would not yet have been defined.  For an explanation of this timing
 problem, @ref{LilyPond Scheme syntax}.
 
-In any case, evaluation of Scheme code happens in the parser at latest.
-If you need it to be executed at a later point of time, @ref{Void scheme
-functions}, or store it in a macro:
+@funindex $@@
+@funindex #@@
+A further convenience can be the @q{list splicing} operators @code{$@@}
+and @code{#@@} for inserting the elements of a list in the surrounding
+context.  Using those, the last part of the example could have been
+written as
+
+@example
+...
+@{ $@@newLa @}
+@end example
+
+Here, every element of the list stored in @code{newLa} is taken in
+sequence and inserted into the list, as if we had written
+
+@example
+@{ $(first newLa) $(second newLa) @}
+@end example
+
+Now in all of these forms, the Scheme code is evaluated while the
+input is still being consumed, either in the lexer or in the parser.
+If you need it to be executed at a later point of time, check out
+@ref{Void scheme functions}, or store it in a procedure:
 
 @example
 #(define (nopc)
   (ly:set-option 'point-and-click #f))
 
 ...
 #(nopc)
 @{ c'4 @}
 @end example
 
@@ skipping 664 matching lines @@
 #{
   $x e8 a b $y b a e
 #})
 
 \relative c''{
   \pattern c8 c8\f
   \pattern {d16 dis} { ais16-> b\p }
 }
 @end lilypond
 @end ignore