1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
13 @node Interfaces for programmers
14 @chapter Interfaces for programmers
16 Advanced tweaks may be performed by using Scheme. If you are
17 not familiar with Scheme, you may wish to read our
18 @ref{Scheme tutorial}.
23 * Contexts for programmers::
24 * Callback functions::
25 * Inline Scheme code::
31 @section Music functions
33 Music functions are scheme functions that are used to
34 automatically create music expressions. They can be used to
35 greatly simplify the input file.
38 * Music function syntax::
39 * Simple substitution functions::
40 * Intermediate substitution functions::
41 * Mathematics in functions::
43 * Functions without arguments::
46 @node Music function syntax
47 @subsection Music function syntax
49 The general syntax of a music function is:
53 #(define-music-function (parser location @var{var_1} @var{var_2}...@var{var_n})
54 (@var{var_1-type?} @var{var_2-type?}...@var{var_n-type?})
55 @var{...valid music expression...})
61 @multitable @columnfractions .33 .66
62 @item @var{var_i} @tab @var{i}th variable
63 @item @var{var_i-type?} @tab type of @var{i}th variable
64 @item @var{...valid music expression...} @tab expression that returns
65 valid music, generally in the form of a Scheme expression. There is
66 also special syntax that allows LilyPond input code in this music
70 The variable type checkers are scheme procedures that will return
71 @code{#t} if a variable is of a given type. Some common types
72 are shown in the table below. Other types can be found in the files
73 @file{lily/music-scheme.cc} and @file{scm/c++.scm}. The complete
74 list of named type checkers for LilyPond is found in the
75 @var{type-p-name-alist} of @file{scm/lily.scm}.
77 @c TODO -- automatically document type-p-name-alist
79 @multitable @columnfractions .33 .66
80 @headitem Input type @tab @var{vari-type?} notation
81 @item Integer @tab @code{integer?}
82 @item Float (decimal number) @tab @code{number?}
83 @item Text string @tab @code{string?}
84 @item Markup @tab @code{markup?}
85 @item Music expression @tab @code{ly:music?}
86 @item A pair of variables @tab @code{pair?}
89 The @code{parser} and @code{location} arguments are mandatory.
90 The @code{parser} argument is used in the body of the function
91 to gain access to the value of another LilyPond variable.
92 The @code{location} argument is used to set the @q{origin}
93 of the music expression that is built by the music function,
94 so that in case of a syntax error LilyPond
95 can tell the user an appropriate place to look in the input file.
97 @node Simple substitution functions
98 @subsection Simple substitution functions
100 A simple substitution function is a music function whose output music
101 expression is written in LilyPond code, but with an input variable
102 substituted into the LilyPond code. The general form of these functions is
106 #(define-music-function (parser location @var{var1})
109 @emph{... LilyPond input code with} @code{#$var1} @emph{for substition ...}
113 Note that the special characters @code{#@{} and @code{#@}} surround the
116 @multitable @columnfractions .33 .66
117 @item @var{vari} @tab @var{i}th variable
118 @item @var{vari-type?} @tab type of @var{i}th variable
119 @item @var{...music...} @tab normal LilyPond input, using
120 variables as @code{#$var1}, etc.
123 For example, a function can be defined that simplifies
124 setting the padding of a TextScript:
126 @lilypond[quote,verbatim,ragged-right]
127 padText = #(define-music-function (parser location padding) (number?)
129 \once \override TextScript #'padding = #$padding
137 c4^"piu mosso" fis a g
141 In addition to numbers, we can use music expressions such
142 as notes for arguments to music functions:
144 @lilypond[quote,verbatim,ragged-right]
145 custosNote = #(define-music-function (parser location note)
148 \once \override Voice.NoteHead #'stencil =
149 #ly:text-interface::print
150 \once \override Voice.NoteHead #'text =
151 \markup \musicglyph #"custodes.mensural.u0"
152 \once \override Voice.Stem #'stencil = ##f
157 @node Intermediate substitution functions
158 @subsection Intermediate substitution functions
160 Slightly more complicated than simple substitution function,
161 intermediate substitution functions involve a mix of Scheme code and
162 LilyPond code in the music expression to be
165 Some @code{\override} commands require an argument consisting of
166 a pair of numbers (called a @code{cons cell} in Scheme).
168 The pair can be directly passed into the music function,
169 using a @code{pair?} variable:
174 #(define-music-function (parser location beg-end)
177 \once \override Beam #'positions = #$beg-end
181 \manualBeam #'(3 . 6) c8 d e f
186 Alternatively, the numbers making up the pair can be
187 passed as separate arguments, and the Scheme code
188 used to create the pair can be included in the
191 @lilypond[quote,verbatim,ragged-right]
193 #(define-music-function (parser location beg end)
196 \once \override Beam #'positions = #(cons $beg $end)
200 \manualBeam #3 #6 c8 d e f
205 @node Mathematics in functions
206 @subsection Mathematics in functions
208 Music functions can involve Scheme programming in
209 addition to simple substitution,
211 @lilypond[quote,verbatim,ragged-right]
212 AltOn = #(define-music-function (parser location mag) (number?)
213 #{ \override Stem #'length = #$(* 7.0 mag)
214 \override NoteHead #'font-size =
215 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #})
218 \revert Stem #'length
219 \revert NoteHead #'font-size
222 { c'2 \AltOn #0.5 c'4 c'
223 \AltOn #1.5 c' c' \AltOff c'2 }
227 This example may be rewritten to pass in music expressions,
229 @lilypond[quote,verbatim,ragged-right]
230 withAlt = #(define-music-function (parser location mag music) (number? ly:music?)
231 #{ \override Stem #'length = #$(* 7.0 mag)
232 \override NoteHead #'font-size =
233 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
235 \revert Stem #'length
236 \revert NoteHead #'font-size #})
238 { c'2 \withAlt #0.5 {c'4 c'}
239 \withAlt #1.5 {c' c'} c'2 }
243 @subsection Void functions
245 A music function must return a music expression, but sometimes we
246 may want to have a function that does not involve music (such as
247 turning off Point and Click). To do this, we return a @code{void}
251 that is returned is the @code{(make-music ...)}. With the
252 @code{'void} property set to @code{#t}, the parser is told to
253 actually disregard this returned music
254 expression. Thus the important part of the void music function is the
255 processing done by the function, not the music expression that is
260 #(define-music-function (parser location) ()
261 (ly:set-option 'point-and-click #f)
262 (make-music 'SequentialMusic 'void #t))
264 \noPointAndClick % disable point and click
268 @node Functions without arguments
269 @subsection Functions without arguments
271 In most cases a function without arguments should be written
275 dolce = \markup@{ \italic \bold dolce @}
278 However, in rare cases it may be useful to create a music function
283 #(define-music-function (parser location) ()
284 (if (eq? #t (ly:get-option 'display-bar-numbers))
285 #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
289 To actually display bar numbers where this function is called,
290 invoke @command{lilypond} with
293 lilypond -d display-bar-numbers FILENAME.ly
298 @node Markup functions
299 @section Markup functions
301 Markups are implemented as special Scheme functions which produce a
302 @code{Stencil} object given a number of arguments.
305 * Markup construction in Scheme::
306 * How markups work internally::
307 * New markup command definition::
308 * New markup list command definition::
312 @node Markup construction in Scheme
313 @subsection Markup construction in Scheme
315 @cindex defining markup commands
317 The @code{markup} macro builds markup expressions in Scheme while
318 providing a LilyPond-like syntax. For example,
320 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
321 #:larger #:line ("foo" "bar" "baz")))
327 \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
328 \larger \line @{ foo bar baz @} @}
332 This example demonstrates the main translation rules between regular
333 LilyPond markup syntax and Scheme markup syntax.
336 @multitable @columnfractions .3 .3
337 @item @b{LilyPond} @tab @b{Scheme}
338 @item @code{\markup markup1} @tab @code{(markup markup1)}
339 @item @code{\markup @{ markup1 markup2 ... @}} @tab
340 @code{(markup markup1 markup2 ... )}
341 @item @code{\markup-command} @tab @code{#:markup-command}
342 @item @code{\variable} @tab @code{variable}
343 @item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
344 @item @code{string} @tab @code{"string"}
345 @item @code{#scheme-arg} @tab @code{scheme-arg}
349 The whole Scheme language is accessible inside the
350 @code{markup} macro. For example, You may use function calls inside
351 @code{markup} in order to manipulate character strings. This is
352 useful when defining new markup commands (see
353 @ref{New markup command definition}).
358 The markup-list argument of commands such as @code{#:line},
359 @code{#:center}, and @code{#:column} cannot be a variable or
360 the result of a function call.
363 (markup #:line (function-that-returns-markups))
367 is invalid. One should use the @code{make-line-markup},
368 @code{make-center-markup}, or @code{make-column-markup} functions
372 (markup (make-line-markup (function-that-returns-markups)))
376 @node How markups work internally
377 @subsection How markups work internally
382 \raise #0.5 "text example"
386 @code{\raise} is actually represented by the @code{raise-markup}
387 function. The markup expression is stored as
390 (list raise-markup 0.5 (list simple-markup "text example"))
393 When the markup is converted to printable objects (Stencils), the
394 @code{raise-markup} function is called as
399 @var{list of property alists}
401 @var{the "text example" markup})
404 The @code{raise-markup} function first creates the stencil for the
405 @code{text example} string, and then it raises that Stencil by 0.5
406 staff space. This is a rather simple example; more complex examples
408 of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
411 @node New markup command definition
412 @subsection New markup command definition
414 This section discusses the definition of new markup commands.
417 * Markup command definition syntax::
419 * A complete example::
420 * Adapting builtin commands::
423 @node Markup command definition syntax
424 @unnumberedsubsubsec Markup command definition syntax
426 New markup commands can be defined using the
427 @code{define-markup-command} Scheme macro, at top-level.
430 (define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
431 (@var{arg1-type?} @var{arg2-type?} ...)
432 [ #:properties ((@var{property1} @var{default-value1})
441 the markup command name
443 the @q{layout} definition.
445 a list of associative lists, containing all active properties.
447 @var{i}th command argument
449 a type predicate for the i@var{th} argument
452 If the command uses properties from the @var{props} arguments, the
453 @code{#:properties} keyword can be used, to specify which properties are
454 used, and their default values.
457 There are restrictions on the possible arguments to a markup command.
459 Arguments are distingued according to their type:
461 @item a markup, corresponding to type predicate @code{markup?};
462 @item a list of markup, corresponding to type predicate
464 @item any other scheme object, corresponding to type predicates such as
465 @code{list?}, @code{number?}, @code{boolean?}, etc.
468 The available combinations of arguments (after the standard @var{layout}
469 and @var{props} arguments) to a markup command defined with
470 @code{define-markup-command} are limited as follows.
474 @itemx @var{markup-list}
476 @itemx @var{markup markup}
478 @itemx @var{scheme markup}
479 @itemx @var{scheme scheme}
480 @itemx @var{scheme scheme markup}
481 @itemx @var{scheme scheme markup markup}
482 @itemx @var{scheme markup markup}
483 @itemx @var{scheme scheme scheme}
487 This means that it is not possible to define with e.g. three scheme
488 arguments and a markup arguments, like:
491 #(define-markup-command (foo layout props
492 num1 num2 a-list a-markup)
493 (number? number? list? markup?)
498 If you apply it as, say,
501 \markup \foo #1 #2 #'(bar baz) Blah
504 @cindex Scheme signature
505 @cindex signature, Scheme
507 @command{lilypond} complains that it cannot parse @code{foo} due to its
508 unknown Scheme signature.
511 @unnumberedsubsubsec On properties
513 The @code{layout} and @code{props} arguments of markup commands bring a
514 context for the markup interpretation: font size, line width, etc.
516 The @code{layout} argument allows access to properties defined in
517 @code{paper} blocks, using the @code{ly:output-def-lookup} function.
518 For instance, the line width (the same as the one used in scores) is
522 (ly:output-def-lookup layout 'line-width)
525 The @code{props} argument makes some properties accessible to markup
526 commands. For instance, when a book title markup is interpreted, all
527 the variables defined in the @code{\header} block are automatically
528 added to @code{props}, so that the book title markup can access the book
529 title, composer, etc. It is also a way to configure the behaviour of a
530 markup command: for example, when a command uses font size during
531 processing, the font size is read from @code{props} rather than having a
532 @code{font-size} argument. The caller of a markup command may change
533 the value of the font size property in order to change the behaviour.
534 Use the @code{#:properties} keyword of @code{define-markup-command} to
535 specify which properties shall be read from the @code{props} arguments.
537 The example in next section illustrates how to access and override
538 properties in a markup command.
540 @node A complete example
541 @unnumberedsubsubsec A complete example
543 The following example defines a markup command to draw a double box
544 around a piece of text.
546 Firstly, we need to build an approximative result using markups.
547 Consulting the @ruser{Text markup commands} shows us the @code{\box}
550 @lilypond[quote,verbatim,ragged-right]
551 \markup \box \box HELLO
554 Now, we consider that more padding between the text and the boxes is
555 preferable. According to the @code{\box} documentation, this command
556 uses a @code{box-padding} property, which defaults to 0.2. The
557 documentation also mentions how to override it:
559 @lilypond[quote,verbatim,ragged-right]
560 \markup \box \override #'(box-padding . 0.6) \box A
563 Then, the padding between the two boxes is considered too small, so we
566 @lilypond[quote,verbatim,ragged-right]
567 \markup \override #'(box-padding . 0.4) \box \override #'(box-padding . 0.6) \box A
570 Repeating this lengthy markup would be painful. This is where a markup
571 command is needed. Thus, we write a @code{double-box} markup command,
572 taking one argument (the text). This draws the two boxes, with some
576 #(define-markup-command (double-box layout props text) (markup?)
577 "Draw a double box around text."
578 (interpret-markup layout props
579 (markup #:override '(box-padding . 0.4) #:box
580 #:override '(box-padding . 0.6) #:box text)))
583 @code{text} is the name of the command argument, and @code{markup?} its
584 type: it identifies it as a markup. The @code{interpret-markup}
585 function is used in most of markup commands: it builds a stencil, using
586 @code{layout}, @code{props}, and a markup. Here, this markup is built
587 using the @code{markup} scheme macro, see @ref{Markup construction in Scheme}.
588 The transformation from @code{\markup} expression to scheme
589 markup expression is straight-forward.
591 The new command can be used as follow:
594 \markup \double-box A
597 It would be nice to make the @code{double-box} command customizable:
598 here, the @code{box-padding} values are hard coded, and cannot be
599 changed by the user. Also, it would be better to distinguish the
600 padding between the two boxes, from the padding between the inner box
601 and the text. So we will introduce a new property,
602 @code{inter-box-padding}, for the padding between the two boxes. The
603 @code{box-padding} will be used for the inner padding. The new code is
607 #(define-markup-command (double-box layout props text) (markup?)
608 #:properties ((inter-box-padding 0.4)
610 "Draw a double box around text."
611 (interpret-markup layout props
612 (markup #:override `(box-padding . ,inter-box-padding) #:box
613 #:override `(box-padding . ,box-padding) #:box text)))
616 Here, the @code{#:properties} keyword is used so that the
617 @code{inter-box-padding} and @code{box-padding} properties are read from
618 the @code{props} argument, and default values are given to them if the
619 properties are not defined.
621 Then, these values are used to override the @code{box-padding}
622 properties used by the two @code{\box} commands. Note the backquote and
623 the comma in the @code{\override} argument: they allow you to introduce
624 a variable value into a literal expression.
626 Now, the command can be used in a markup, and the boxes padding be
629 @lilypond[quote,verbatim,ragged-right]
630 #(define-markup-command (double-box layout props text) (markup?)
631 #:properties ((inter-box-padding 0.4)
633 "Draw a double box around text."
634 (interpret-markup layout props
635 (markup #:override `(box-padding . ,inter-box-padding) #:box
636 #:override `(box-padding . ,box-padding) #:box text)))
638 \markup \double-box A
639 \markup \override #'(inter-box-padding . 0.8) \double-box A
640 \markup \override #'(box-padding . 1.0) \double-box A
643 @node Adapting builtin commands
644 @unnumberedsubsubsec Adapting builtin commands
646 A good way to start writing a new markup command, is to take example on
647 a builtin one. Most of the markup commands provided with LilyPond can be
648 found in file @file{scm/@/define@/-markup@/-commands@/.scm}.
650 For instance, we would like to adapt the @code{\draw-line} command, to
651 draw a double line instead. The @code{\draw-line} command is defined as
652 follow (documentation stripped):
655 (define-markup-command (draw-line layout props dest)
658 #:properties ((thickness 1))
660 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
664 (make-line-stencil th 0 0 x y)))
667 To define a new command based on an existing one, copy the definition,
668 and change the command name. The @code{#:category} keyword can be
669 safely removed, as it is only used for generating LilyPond
670 documentation, and is of no use for user-defined markup commands.
673 (define-markup-command (draw-double-line layout props dest)
675 #:properties ((thickness 1))
677 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
681 (make-line-stencil th 0 0 x y)))
684 Then, a property for setting the gap between two lines is added, called
685 @code{line-gap}, defaulting e.g. to 0.6:
688 (define-markup-command (draw-double-line layout props dest)
690 #:properties ((thickness 1)
696 Finally, the code for drawing two lines is added. Two calls to
697 @code{make-line-stencil} are used to draw the lines, and the resulting
698 stencils are combined using @code{ly:stencil-add}:
700 @lilypond[quote,verbatim,ragged-right]
701 #(define-markup-command (my-draw-line layout props dest)
703 #:properties ((thickness 1)
706 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
711 (x (cond ((= dx 0) w)
713 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
714 (y (* (if (< (* dx dy) 0) 1 -1)
717 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
718 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
719 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
721 \markup \my-draw-line #'(4 . 3)
722 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
726 @node New markup list command definition
727 @subsection New markup list command definition
728 Markup list commands are defined with the
729 @code{define-markup-list-command} Scheme macro, which is similar to the
730 @code{define-markup-command} macro described in
731 @ref{New markup command definition}, except that where the latter returns
732 a single stencil, the former returns a list of stencils.
734 In the following example, a @code{\paragraph} markup list command is
735 defined, which returns a list of justified lines, the first one being
736 indented. The indent width is taken from the @code{props} argument.
738 #(define-markup-list-command (paragraph layout props args) (markup-list?)
739 #:properties ((par-indent 2))
740 (interpret-markup-list layout props
741 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
745 Besides the usual @code{layout} and @code{props} arguments, the
746 @code{paragraph} markup list command takes a markup list argument, named
747 @code{args}. The predicate for markup lists is @code{markup-list?}.
749 First, the function gets the indent width, a property here named
750 @code{par-indent}, from the property list @code{props}. If the
751 property is not found, the default value is @code{2}. Then, a
752 list of justified lines is made using the
753 @code{make-justified-lines-markup-list} function, which is related
754 to the @code{\justified-lines} built-in markup list command. A
755 horizontal space is added at the beginning using the
756 @code{make-hspace-markup} function. Finally, the markup list is
757 interpreted using the @code{interpret-markup-list} function.
759 This new markup list command can be used as follows:
763 The art of music typography is called \italic @{(plate) engraving.@}
764 The term derives from the traditional process of music printing.
765 Just a few decades ago, sheet music was made by cutting and stamping
766 the music into a zinc or pewter plate in mirror image.
768 \override-lines #'(par-indent . 4) \paragraph @{
769 The plate would be inked, the depressions caused by the cutting
770 and stamping would hold ink. An image was formed by pressing paper
771 to the plate. The stamping and cutting was completely done by
777 @node Contexts for programmers
778 @section Contexts for programmers
781 * Context evaluation::
782 * Running a function on all layout objects::
785 @node Context evaluation
786 @subsection Context evaluation
788 @cindex calling code during interpreting
789 @funindex \applyContext
791 Contexts can be modified during interpretation with Scheme code. The
794 \applyContext @var{function}
797 @var{function} should be a Scheme function that takes a single
798 argument: the context in which the @code{\applyContext} command is
799 being called. The following code will print the current bar
800 number on the standard output during the compile:
805 (format #t "\nWe were called in barnumber ~a.\n"
806 (ly:context-property x 'currentBarNumber)))
811 @node Running a function on all layout objects
812 @subsection Running a function on all layout objects
815 @cindex calling code on layout objects
816 @funindex \applyOutput
819 The most versatile way of tuning an object is @code{\applyOutput}. Its
822 \applyOutput @var{context} @var{proc}
826 where @var{proc} is a Scheme function, taking three arguments.
828 When interpreted, the function @var{proc} is called for every layout
829 object found in the context @var{context}, with the following
832 @item the layout object itself,
833 @item the context where the layout object was created, and
834 @item the context where @code{\applyOutput} is processed.
838 In addition, the cause of the layout object, i.e., the music
839 expression or object that was responsible for creating it, is in the
840 object property @code{cause}. For example, for a note head, this is a
841 @rinternals{NoteHead} event, and for a @rinternals{Stem} object,
842 this is a @rinternals{NoteHead} object.
844 Here is a function to use for @code{\applyOutput}; it blanks
845 note-heads on the center-line:
847 @lilypond[quote,verbatim,ragged-right]
848 #(define (blanker grob grob-origin context)
849 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
850 (eq? (ly:grob-property grob 'staff-position) 0))
851 (set! (ly:grob-property grob 'transparent) #t)))
854 e4 g8 \applyOutput #'Voice #blanker b d2
859 @node Callback functions
860 @section Callback functions
862 Properties (like @code{thickness}, @code{direction}, etc.) can be
863 set at fixed values with @code{\override}, e.g.
866 \override Stem #'thickness = #2.0
869 Properties can also be set to a Scheme procedure,
871 @lilypond[fragment,verbatim,quote,relative=2]
872 \override Stem #'thickness = #(lambda (grob)
873 (if (= UP (ly:grob-property grob 'direction))
880 In this case, the procedure is executed as soon as the value of the
881 property is requested during the formatting process.
883 Most of the typesetting engine is driven by such callbacks.
884 Properties that typically use callbacks include
888 The printing routine, that constructs a drawing for the symbol
890 The routine that sets the horizontal position
892 The routine that computes the width of an object
895 The procedure always takes a single argument, being the grob.
897 If routines with multiple arguments must be called, the current grob
898 can be inserted with a grob closure. Here is a setting from
899 @code{AccidentalSuggestion},
903 ,(ly:make-simple-closure
905 ,(ly:make-simple-closure
906 (list ly:self-alignment-interface::centered-on-x-parent))
907 ,(ly:make-simple-closure
908 (list ly:self-alignment-interface::x-aligned-on-self)))))
912 In this example, both @code{ly:self-alignment-interface::x-aligned-on-self} and
913 @code{ly:self-alignment-interface::centered-on-x-parent} are called
914 with the grob as argument. The results are added with the @code{+}
915 function. To ensure that this addition is properly executed, the whole
916 thing is enclosed in @code{ly:make-simple-closure}.
918 In fact, using a single procedure as property value is equivalent to
921 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
925 The inner @code{ly:make-simple-closure} supplies the grob as argument
926 to @var{proc}, the outer ensures that result of the function is
927 returned, rather than the @code{simple-closure} object.
929 From within a callback, the easiest method for evaluating a markup is
930 to use grob-interpret-markup. For example:
933 my-callback = #(lambda (grob)
934 (grob-interpret-markup grob (markup "foo")))
937 @node Inline Scheme code
938 @section Inline Scheme code
940 The main disadvantage of @code{\tweak} is its syntactical
941 inflexibility. For example, the following produces a syntax error.
944 F = \tweak #'font-size #-3 -\flageolet
952 In other words, @code{\tweak} doesn't behave like an articulation
953 regarding the syntax; in particular, it can't be attached with
954 @code{^} and @code{_}.
956 Using Scheme, this problem can be avoided. The route to the
957 result is given in @ref{Adding articulation to notes (example)},
958 especially how to use @code{\displayMusic} as a helping guide.
961 F = #(let ((m (make-music 'ArticulationEvent
962 'articulation-type "flageolet")))
963 (set! (ly:music-property m 'tweaks)
965 (ly:music-property m 'tweaks)))
974 Here, the @code{tweaks} properties of the flageolet object
975 @code{m} (created with @code{make-music}) are extracted with
976 @code{ly:music-property}, a new key-value pair to change the
977 font size is prepended to the property list with the
978 @code{acons} Scheme function, and the result is finally
979 written back with @code{set!}. The last element of the
980 @code{let} block is the return value, @code{m} itself.
984 @node Difficult tweaks
985 @section Difficult tweaks
987 There are a few classes of difficult adjustments.
993 One type of difficult adjustment involves the appearance of
994 spanner objects, such as slurs and ties. Usually, only one
995 spanner object is created at a time, and it can be adjusted with
996 the normal mechanism. However, occasionally a spanner crosses a
997 line break. When this happens, the object is cloned. A separate
998 object is created for every system in which the spanner appears.
999 The new objects are clones of the original object and inherit all
1000 properties, including @code{\override}s.
1003 In other words, an @code{\override} always affects all pieces of a
1004 broken spanner. To change only one part of a spanner at a line break,
1005 it is necessary to hook into the formatting process. The
1006 @code{after-line-breaking} callback contains the Scheme procedure that
1007 is called after the line breaks have been determined and layout
1008 objects have been split over different systems.
1010 In the following example, we define a procedure
1011 @code{my-callback}. This procedure
1015 determines if the spanner has been split across line breaks
1017 if yes, retrieves all the split objects
1019 checks if this grob is the last of the split objects
1021 if yes, it sets @code{extra-offset}.
1024 This procedure is installed into @rinternals{Tie}, so the last part
1025 of the broken tie is repositioned.
1027 @lilypond[quote,verbatim,ragged-right]
1028 #(define (my-callback grob)
1030 ; have we been split?
1031 (orig (ly:grob-original grob))
1033 ; if yes, get the split pieces (our siblings)
1034 (siblings (if (ly:grob? orig)
1035 (ly:spanner-broken-into orig) '() )))
1037 (if (and (>= (length siblings) 2)
1038 (eq? (car (last-pair siblings)) grob))
1039 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1042 \override Tie #'after-line-breaking =
1049 When applying this trick, the new @code{after-line-breaking} callback
1050 should also call the old one @code{after-line-breaking}, if there is
1051 one. For example, if using this with @code{Hairpin},
1052 @code{ly:hairpin::after-line-breaking} should also be called.
1055 @item Some objects cannot be changed with @code{\override} for
1056 technical reasons. Examples of those are @code{NonMusicalPaperColumn}
1057 and @code{PaperColumn}. They can be changed with the
1058 @code{\overrideProperty} function, which works similar to @code{\once
1059 \override}, but uses a different syntax.
1063 #"Score.NonMusicalPaperColumn" % Grob name
1064 #'line-break-system-details % Property name
1065 #'((next-padding . 20)) % Value
1068 Note, however, that @code{\override}, applied to
1069 @code{NonMusicalPaperColumn} and @code{PaperColumn}, still works as
1070 expected within @code{\context} blocks.
1074 @node LilyPond Scheme interfaces
1075 @chapter LilyPond Scheme interfaces
1077 This chapter covers the various tools provided by LilyPond to help
1078 Scheme programmers get information into and out of the music streams.
1080 TODO -- figure out what goes in here and how to organize it