@code{\score} block is interpreted in time order, the same order in
which we hear and play the music. During this phase, the interpretation
context holds the state for the current point within the music, for
-example
+example:
@itemize @bullet
@item What notes are playing at this point?
@cindex context selection
Contexts for a music expression can be selected manually, using the
-following music expression.
+following music expression:
@example
\context @var{contexttype} [= @var{contextname}] @var{musicexpr}
@noindent
This means that @var{musicexpr} should be interpreted within a context
of type @var{contexttype} (with name @var{contextname} if specified).
-If no such context exists, it will be created.
+If no such context exists, it will be created:
@lilypond[verbatim,singleline]
\score {
Second, contexts are created automatically to be able to interpret the
-music expressions. Consider the following example.
+music expressions. Consider the following example:
@lilypond[verbatim, singleline]
\score { \notes { c'4-( d' e'-) } }
@noindent
The sequential music is interpreted by the Score context initially,
but when a note is encountered, contexts are setup to accept that
-note. In this case, a Thread, Voice, and Staff context are created.
-The rest of the sequential music is also interpreted with the same
-Thread, Voice, and Staff context, putting the notes on the same staff,
-in the same voice.
+note. In this case, a @code{Thread}, @code{Voice}, and @code{Staff}
+context are created. The rest of the sequential music is also
+interpreted with the same @code{Thread}, @code{Voice}, and
+@code{Staff} context, putting the notes on the same staff, in the same
+voice.
@node Context properties
@subsection Context properties
If you do not wish to specify the name of the context in the
@code{\property}-expression itself, you can refer to the abstract context
name, @code{Current}. The @code{Current} context is the latest
-used context. This will typically mean the @internalsref{Thread}
-context, but you can force another context with the
+used context. This will typically mean the @internalsref{Thread} context,
+but you can force another context with the
@code{\property}-command. Hence the expressions
@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.
+current bar number on the standard output during the compile:
@example
\applycontext
Here @var{engravername} is a string, the name of an engraver in the
system. In the following example, the @code{Clef_engraver} is removed
from the Staff context. The result is a staff without a clef, where
-the central C is at its default position, the center line.
+the central C is at its default position, the center line:
@lilypond[verbatim,singleline]
\score {
note heads on a staff symbol.
@example
-\translator @code{
+\translator @{
\type "Engraver_group_engraver"
\name "SimpleStaff"
\alias "Staff"
\consists "Staff_symbol_engraver"
\consists "Note_head_engraver"
\consistsend "Axis_group_engraver"
-}@
+@}
@end example
@noindent
defining a Score context from scratch, in which case
@code{Score_engraver} must be used).
-The complete list of context modifiers is as follows:
+The complete list of context modifiers is the following:
@itemize @bullet
@item @code{\alias} @var{alternate-name}:
This specifies a different name. In the above example,
-@code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
+@code{\property Staff.X = Y} will also work on @code{SimpleStaff}s.
@item @code{\consistsend} @var{engravername}:
Analogous to @code{\consists}, but makes sure that
@item @code{\accepts} @var{contextname}:
This context can contains @var{contextname} contexts. The first
-@code{\accepts} is created as a default context when events (eg. notes
+@code{\accepts} is created as a default context when events (e.g. notes
or rests) are encountered.
@item @code{\denies}:
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
-@code{twice}
+@code{twice}:
@example
traLaLa = \notes @{ c'4 d'4 @}
@subsection Scheme datatypes
Scheme is used to glue together different program modules. To aid this
-glue function, many lilypond specific object types can be passed as
+glue function, many LilyPond specific object types can be passed as
Scheme value.
-The following list are all lilypond specific types, that
+The following list are all LilyPond specific types, that
can exist during parsing:
@table @code
@item Duration
-@item Identifier
@item Input
@item Moment
@item Music
+@item Event
+In C++ terms, an @code{Event} is a subtype of @code{Music}. However,
+both have different functions in the syntax.
@item Music_output_def
@item Pitch
@item Score
@item Spring_smob
-@item Translator: An object that produces audio objects or Grobs. This is
-not yet user-accessible.
+@item Translator: An object that produces audio objects or Grobs.
+It may be accessed with @code{\applyoutput}.
@item Font_metric: An object representing a font.
@end table
@section Music storage format
Music in LilyPond is entered as music expressions. This section
-discusses different types of music expressions, and explains
+discusses different types of music expressions, and explains how
information is stored internally. This internal storage is accessible
through the Scheme interpreter, so music expressions may be
manipulated using Scheme functions.
@cindex music expressions
Notes, rests, lyric syllables are music expressions. Small music
-expressions may be combined to form larger ones, for example by
+expressions may be combined to form larger ones, for example, by
enclosing a list of expressions in @code{\sequential @{ @}} or @code{<
>}. In the following example, a compound expression is formed out of
the quarter note @code{c} and a quarter note @code{d}:
@cindex @code{\simultaneous}
The two basic compound music expressions are simultaneous and
-sequential music.
+sequential music:
@example
\sequential @code{@{} @var{musicexprlist} @code{@}}
-Other compound music expressions include
+Other compound music expressions include:
@example
\repeat @var{expr}
\transpose @var{from} @var{to} @var{expr}
it takes up time. Time is a rational number that measures the length
of a piece of music, in whole notes.
-A music object has three kinds of types
+A music object has three kinds of types:
@itemize @bullet
@item
- Music name: each music expression has a name, for example, a note
+ 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 internals manual, under @internalsref{Music
expressions}.
@item
- Each music name has several `types' or interface. 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}.
+ `type' or interface: Each music name has several `types' or interface,
+ 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 internals manual, under
@internalsref{Music classes}.
@item
-Each music object is represented by a C++ object. For technical
+C++ object: Each music object is represented by a C++ object. For technical
reasons, different music objects may be represented by different C++
object types. For example, a note is @code{Event} object, while
@code{\grace} creates a @code{Grace_music} object.
note. A list of all properties available is in the internals manual,
under @internalsref{Music properties}.
-A compound music expresssion is a music object that contains other
+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'
-music object is stored in the @code{element} object. For example,
+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
@code{element}. The body of a repeat is in @code{element} property of
@subsection Manipulating music expressions
Music objects and their properties can be accessed and manipulated
-directly, through the @code{\apply} mechanism. Scheme functions can
-read and write properties using the functions
-@code{ly:get-music-property} and @code{ly:set-music-property!}.
-6
-The syntax for @code{\apply}
+directly, through the @code{\apply} mechanism.
+The syntax for @code{\apply} is
@example
\apply #@var{func} @var{music}
@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 expresssion.
+result of the entire expression. @var{func} may read and write music
+properties using the functions @code{ly:get-mus-property} and
+@code{ly:set-mus-property!}.
An example is a function that reverses the order of elements in
its argument:
-@example
+@lilypond[verbatim,singleline]
#(define (rev-music-1 m)
- (ly:set-music-property! 'elements (reverse
- (ly:get-music-property mus 'elements)))
- )
- \apply #rev-music-1 @{ c4 d4 @}
-@end example
+ (ly:set-mus-property! m 'elements (reverse
+ (ly:get-mus-property m 'elements)))
+ m)
+ \score { \notes \apply #rev-music-1 { c4 d4 } }
+@end lilypond
The use of such a function is very limited. The effect of this
-function is void, when it is applied to an argument which is does not
-have multiple children, for example
+function is void when applied to an argument which is does not have
+multiple children. The following function application has no effect:
@example
\apply #rev-music-1 \grace @{ c4 d4 @}
@end example
@noindent
-does not do anything: @code{\grace} is stored as
-@internalsref{GraceMusic}, which has no @code{elements}, only a single
-@code{element}. Every generally applicable function for @code{\apply}
-must --like music expressions themselves-- be recursive.
+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{\apply} must -- like music expressions
+themselves -- be recursive.
-The following example is such a recursive function: it first extracts
+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.
above by the internal equivalent of
@example
< \context Voice = "1" @{ \voiceOne a @}
- \context Voice = "2" @{ \voiceTwo a @} >
+ \context Voice = "2" @{ \voiceTwo b @} >
@end example
Other applications of @code{\apply} are writing out repeats
@file{scm/music-functions.scm}, @file{scm/music-types.scm},
@inputfileref{input/test,add-staccato.ly},
-@inputfileref{input/test,duration-check.ly}.
-@inputfileref{input/test,unfold-all-repeats.ly},
+@inputfileref{input/test,unfold-all-repeats.ly}, and
@inputfileref{input/test,music-box.ly}.
@node Lexical details
@section Lexical details
-@menu
-* Strings::
-@end menu
-@node Strings
-@subsection Strings
@cindex string
@cindex concatenate
@code{lastpagefill} in LilyPond's @code{\paper} block.
It is possible to fine-tune the vertical offset further by defining the
-macro @code{\lilypondscoreshift}. Example:
+macro @code{\lilypondscoreshift}:
@example
\def\lilypondscoreshift@{0.25\baselineskip@}
@end example
@noindent
-@code{\baselineskip} is the distance from one text line to the next.
+where @code{\baselineskip} is the distance from one text line to the next.
The code produced by LilyPond should be run through La@TeX{}, not
plain @TeX{}.
Here an example how to embed a small LilyPond file @code{foo.ly} into
running La@TeX{} text without using the @code{lilypond-book} script
-(@pxref{lilypond-book manual}).
+(@pxref{lilypond-book manual}):
@example
\documentclass@{article@}