@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond.tely
+@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. See TRANSLATION for details.
+@end ignore
+
+@c \version "2.11.51"
+
@node Interfaces for programmers
@chapter Interfaces for programmers
Advanced tweaks may be performed by using Scheme. If you are
not familiar with Scheme, you may wish to read our
-@ref{Scheme tutorial}.
+@rlearning{Scheme tutorial}.
@menu
* Music functions::
* Building complicated functions::
* Markup programmer interface::
* Contexts for programmers::
-* OLD STUFF::
+* Scheme procedures as properties::
+* TODO moved into scheme::
@end menu
@menu
* Overview of music functions::
* Simple substitution functions::
-* Paired substition functions::
+* Paired substitution functions::
* Mathematics in functions::
* Void functions::
+* Functions without arguments::
+* Overview of available music functions::
@end menu
@node Overview of music functions
@subsection Overview of music functions
-Making a funcion which substitutes a variable into LilyPond
+Making a function which substitutes a variable into LilyPond
code is easy. The general form of these functions is
@example
and are used in some advanced situations. The @code{parser}
argument is used to access to the value of another LilyPond
variable. The @code{location} argument
-is used to set the ``origin'' of the music expression that is built
+is used to set the @q{origin} of the music expression that is built
by the music function, so that in case of a syntax error LilyPond
can tell the user an appropriate place to look in the input file.
(number? string?)
#{
\once \override Score . RehearsalMark #'padding = $padding
- \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
\mark \markup { \bold $marktext }
#})
@end lilypond
-@node Paired substition functions
-@subsection Paired substition functions
+@node Paired substitution functions
+@subsection Paired substitution functions
Some @code{\override} commands require a pair of numbers
(called a @code{cons cell} in Scheme). To pass these numbers
\withAlt #1.5 {c' c'} c'2 }
@end lilypond
-
@node Void functions
@subsection Void functions
music expression.
That is why the form
-that is returned is the @code{(make-music ...)}. With the
+that is returned is the @code{(make-music ...)}. With the
@code{'void} property set to @code{#t}, the parser is told to
actually disregard this returned music
expression. Thus the important part of the void music function is the
@end example
+@node Functions without arguments
+@subsection Functions without arguments
+
+In most cases a function without arguments should be written
+with an variable,
+
+@example
+dolce = \markup@{ \italic \bold dolce @}
+@end example
+
+However, in rare cases it may be useful to create a music function
+without arguments,
+
+@example
+displayBarNum =
+#(define-music-function (parser location) ()
+ (if (eq? #t (ly:get-option 'display-bar-numbers))
+ #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
+ #@{#@}))
+@end example
+
+To actually display bar numbers where this function is called,
+invoke @command{lilypond} with
+
+@example
+lilypond -d display-bar-numbers FILENAME.ly
+@end example
+
+
+@node Overview of available music functions
+@subsection Overview of available music functions
+
+@c fixme ; this should be move somewhere else?
+The following commands are music functions
+
+@include identifiers.tely
+
+
+
@node Programmer interfaces
@section Programmer interfaces
@noindent
is internally converted to a Scheme definition
@example
-(define traLaLa @var{Scheme value of ``@code{... }''})
+(define traLaLa @var{Scheme value of `@code{... }'})
@end example
This means that input variables and Scheme variables may be freely
variable @code{traLaLa}, and duplicated using Scheme. The result is
imported in a @code{\score} block by means of a second variable
@code{twice}:
-@example
-traLaLa = @{ c'4 d'4 @}
+
+@lilypond[verbatim]
+traLaLa = { c'4 d'4 }
+
+%% dummy action to deal with parser lookahead
+#(display "this needs to be here, sorry!")
#(define newLa (map ly:music-deep-copy
(list traLaLa traLaLa)))
#(define twice
(make-sequential-music newLa))
-@{ \twice @}
-@end example
+{ \twice }
+@end lilypond
+
+Due to parser lookahead
-In the above example, music expressions can be `exported' from the
+In this example, the assignment happens after parser has verified that
+nothing interesting happens after @code{traLaLa = @{ ... @}}. Without
+the dummy statement in the above example, the @code{newLa} definition
+is executed before @code{traLaLa} is defined, leading to a syntax
+error.
+
+The above example shows how to @q{export} music expressions from the
input to the Scheme interpreter. The opposite is also possible. By
wrapping a Scheme value in the function @code{ly:export}, 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
+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
@dots{}
@{ #(ly:export (make-sequential-music (list newLa))) @}
@end example
Scheme code is evaluated as soon as the parser encounters it. To
-define some scheme code in a macro (to be called later), use
-@ref{Void functions} or
+define some Scheme code in a macro (to be called later), use
+@ref{Void functions}, or
@example
#(define (nopc)
@end example
-@refbugs
+@knownissues
-Mixing Scheme and LilyPond identifiers is not possible with the
+Mixing Scheme and LilyPond variables is not possible with the
@code{--safe} option.
of a piece of music in whole notes.
A music object has three kinds of types:
-@itemize @bullet
+@itemize
@item
music name: Each music expression has a name. For example, a note
-leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
-a @internalsref{SimultaneousMusic}. A list of all expressions
-available is in the Program reference manual, under
-@internalsref{Music expressions}.
+leads to a @rinternals{NoteEvent}, and @code{\simultaneous} leads to
+a @rinternals{SimultaneousMusic}. A list of all expressions
+available is in the Internals Reference manual, under
+@rinternals{Music expressions}.
@item
-`type' or interface: Each music name has several `types' or
+@q{type} or interface: Each music name has several @q{types} or
interfaces, for example, a note is an @code{event}, but it is also a
@code{note-event}, a @code{rhythmic-event}, and a
@code{melodic-event}. All classes of music are listed in the
-Profram reference, under
-@internalsref{Music classes}.
+Internals Reference, under
+@rinternals{Music classes}.
@item
C++ object: Each music object is represented by an object of the C++
@end itemize
The actual information of a music expression is stored in properties.
-For example, a @internalsref{NoteEvent} has @code{pitch} and
+For example, a @rinternals{NoteEvent} has @code{pitch} and
@code{duration} properties that store the pitch and duration of that
note. A list of all properties available is in the internals manual,
-under @internalsref{Music properties}.
+under @rinternals{Music properties}.
A compound music expression is a music object that contains other
music objects in its properties. A list of objects can be stored in
-the @code{elements} property of a music object, or a single `child'
+the @code{elements} property of a music object, or a single @q{child}
music object in the @code{element} object. For example,
-@internalsref{SequentialMusic} has its children in @code{elements},
-and @internalsref{GraceMusic} has its single argument in
+@rinternals{SequentialMusic} has its children in @code{elements},
+and @rinternals{GraceMusic} has its single argument in
@code{element}. The body of a repeat is stored in the @code{element}
-property of @internalsref{RepeatedMusic}, and the alternatives in
+property of @rinternals{RepeatedMusic}, and the alternatives in
@code{elements}.
@end example
The @code{display-scheme-music} function is the function used by
-@code{\displayMusic} to display the scheme representation of a music
+@code{\displayMusic} to display the Scheme representation of a music
expression.
@example
(ly:make-pitch 0 0 0))
@end example
-Then the note pitch is accessed thourgh the @code{'pitch} property
+Then the note pitch is accessed through the @code{'pitch} property
of the @code{NoteEvent} object,
@example
@subsection Doubling a note with slurs (example)
Suppose we want to create a function which translates
-input like ``@code{a}'' into ``@code{a( a)}''. We begin
+input like @code{a} into @code{a( a)}. We begin
by examining the internal representation of the music
we want to end up with.
@end example
The bad news is that the @code{SlurEvent} expressions
-must be added ``inside'' the note (or more precisely,
+must be added @q{inside} the note (or more precisely,
inside the @code{EventChord} expression).
Now we examine the input,
@code{SequentialMusic} with the two @code{EventChords}.
@example
-doubleSlur = #(def-music-function (parser location note) (ly:music?)
+doubleSlur = #(define-music-function (parser location note) (ly:music?)
"Return: @{ note ( note ) @}.
`note' is supposed to be an EventChord."
(let ((note2 (ly:music-deep-copy note)))
(let ((result-event-chord (ly:music-deep-copy event-chord)))
@end example
-`@code{let}' is used to declare local variables. Here we use one local
-variable, named `@code{result-event-chord}', to which we give the value
-@code{(ly:music-deep-copy event-chord)}. `@code{ly:music-deep-copy}' is
+@code{let} is used to declare local variables. Here we use one local
+variable, named @code{result-event-chord}, to which we give the value
+@code{(ly:music-deep-copy event-chord)}. @code{ly:music-deep-copy} is
a function specific to LilyPond, like all functions prefixed by
-`@code{ly:}'. It is use to make a copy of a music
-expression. Here we copy `@code{event-chord} (the parameter of the
+@code{ly:}. It is use to make a copy of a music
+expression. Here we copy @code{event-chord} (the parameter of the
function). Recall that our purpose is to add a marcato to an
@code{EventChord} expression. It is better to not modify the
@code{EventChord} which was given as an argument, because it may be
used elsewhere.
Now we have a @code{result-event-chord}, which is a
-@code{oteEventChord} expression and is a copy of @code{event-chord}. We
+@code{NoteEventChord} expression and is a copy of @code{event-chord}. We
add the marcato to its elements list property.
@example
(set! place new-value)
@end example
-Here, what we want to set (the "place") is the "elements" property of
-@code{result-event-chord} expression
+Here, what we want to set (the @q{place}) is the @q{elements} property of
+@code{result-event-chord} expression.
@example
(ly:music-property result-event-chord 'elements)
(the @code{'elements}, @code{'duration}, @code{'pitch}, etc, that we
see in the @code{\displayMusic} output above). The new value is the
former elements property, with an extra item: the
-@code{MarcatoEvent} expression, which we copy from the
+@code{ArticulationEvent} expression, which we copy from the
@code{\displayMusic} output,
@example
(ly:music-property result-event-chord 'elements))
@end example
-`@code{cons}' is used to add an element to a list without modifying the
+@code{cons} is used to add an element to a list without modifying the
original list. This is what we
want: the same list as before, plus the new @code{ArticulationEvent}
expression. The order inside the elements property is not important here.
-Finally, once we have added the @code{MarcatoEvent} to its elements
+Finally, once we have added the marcato articulation to its @code{elements}
property, we can return @code{result-event-chord}, hence the last line of
the function.
* Markup construction in Scheme::
* How markups work internally::
* New markup command definition::
+* New markup list command definition::
@end menu
@end multitable
@end quotation
-The whole scheme language is accessible inside the
+The whole Scheme language is accessible inside the
@code{markup} macro. For example, You may use function calls inside
@code{markup} in order to manipulate character strings. This is
useful when defining new markup commands (see
@ref{New markup command definition}).
-@refbugs
+@knownissues
The markup-list argument of commands such as @code{#:line},
@code{#:center}, and @code{#:column} cannot be a variable or
@subsection New markup command definition
New markup commands can be defined
-with the @code{define-markup-command} scheme macro.
+with the @code{define-markup-command} Scheme macro.
@lisp
(define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
@item argi-type?
a type predicate for the i@var{th} argument
@item layout
-the `layout' definition
+the @q{layout} definition
@item props
a list of alists, containing all active properties.
@end table
Note: there is now an internal command @code{\smallCaps} which can
be used to set text in small caps. See
-@ref{Overview of text markup commands} for details.
+@ref{Text markup commands}, for details.
+
+@knownissues
+
+Currently, the available combinations of arguments (after the standard
+@var{layout} and @var{props} arguments) to a markup command defined with
+@code{define-markup-command} are limited as follows.
+
+@table @asis
+@item (no argument)
+@itemx @var{list}
+@itemx @var{markup}
+@itemx @var{markup markup}
+@itemx @var{scm}
+@itemx @var{scm markup}
+@itemx @var{scm scm}
+@itemx @var{scm scm markup}
+@itemx @var{scm markup markup}
+@itemx @var{scm scm scm}
+@end table
+
+@noindent
+In the above table, @var{scm} represents native Scheme data types like
+@q{number} or @q{string}.
+
+As an example, it is not possible to use a markup command @code{foo} with
+four arguments defined as
+
+@example
+#(define-markup-command (foo layout props
+ num1 str1 num2 str2)
+ (number? string? number? string?)
+ ...)
+@end example
+
+@noindent
+If you apply it as, say,
+
+@example
+\markup \foo #1 #"bar" #2 #"baz"
+@end example
+
+@cindex Scheme signature
+@cindex signature, Scheme
+@noindent
+@command{lilypond} complains that it cannot parse @code{foo} due to its
+unknown Scheme signature.
+@node New markup list command definition
+@subsection New markup list command definition
+Markup list commands are defined with the
+@code{define-markup-list-command} Scheme macro, which is similar to the
+@code{define-markup-command} macro described in
+@ref{New markup command definition}, except that where the latter returns
+a single stencil, the former returns a list stencils.
+
+In the following example, a @code{\paragraph} markup list command is
+defined, which returns a list of justified lines, the first one being
+indented. The indent width is taken from the @code{props} argument.
+@example
+#(define-markup-list-command (paragraph layout props args) (markup-list?)
+ (let ((indent (chain-assoc-get 'par-indent props 2)))
+ (interpret-markup-list layout props
+ (make-justified-lines-markup-list (cons (make-hspace-markup indent)
+ args)))))
+@end example
+
+Besides the usual @code{layout} and @code{props} arguments, the
+@code{paragraph} markup list command takes a markup list argument, named
+@code{args}. The predicate for markup lists is @code{markup-list?}.
+
+First, the function gets the indent width, a property here named
+@code{par-indent}, from the property list @code{props} If the property
+is not found, the default value is @code{2}. Then, a list of justified
+lines is made using the @code{make-justified-lines-markup-list}
+function, which is related to the @code{\justified-lines}
+built-in markup list command. An horizontal space is added at the
+beginning using the @code{make-hspace-markup} function. Finally, the
+markup list is interpreted using the @code{interpret-markup-list}
+function.
+
+This new markup list command can be used as follows:
+@example
+\markuplines @{
+ \paragraph @{
+ The art of music typography is called \italic @{(plate) engraving.@}
+ The term derives from the traditional process of music printing.
+ Just a few decades ago, sheet music was made by cutting and stamping
+ the music into a zinc or pewter plate in mirror image.
+ @}
+ \override-lines #'(par-indent . 4) \paragraph @{
+ The plate would be inked, the depressions caused by the cutting
+ and stamping would hold ink. An image was formed by pressing paper
+ to the plate. The stamping and cutting was completely done by
+ hand.
+ @}
+@}
+@end example
@node Contexts for programmers
@section Contexts for programmers
When interpreted, the function @var{proc} is called for every layout
object found in the context @var{context}, with the following
arguments:
-@itemize @bullet
+@itemize
@item the layout object itself,
@item the context where the layout object was created, and
@item the context where @code{\applyOutput} is processed.
In addition, the cause of the layout object, i.e., the music
expression or object that was responsible for creating it, is in the
object property @code{cause}. For example, for a note head, this is a
-@internalsref{NoteHead} event, and for a @internalsref{Stem} object,
-this is a @internalsref{NoteHead} object.
+@rinternals{NoteHead} event, and for a @rinternals{Stem} object,
+this is a @rinternals{NoteHead} object.
Here is a function to use for @code{\applyOutput}; it blanks
note-heads on the center-line:
@end example
-@node OLD STUFF
-@section OLD STUFF
-
-This stuff is slated for deletion or merger into the earlier sections.
-
-@menu
-* Extending music syntax::
-* Manipulating music expressions::
-* Using LilyPond syntax inside Scheme::
-@end menu
-
-
-@node Extending music syntax
-@subsection Extending music syntax
+@node Scheme procedures as properties
+@section Scheme procedures as properties
-@c TODO: rewrite example.
-@c The use of FUNC as example argument is rather confusing.
-
-The syntax of composite music expressions, like @code{\repeat},
-@code{\transpose}, and @code{\context} follows the general form of
+Properties (like thickness, direction, etc.) can be set at fixed values
+with \override, e.g.
@example
-\@code{keyword} @var{non-music-arguments} @var{music-arguments}
+\override Stem #'thickness = #2.0
@end example
-Such syntax can also be defined as user code. To do this it is
-necessary to create a @emph{music function}. This is a specially marked
-Scheme function. For example, the music function @code{\applyMusic} applies
-a user-defined function to a music expression. Its syntax is
+Properties can also be set to a Scheme procedure,
-@example
-\applyMusic #@var{func} @var{music}
-@end example
+@lilypond[fragment,verbatim,quote,relative=2]
+\override Stem #'thickness = #(lambda (grob)
+ (if (= UP (ly:grob-property grob 'direction))
+ 2.0
+ 7.0))
+c b a g b a g b
+@end lilypond
-A music function is created with @code{ly:make-music-function},
+@noindent
+In this case, the procedure is executed as soon as the value of the
+property is requested during the formatting process.
+
+Most of the typesetting engine is driven by such callbacks.
+Properties that typically use callbacks include
+
+@table @code
+@item stencil
+ The printing routine, that constructs a drawing for the symbol
+@item X-offset
+ The routine that sets the horizontal position
+@item X-extent
+ The routine that computes the width of an object
+@end table
-@example
-(ly:make-music-function
-@end example
+The procedure always takes a single argument, being the grob.
-@code{\applyMusic} takes a Scheme function and a Music expression as
-arguments. This is encoded in its parameter list,
+If routines with multiple arguments must be called, the current grob
+can be inserted with a grob closure. Here is a setting from
+@code{AccidentalSuggestion},
@example
-(list procedure? ly:music?)
+(X-offset .
+ ,(ly:make-simple-closure
+ `(,+
+ ,(ly:make-simple-closure
+ (list ly:self-alignment-interface::centered-on-x-parent))
+ ,(ly:make-simple-closure
+ (list ly:self-alignment-interface::x-aligned-on-self)))))
@end example
-The function itself takes another argument: an Input location
-object. That object is used to provide error messages with file names
-and line numbers. The definition is the second argument of
-@code{ly:make-music-function}. The body simply calls the function
-
-@example
-(lambda (where func music)
- (func music))
-@end example
+@noindent
+In this example, both @code{ly:self-alignment-interface::x-aligned-on-self} and
+@code{ly:self-alignment-interface::centered-on-x-parent} are called
+with the grob as argument. The results are added with the @code{+}
+function. To ensure that this addition is properly executed, the whole
+thing is enclosed in @code{ly:make-simple-closure}.
-The above Scheme code only defines the functionality. The tag
-@code{\applyMusic} is selected by defining
+In fact, using a single procedure as property value is equivalent to
@example
-applyMusic = #(ly:make-music-function
- (list procedure? ly:music?)
- (lambda (parser location func music)
- (func music)))
+(ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
@end example
-A @code{define-music-function} macro is introduced on top of
-@code{ly:make-music-function} to ease the definition of music
-functions:
-
-@example
-applyMusic = #(define-music-function (parser location func music)
- (procedure? ly:music?)
- (func music))
-@end example
+@noindent
+The inner @code{ly:make-simple-closure} supplies the grob as argument
+to @var{proc}, the outer ensures that result of the function is
+returned, rather than the @code{simple-closure} object.
-Examples of the use of @code{\applyMusic} are in the next section.
-@seealso
-@file{ly/@/music@/-functions@/-init@/.ly}.
+@node TODO moved into scheme
+@section TODO moved into scheme
+@menu
+* Using Scheme code instead of \tweak::
+* Difficult tweaks::
+@end menu
-@node Manipulating music expressions
-@subsection Manipulating music expressions
+@node Using Scheme code instead of \tweak
+@subsection Using Scheme code instead of @code{\tweak}
-Music objects and their properties can be accessed and manipulated
-directly through the @code{\applyMusic} mechanism.
-The syntax for @code{\applyMusic} is
+The main disadvantage of @code{\tweak} is its syntactical
+inflexibility. For example, the following produces a syntax error.
@example
-\applyMusic #@var{func} @var{music}
+F = \tweak #'font-size #-3 -\flageolet
+
+\relative c'' @{
+ c4^\F c4_\F
+@}
@end example
@noindent
-This means that the Scheme function @var{func} is called with
-@var{music} as its argument. The return value of @var{func} is the
-result of the entire expression. @var{func} may read and write music
-properties using the functions @code{ly:music-property} and
-@code{ly:music-set-property!}.
-
-An example is a function that reverses the order of elements in
-its argument,
-@lilypond[quote,verbatim,ragged-right]
-#(define (rev-music-1 m)
- (ly:music-set-property! m 'elements
- (reverse (ly:music-property m 'elements)))
- m)
-
-\applyMusic #rev-music-1 { c'4 d'4 }
-@end lilypond
+With other words, @code{\tweak} doesn't behave like an articulation
+regarding the syntax; in particular, it can't be attached with
+@code{^} and @code{_}.
-The use of such a function is very limited. The effect of this
-function is void when applied to an argument that does not have
-multiple children. The following function application has no effect
+Using Scheme, this problem can be circumvented. The route to the
+result is given in @ref{Adding articulation to notes (example)},
+especially how to use @code{\displayMusic} as a helping guide.
@example
-\applyMusic #rev-music-1 \grace @{ c4 d4 @}
+F = #(let ((m (make-music 'ArticulationEvent
+ 'articulation-type "flageolet")))
+ (set! (ly:music-property m 'tweaks)
+ (acons 'font-size -3
+ (ly:music-property m 'tweaks)))
+ m)
+
+\relative c'' @{
+ c4^\F c4_\F
+@}
@end example
@noindent
-In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which
-has no @code{elements}, only a single @code{element}. Every generally
-applicable function for @code{\applyMusic} must -- like music expressions
-themselves -- be recursive.
+Here, the @code{tweaks} properties of the flageolet object
+@code{m} (created with @code{make-music}) are extracted with
+@code{ly:music-property}, a new key-value pair to change the
+font size is prepended to the property list with the
+@code{acons} Scheme function, and the result is finally
+written back with @code{set!}. The last element of the
+@code{let} block is the return value, @code{m} itself.
-The following example is such a recursive function: It first extracts
-the @code{elements} of an expression, reverses them and puts them
-back. Then it recurses, both on @code{elements} and @code{element}
-children.
-@example
-#(define (reverse-music music)
- (let* ((elements (ly:music-property music 'elements))
- (child (ly:music-property music 'element))
- (reversed (reverse elements)))
- ; set children
- (ly:music-set-property! music 'elements reversed)
+@node Difficult tweaks
+@subsection Difficult tweaks
- ; recurse
- (if (ly:music? child) (reverse-music child))
- (map reverse-music reversed)
+There are a few classes of difficult adjustments.
- music))
-@end example
+@itemize
-A slightly more elaborate example is in
-@inputfileref{input/@/test,reverse@/-music@/.ly}.
-Some of the input syntax is also implemented as recursive music
-functions. For example, the syntax for polyphony
-@example
-<<a \\ b>>
-@end example
+@item
+One type of difficult adjustment is the appearance of spanner objects,
+such as slur and tie. Initially, only one of these objects is created,
+and they can be adjusted with the normal mechanism. However, in some
+cases the spanners cross line breaks. If this happens, these objects
+are cloned. A separate object is created for every system that it is
+in. These are clones of the original object and inherit all
+properties, including @code{\override}s.
+
+
+In other words, an @code{\override} always affects all pieces of a
+broken spanner. To change only one part of a spanner at a line break,
+it is necessary to hook into the formatting process. The
+@code{after-line-breaking} callback contains the Scheme procedure that
+is called after the line breaks have been determined, and layout
+objects have been split over different systems.
+
+In the following example, we define a procedure
+@code{my-callback}. This procedure
+
+@itemize
+@item
+determines if we have been split across line breaks
+@item
+if yes, retrieves all the split objects
+@item
+checks if we are the last of the split objects
+@item
+if yes, it sets @code{extra-offset}.
+@end itemize
-@noindent
-is actually implemented as a recursive function that replaces the
-above by the internal equivalent of
-@example
-<< \context Voice = "1" @{ \voiceOne a @}
- \context Voice = "2" @{ \voiceTwo b @} >>
-@end example
+This procedure is installed into @rinternals{Tie}, so the last part
+of the broken tie is translated up.
-Other applications of @code{\applyMusic} are writing out repeats
-automatically (@inputfileref{input/@/test,unfold@/-all@/-repeats@/.ly}),
-saving keystrokes (@inputfileref{input/@/test,music@/-box@/.ly}) and
-exporting LilyPond input to other formats
-@c no @inputfileref{} here
-(eg. @file{input/@/no@/-notation/@/to@/-xml@/.ly}).
+@lilypond[quote,verbatim,ragged-right]
+#(define (my-callback grob)
+ (let* (
+ ; have we been split?
+ (orig (ly:grob-original grob))
-@seealso
+ ; if yes, get the split pieces (our siblings)
+ (siblings (if (ly:grob? orig)
+ (ly:spanner-broken-into orig) '() )))
-@file{scm/@/music@/-functions@/.scm}, @file{scm/@/music@/-types@/.scm},
-@inputfileref{input/@/test,add@/-staccato@/.ly},
-@inputfileref{input/@/test,unfold@/-all@/-repeats@/.ly}, and
-@inputfileref{input/@/test,music@/-box@/.ly}.
+ (if (and (>= (length siblings) 2)
+ (eq? (car (last-pair siblings)) grob))
+ (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
+\relative c'' {
+ \override Tie #'after-line-breaking =
+ #my-callback
+ c1 ~ \break c2 ~ c
+}
+@end lilypond
-@node Using LilyPond syntax inside Scheme
-@subsection Using LilyPond syntax inside Scheme
+@noindent
+When applying this trick, the new @code{after-line-breaking} callback
+should also call the old one @code{after-line-breaking}, if there is
+one. For example, if using this with @code{Hairpin},
+@code{ly:hairpin::after-line-breaking} should also be called.
-Creating music expressions in Scheme can be tedious, as they are
-heavily nested and the resulting Scheme code is large. For some
-simple tasks this can be avoided by using common LilyPond syntax inside
-Scheme, with the dedicated @code{#@{ ... #@}} syntax.
-The following two expressions give equivalent music expressions:
-@example
-mynotes = @{ \override Stem #'thickness = #4
- @{ c'8 d' @} @}
+@item Some objects cannot be changed with @code{\override} for
+technical reasons. Examples of those are @code{NonMusicalPaperColumn}
+and @code{PaperColumn}. They can be changed with the
+@code{\overrideProperty} function, which works similar to @code{\once
+\override}, but uses a different syntax.
-#(define mynotes #@{ \override Stem #'thickness = #4
- @{ c'8 d' @} #@})
+@example
+\overrideProperty
+#"Score.NonMusicalPaperColumn" % Grob name
+#'line-break-system-details % Property name
+#'((next-padding . 20)) % Value
@end example
-The content of @code{#@{ ... #@}} is enclosed in an implicit @code{@{
-... @}} block, which is parsed. The resulting music expression, a
-@code{SequentialMusic} music object, is then returned and usable in Scheme.
-
-Arbitrary Scheme forms, including variables, can be used in @code{#@{ ... #@}}
-expressions with the @code{$} character (@code{$$} can be used to
-produce a single @code{$} character). This makes the creation of simple
-functions straightforward. In the following example, a function
-setting the TextScript's padding is defined:
+Note, however, that @code{\override}, applied to
+@code{NoteMusicalPaperColumn} and @code{PaperColumn}, still works as
+expected within @code{\context} blocks.
-@lilypond[quote,verbatim,ragged-right]
-#(use-modules (ice-9 optargs))
-#(define* (textpad padding #:optional once?)
- (ly:export ; this is necessary for using the expression
- ; directly inside a block
- (if once?
- #{ \once \override TextScript #'padding = #$padding #}
- #{ \override TextScript #'padding = #$padding #})))
-
- {
- c'^"1"
- #(textpad 3.0 #t) % only once
- c'^"2"
- c'^"3"
- #(textpad 5.0)
- c'^"4"
- c'^"5"
- }
-@end lilypond
-
-Here, the variable @code{padding} is a number; music expression
-variables may also be used in a similar fashion, as in the following
-example:
-
-@lilypond[quote,verbatim,ragged-right]
-#(define (with-padding padding)
- (lambda (music)
- #{ \override TextScript #'padding = #$padding
- $music
- \revert TextScript #'padding #}))
-
-{
- c'^"1"
- \applyMusic #(with-padding 3) { c'^"2" c'^"3" }
- c'^"4"
-}
-@end lilypond
+@end itemize
-The function created by @code{(with-padding 3)} adds @code{\override} and
-@code{\revert} statements around the music given as an argument, and returns
-this new expression. Thus, this example is equivalent to:
-@example
-@{
- c'^"1"
- @{ \override TextScript #'padding = #3
- @{ c'^"2" c'^"3"@}
- \revert TextScript #'padding
- @}
- c'^"4"
-@}
-@end example
projects / lilypond.git / blobdiff