Re: [Lilypond-auto] Issue 2607 in lilypond: Patch: Allow immediate Scheme expressions to take multiple values

[Werner LEMBERG]

> The inspiration for this ,@ is described as
> 
>      If an `(unquote-splicing <expression> ...)' form appears inside a
>      <qq template>, then the <expression>s must evaluate to lists; the
>      opening and closing parentheses of the lists are then "stripped
>      away" and the elements of the lists are inserted in place of the
>      `UNQUOTE-SPLICING' form.
> 
>      Any `UNQUOTE-SPLICING' or multi-operand `UNQUOTE' form must appear
>      only within a list or vector <qq template>.
> 
>      The following abbreviations may be used:
> 
>           (quasiquote <qq template>)       =  `<qq template>
>           (unquote <expression>)           =  ,<expression>
>           (unquote-splicing <expression>)  =  ,@<expression>
> 
>      Examples:
> 
>           `(list ,(+ 1 2) 4)                      => (list 3 4)
> 
>           (let ((name 'a))
>             `(list ,name ',name))                 => (list a (quote a))
> 
>           `(a ,(+ 1 2) ,@(map abs '(4 -5 6)) b)   => (a 3 4 5 6 b)
> 
>           `((foo ,(- 10 3))
>             ,@(cdr '(c)) . ,(car '(cons)))        => ((foo 7) . cons)
> 
>           `#(10 5 ,(sqrt 4) ,@(map sqrt '(16 9)) 8)
>                                                   => #(10 5 2 4 3 8)
> 
> Suggestions for improving the docs?

I find the above much too dense.  It introduces three different pseudo
operators in one rush.  While tightly related, it should be done step
by step.  So this is a criticism of the R6RS docs (being a standard to
be read by Scheme experts), not LilyPond.  However, a casual reader
not so fluent in Scheme will tear one's hair if she gets confronted
with your $@ form.

Perhaps it's a bit redundant, but I think that it would help many
readers if some Scheme basics are added to the documentation of $@
*directly*, demonstrating the unquote-splicing mechanism in very basic
examples.


    Werner