Re: (doc help) scheme: why not start with define-music-function ?

[Nicolas Sceaux]

Graham Percival <address@hidden> writes:

> In the current manual, define-music-function is introduced late in the
> scheme chapter.  I suspect that this is simply because
> define-music-function is a more recent lilypond construct, and whoever
> added it didn't want to disturb the existing material.  Is that
> correct?

You're absolutely right. First, the doc for ly:make-music-function was
introduced, then I added something for define-music-function, preserving
the previous documentation. Reading it again now, it is really strange.

> I'm revising the chapter now (as you can tell from the previous
> half-dozen emails :), and it makes sense to me to _begin_ the chapter
> with define-music-function, and then work through the general theory
> of scheme, lilypond music expressions, etc.  In other words, stick the
> define-music-function stuff *before* the current 11.1.1.  Are there
> any objections?  I really don't think that people need to know what
> #(ly:make-music-function  (11.1.3) does before using
> define-music-function, but I still can't claim to fully understand
> #(ly:make-music-function  myself, so I might be missing some vital
> info.

ly:make-music-function is the interface with C++ code, and
define-music-function is the public interface. People don't need to know
about ly:make-music-function at all (people who would have to use it
would find it by themselves anyway).

> My current sense is that define-music-function and \displayMusic (and
> perhaps a bit of patience) are the most important parts of 11.1.
> Thoughts?

define-music-function, with a very straight forward use of the #{ #}
syntax, may be introduced first. 

%%% Example with one music argument (a note)
custosNote = 
#(define-music-function (parser location note)
                        (ly:music?)
  #{ 
    \once \override Voice.NoteHead #'stencil = 
      #ly:text-interface::print
    \once \override Voice.NoteHead #'text = 
      \markup \musicglyph #"custodes.mensural.u0"
    \once \override Voice.Stem #'stencil = ##f 
    $note
  #})

{ c' d' e' f' \custosNote g' }


%%% Example with two music arguments
firstAndSecondTime = 
#(define-music-function (parser location first-time second-time) 
                        (ly:music? ly:music?)
  #{
    \set Score.repeatCommands = #'((volta "1."))
    $first-time
    \bar ":|"
    \set Score.repeatCommands = #'((volta #f) (volta "2."))
    $second-time
    \set Score.repeatCommands = #'((volta #f)) 
  #})

{ c'2 c'
  \firstAndSecondTime { d' d' } { e' e' }
}

%%% Example with a markup argument
tempoMark =
#(define-music-function (parser location tempo-markup)
                        (markup?)
  #{
    \once \override Score . RehearsalMark #'self-alignment-X = #-1
    \once \override Score . RehearsalMark #'no-spacing-rods = ##t
    \once \override Score . RehearsalMark #'padding = #2
    \once \override Score . RehearsalMark #'break-align-symbol = #'left-edge
    \mark \markup \fontsize #-1 \italic $tempo-markup 
  #})

{
  \tempoMark \markup { Allegro molto. } 
  c'' c'' c'' c'' 
  \mark "Another mark"
   c'' c'' c'' c'' 
}


In a second step, a more complex example, requiring manipulating music
expressions, could be explained. There, \displayMusic should be used.
I don't have a good example in mind at the moment...

nicolas