-@c -*- coding: latin-1; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
@node Interfaces for programmers
@chapter Interfaces for programmers
* Internal music representation::
* Extending music syntax::
* Manipulating music expressions::
+* Displaying music expressions::
* Using LilyPond syntax inside Scheme::
@end menu
@subsection Input variables and Scheme
-The input format supports the notion of variable: in the following
+The input format supports the notion of variables: in the following
example, a music expression is assigned to a variable with the name
@code{traLaLa}.
@example
@end example
@c
In effect, each input file is a scope, and all @code{\header},
-@code{\midi} and @code{\layout} blocks are scopes nested inside that
+@code{\midi}, and @code{\layout} blocks are scopes nested inside that
toplevel scope.
Both variables and scoping are implemented in the GUILE module system.
This means that input variables and Scheme variables may be freely
mixed. In the following example, a music fragment is stored in the
variable @code{traLaLa}, and duplicated using Scheme. The result is
-imported in a @code{\score} by means of a second variable
+imported in a @code{\score} block by means of a second variable
@code{twice}:
@example
traLaLa = @{ c'4 d'4 @}
written as
@example
@dots{}
-@{ #(ly:export (make-sequential-music newLa)) @}
+@{ #(ly:export (make-sequential-music (list newLa))) @}
@end example
@refbugs
@item
`type' or interface: Each music name has several `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}.
+@code{note-event}, a @code{rhythmic-event}, and a @code{melodic-event}.
All classes of music are listed in the internals manual, under
@internalsref{Music classes}.
@node Extending music syntax
@subsection Extending music syntax
-The syntax of composite music expressions, like
-@code{\repeat}, @code{\transpose} and @code{\context}
-follows the general form of
+@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
@example
\@code{keyword} @var{non-music-arguments} @var{music-arguments}
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
+Scheme function. For example, the music function @code{\applyMusic} applies
a user-defined function to a music expression. Its syntax is
@example
-\applymusic #@var{func} @var{music}
+\applyMusic #@var{func} @var{music}
@end example
A music function is created with @code{ly:make-music-function},
(ly:make-music-function
@end example
-@code{\applymusic} takes a Scheme function and a Music expression as
-argument. This is encoded in its first argument,
+@code{\applyMusic} takes a Scheme function and a Music expression as
+arguments. This is encoded in its parameter list,
@example
(list procedure? ly:music?)
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 is function simply calls the
-function
+@code{ly:make-music-function}. The body simply calls the function
@example
(lambda (where func music)
@end example
The above Scheme code only defines the functionality. The tag
-@code{\applymusic} is selected by defining
+@code{\applyMusic} is selected by defining
@example
-applymusic = #(ly:make-music-function
+applyMusic = #(ly:make-music-function
(list procedure? ly:music?)
- (lambda (location func music)
+ (lambda (parser location func music)
(func music)))
@end example
functions:
@example
-applymusic = #(def-music-function (location func music)
+applyMusic = #(def-music-function (parser location func music)
(procedure? ly:music?)
(func music))
@end example
-Examples of the use of @code{\applymusic} are in the next section.
+Examples of the use of @code{\applyMusic} are in the next section.
@seealso
@file{ly/@/music@/-functions@/-init@/.ly}.
@subsection Manipulating music expressions
Music objects and their properties can be accessed and manipulated
-directly, through the @code{\applymusic} mechanism.
-The syntax for @code{\applymusic} is
+directly, through the @code{\applyMusic} mechanism.
+The syntax for @code{\applyMusic} is
@example
-\applymusic #@var{func} @var{music}
+\applyMusic #@var{func} @var{music}
@end example
@noindent
(reverse (ly:music-property m 'elements)))
m)
-\applymusic #rev-music-1 { c'4 d'4 }
+\applyMusic #rev-music-1 { c'4 d'4 }
@end lilypond
The use of such a function is very limited. The effect of this
-function is void when applied to an argument which is does not have
+function is void when applied to an argument that does not have
multiple children. The following function application has no effect
@example
-\applymusic #rev-music-1 \grace @{ c4 d4 @}
+\applyMusic #rev-music-1 \grace @{ c4 d4 @}
@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
+applicable function for @code{\applyMusic} must -- like music expressions
themselves -- be recursive.
The following example is such a recursive function: It first extracts
\context Voice = "2" @{ \voiceTwo b @} >>
@end example
-Other applications of @code{\applymusic} are writing out repeats
+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
-(@inputfileref{input/@/test,to@/-xml@/.ly})
+@c no @inputfileref{} here
+(eg. @file{input/@/no@/-notation/@/to@/-xml@/.ly}).
+
+@seealso
+
+@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}.
+
+
+@node Displaying music expressions
+@subsection Displaying music expressions
@cindex internal storage
@cindex @code{\displayMusic}
+@cindex @code{\displayLilyMusic}
+
When writing a music function, it is often instructive to inspect how
a music expression is stored internally. This can be done with the
music function @code{\displayMusic}.
-@seealso
+@example
+@{
+ \displayMusic @{ c'4\f @}
+@}
+@end example
-@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}.
+Conversely, displaying a music expression in LilyPond notation can be
+done using the music function @code{\displayLilyMusic}. For instance:
+@example
+@{
+ \displayLilyMusic \transpose c a, @{ c e g a bes @}
+@}
+@end example
+
+will display:
+
+@example
+@{ a, cis e fis g @}
+@end example
@node Using LilyPond syntax inside Scheme
@subsection Using LilyPond syntax inside Scheme
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, using LilyPond usual syntax inside
+simple tasks, this can be avoided, using common LilyPond syntax inside
Scheme, with the dedicated @code{#@{ ... #@}} syntax.
The following two expressions give equivalent music expressions:
Arbitrary Scheme forms, including variables, can be used in @code{#@{ ... #@}}
expressions with the @code{$} character (@code{$$} can be used to
-produce a single $ character). This makes the creation of simple
+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:
{
c'^"1"
- \applymusic #(with-padding 3) { c'^"2" c'^"3" }
+ \applyMusic #(with-padding 3) { c'^"2" c'^"3" }
c'^"4"
}
@end lilypond
@lilypond[quote,verbatim,raggedright]
withPadding =
- #(def-music-function (location padding music) (number? ly:music?)
+ #(def-music-function (parser location padding music) (number? ly:music?)
#{ \override TextScript #'padding = #$padding
$music
\revert TextScript #'padding #})
@node Markup programmer interface
@section Markup programmer interface
-Markups implemented as special Scheme functions. When applied with as
-arguments an output definition (@code{\layout} or @code{\paper}),
-and a list of properties and other arguments, produce a Stencil
-object.
+@c Please rewrite the second sentence; I don't understand its meaning. AS
+
+Markups are implemented as special Scheme functions. When applied
+with as arguments an output definition (@code{\layout} or
+@code{\paper}), and a list of properties and other arguments, produce
+a Stencil object.
@menu
* Markup construction in Scheme::
@noindent
is equivalent to:
@example
-\markup \column < @{ \bold \italic "hello" \raise #0.4 "world" @}
- \bigger @{ foo bar baz @} >
+\markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
+ \bigger \line @{ foo bar baz @} @}
@end example
@noindent
@quotation
@multitable @columnfractions .3 .3
@item @b{LilyPond} @tab @b{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{\variable} @tab @code{variable}
-@item @code{@{ ... @}} @tab @code{#:line ( ... )}
-@item @code{\center-align < ... >} @tab @code{#:center ( ... )}
+@item @code{\center-align @{ ... @}} @tab @code{#:center-align ( ... )}
@item @code{string} @tab @code{"string"}
@item @code{#scheme-arg} @tab @code{scheme-arg}
@end multitable
@end lisp
@noindent
-is invalid. One should use the @code{make-line-markup} (resp
-@code{make-center-markup}, @code{make-column-markup}) function
+is invalid. One should use the @code{make-line-markup} (resp.,
+@code{make-center-markup} or @code{make-column-markup}) function
instead,
@lisp
(markup (make-line-markup (fun-that-returns-markups)))
function. The markup expression is stored as
@example
-(list raise-markup 0.5 (list simple-markup 'latin1 "foo"))
+(list raise-markup 0.5 (list simple-markup "foo"))
@end example
-@noindent
-In this case, @code{latin1} is the input encoding, which is set with
-the @code{\encoding} command.
-
When the markup is converted to printable objects (Stencils), the
-raise markup is called as
+@code{raise-markup} function is called as
@example
(apply raise-markup
@var{the "foo" markup})
@end example
-The @code{raise-markup} first creates the stencil for the @code{foo}
-string, and then it raises that Stencil by 0.5 staff space. This is a
-rather simple example; more complex examples are in the rest of this
-section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
+The @code{raise-markup} function first creates the stencil for the
+@code{foo} string, and then it raises that Stencil by 0.5 staff space.
+This is a rather simple example; more complex examples are in the rest
+of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
@node Markup command definition
@subsection Markup command definition
To make the above available as @code{\smallcaps} command, we have to
define a function using @code{def-markup-command}. The command should
-take a single argument, of markup type. Therefore, the start of the
+take a single argument, of type markup. Therefore, the start of the
definition should read
@example
(def-markup-command (smallcaps layout props argument) (markup?)
@noindent
What follows is the content of the command: we should interpret
-the @code{argument} as a markup, i.e.
+the @code{argument} as a markup, i.e.,
@example
(interpret-markup layout @dots{} argument)
@noindent
The variable @code{props} is a list of alists, and we prepend to it by
-consing a list with the extra setting.
+cons'ing a list with the extra setting.
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 translated a
bit to the left and top. We will define a @code{\character} command
-that takes into account the needed translation, and uses the newly
+that takes into account the necessary translation, and uses the newly
defined @code{\smallcaps} command:
@example
"Print the character name in small caps, translated to the left and
top. Syntax: \\character #\"name\""
(interpret-markup layout props
- (markup "" #:translate (cons -3 1) #:smallcaps name)))
+ (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
@end example
There is one complication that needs explanation: texts above and below
the staff are moved vertically to be at a certain distance (the
@code{padding} property) from the staff and the notes. To make sure
that this mechanism does not annihilate the vertical effect of our
-@code{#:translate}, we add an empty string (@code{""}) before the
-translated text. Now the @code{""} will be put above the notes, and the
+@code{#:translate}, we add an empty string (@code{#:hspace 0}) before the
+translated text. Now the @code{#:hspace 0} will be put above the notes, and the
@code{name} is moved in relation to that empty string. The net effect is
that the text is moved to the upper left.
"Print the character name in small caps, translated to the left and
top. Syntax: \\character #\"name\""
(interpret-markup layout props
- (markup "" #:translate (cons -3 1) #:smallcaps name)))
+ (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
{
c''^\markup \character #"Cleopatra" c'' c'' c''
@end lilypond
We have used the @code{caps} font shape, but suppose that our font
-that 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
+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:
@example
@subsection Context evaluation
@cindex calling code during interpreting
-@cindex @code{\applycontext}
+@cindex @code{\applyContext}
Contexts can be modified during interpretation with Scheme code. The
syntax for this is
@example
-\applycontext @var{function}
+\applyContext @var{function}
@end example
@var{function} should be a Scheme function taking a single argument,
current bar number on the standard output during the compile:
@example
-\applycontext
+\applyContext
#(lambda (x)
(format #t "\nWe were called in barnumber ~a.\n"
(ly:context-property x 'currentBarNumber)))
@cindex calling code on layout objects
-@cindex @code{\applyoutput}
+@cindex @code{\applyOutput}
-The most versatile way of tuning an object is @code{\applyoutput}. Its
+The most versatile way of tuning an object is @code{\applyOutput}. Its
syntax is
@example
-\applyoutput @var{proc}
+\applyOutput @var{proc}
@end example
@noindent
@itemize @bullet
@item the layout object itself,
@item the context where the layout object was created, and
-@item the context where @code{\applyoutput} is processed.
+@item the context where @code{\applyOutput} is processed.
@end itemize
-In addition, the cause of the layout object, i.e. the music
+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.
-Here is a function to use for @code{\applyoutput}; it blanks
+Here is a function to use for @code{\applyOutput}; it blanks
note-heads on the center-line:
@example
projects / lilypond.git / blobdiff