@node Overview of music functions
@subsection Overview of music functions
-Making a function which substitutes a variable into LilyPond
+Making a function that substitutes a variable into LilyPond
code is easy. The general form of these functions is
@example
variables as @code{#$var1}, etc.
@end multitable
-There following input types may be used as variables
-in a music function. This list is not exhaustive; see
-other documentation specifically about Scheme for more
-variable types.
+The following input types may be used as variables in a music
+function. This list is not exhaustive; see other documentation
+specifically about Scheme for more variable types.
@multitable @columnfractions .33 .66
@headitem Input type @tab @var{vari-type?} notation
@subsection Void functions
A music function must return a music expression, but sometimes we
-may want to have a function which does not involve music (such as
+may want to have a function that does not involve music (such as
turning off Point and Click). To do this, we return a @code{void}
music expression.
@subsection Functions without arguments
In most cases a function without arguments should be written
-with an variable,
+with a variable,
@example
dolce = \markup@{ \italic \bold dolce @}
@c Due to parser lookahead
-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.
+In this example, the assignment happens after the 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
The actual information of a music expression is stored in properties.
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 @rinternals{Music properties}.
+note. A list of all properties available can be found in the
+Internals Reference, 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
(ly:make-pitch 0 0 0)
@end example
-The note pitch can be changed by setting this 'pitch property,
+The note pitch can be changed by setting this @code{'pitch} property,
@funindex \displayLilyMusic
@node Doubling a note with slurs (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
-by examining the internal representation of the music
-we want to end up with.
+Suppose we want to create a function that translates input like
+@code{a} into @code{a( a)}. We begin by examining the internal
+representation of the desired result.
@example
\displayMusic@{ a'( a') @}
The easy way to add articulation to notes is to merge two music
expressions into one context, as explained in
@ref{Creating contexts}. However, suppose that we want to write
-a music function which does this.
+a music function that does this.
A @code{$variable} inside the @code{#@{...#@}} notation is like
-using a regular @code{\variable} in classical LilyPond
-notation. We know that
+a regular @code{\variable} in classical LilyPond notation. We
+know that
@example
@{ \music -. -> @}
used elsewhere.
Now we have a @code{result-event-chord}, which is a
-@code{NoteEventChord} expression and is a copy of @code{event-chord}. We
-add the marcato to its elements list property.
+@code{NoteEventChord} expression and is a copy of
+@code{event-chord}. We add the marcato to its @code{'elements}
+list property.
@example
(set! place new-value)
@end example
-Here, what we want to set (the @q{place}) is the @q{elements} property of
-@code{result-event-chord} expression.
+Here, what we want to set (the @q{place}) is the @code{'elements}
+property of @code{result-event-chord} expression.
@example
(ly:music-property result-event-chord 'elements)
@code{ly:music-property} is the function used to access music properties
(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
+former @code{'elements} property, with an extra item: the
@code{ArticulationEvent} expression, which we copy from the
@code{\displayMusic} output,
(ly:music-property result-event-chord 'elements))
@end example
-@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.
+@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 @code{'elements} property is not important here.
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
@section Markup programmer interface
Markups are implemented as special Scheme functions which produce a
-Stencil object given a number of arguments.
+@code{Stencil} object given a number of arguments.
@menu
* Markup construction in Scheme::
@item @code{\markup markup1} @tab @code{(markup markup1)}
@item @code{\markup @{ markup1 markup2 ... @}} @tab
@code{(markup markup1 markup2 ... )}
-@item @code{\command} @tab @code{#:command}
+@item @code{\markup-command} @tab @code{#:markup-command}
@item @code{\variable} @tab @code{variable}
@item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
@item @code{string} @tab @code{"string"}
Suppose that we are typesetting a recitative in an opera and
we would like to define a command that will show character names in a
custom manner. Names should be printed with small caps and moved a
-bit to the left and top. We will define a @code{\character} command
+bit up and to the left. We will define a @code{\character} command
which takes into account the necessary translation and uses the newly
defined @code{\smallcaps} command:
We have used the @code{caps} font shape, but suppose that our font
does not have a small-caps variant. In that case we have to fake
-the small caps font by setting a string in upcase with the first
-letter a little larger:
+the small caps font by setting a string in uppercase with the
+first letter a little larger:
@example
#(define-markup-command (smallcaps layout props str) (string?)
@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.
+a single stencil, the former returns a list of stencils.
In the following example, a @code{\paragraph} markup list command is
defined, which returns a list of justified lines, the first one being
@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.
+@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. A
+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
\applyContext @var{function}
@end example
-@var{function} should be a Scheme function taking a single argument,
-being the context to apply it to. The following code will print the
-current bar number on the standard output during the compile:
+@var{function} should be a Scheme function that takes a single
+argument: the context in which the @code{\applyContext} command is
+being called. The following code will print the current bar
+number on the standard output during the compile:
@example
\applyContext
@node Scheme procedures as properties
@section Scheme procedures as properties
-Properties (like thickness, direction, etc.) can be set at fixed values
-with \override, e.g.
+Properties (like @code{thickness}, @code{direction}, etc.) can be
+set at fixed values with @code{\override}, e.g.
@example
\override Stem #'thickness = #2.0
@end example
@noindent
-With other words, @code{\tweak} doesn't behave like an articulation
+In other words, @code{\tweak} doesn't behave like an articulation
regarding the syntax; in particular, it can't be attached with
@code{^} and @code{_}.
-Using Scheme, this problem can be circumvented. The route to the
+Using Scheme, this problem can be avoided. The route to the
result is given in @ref{Adding articulation to notes (example)},
especially how to use @code{\displayMusic} as a helping guide.
@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
+One type of difficult adjustment involves the appearance of
+spanner objects, such as slurs and ties. Usually, only one
+spanner object is created at a time, and it can be adjusted with
+the normal mechanism. However, occasionally a spanner crosses a
+line break. When this happens, the object is cloned. A separate
+object is created for every system in which the spanner appears.
+The new objects are clones of the original object and inherit all
properties, including @code{\override}s.
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
+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
@itemize
@item
-determines if we have been split across line breaks
+determines if the spanner has been split across line breaks
@item
if yes, retrieves all the split objects
@item
-checks if we are the last of the split objects
+checks if this grob is the last of the split objects
@item
if yes, it sets @code{extra-offset}.
@end itemize
This procedure is installed into @rinternals{Tie}, so the last part
-of the broken tie is translated up.
+of the broken tie is repositioned.
@lilypond[quote,verbatim,ragged-right]
#(define (my-callback grob)
projects / lilypond.git / blobdiff