@c
@c A menu is needed before every deeper *section nesting of @nodes
@c Run M-x texinfo-all-menus-update
-@c to automagically fill in these menus
+@c to automatically fill in these menus
@c before saving changes
-@node Advanced topics
-@chapter Advanced topics
+@node Technical manual
+@chapter Technical manual
+
+
+When LilyPond is run, it reads music from a file, translates that into
+notation, and outputs the result to a file. The most important steps
+are the first three. Consequently, there are three important basic
+concepts within LilyPond: music, translation and layout. The
+following diagram illustrates the concepts, and list the terminology
+associated with each step.
+
+
+@verbatim
+
+ +-------------+ Translation +----------+
+ | | | |
+ | Music | ------------------> | Layout |
+ | | | |
+ +-------------+ +----------+
+
+
+Syntax: c4 \context \set #'padding =
+ \override
+
+Objects: Music expressions Contexts Layout object
+ Engravers (aka. Grob)
+
+Example objects: NoteEvent Voice NoteHead
+ Note_heads_engraver
+
+Example properties: #'pitch keySignature #'line-count
+
+User applications: none various tuning layout
+
+@end verbatim
+
+The objects passed around in LilyPond have @emph{properties},
+variables that can contain many different types of information. Users
+can set these variables, to modify the default behavior. Since there
+are three different main concepts, there are also three types of
+properties:
+
+@cindex properties
+@cindex concepts, main
+@cindex context
+@cindex music expressions
+@cindex layout
+@cindex grob
+
+
+@table @b
+@item Music properties
+These are used internally, and most users will not see or use them.
+They use Scheme-style naming, i.e. lowercase words separated with
+dashes: @code{pitch}, @code{tremolo-type}.
-When LilyPond is run, it reads an input file. During parsing, Music
-objects are created. This music is interpreted, which is done by
-contexts, that produce graphical objects. This section discusses
-details of these three concepts, and how they are glued together with
-the embedded Scheme interpreter.
+@item Translation properties
+These influence the translation process, and most users will encounter them
+regularly. For example, beaming behavior is tuned with
+@code{autoBeamSettings}.
+
+These use mixed-caps naming: @code{autoBeamSettings},
+@code{ignoreMelismata}. They are assigned as follows:
+@example
+ \set ignoreMelismata = ...
+@end example
+
+@item Layout properties
+These are internally used in the formatting process. Consequently, to
+tune formatting details, it is necessary to adjust these
+properties. For example, some objects may be moved around vertically
+by setting their @code{padding} property.
+
+These properties use Scheme-style naming: @code{c0-position},
+@code{break-align-symbol}. They most often assigned as follows:
+
+@example
+ \override Score.RehearsalMark #'break-align-symbol = ...
+@end example
+
+@noindent
+Here, @code{RehearsalMark} is the type of the layout object.
+
+@end table
+
+This chapter discusses details of the three concepts in more detail,
+and explains how they are glued together in LilyPond with the embedded
+Scheme interpreter.
@menu
* Interpretation context::
@menu
* Creating contexts::
* Default contexts::
-* Context evaluation::
* Context properties::
+* Context evaluation::
+* Defining contexts::
+* Changing contexts locally::
* Engravers and performers::
-* Changing context definitions::
* Defining new contexts::
@end menu
Interpretation contexts are objects that only exist during program
run. During the interpretation phase (when @code{interpreting music}
-is interpreted to standard output), the music expression in a
+is printed on the standard output), the music expression in a
@code{\score} block is interpreted in time order, the same order in
-which hear and play the music. During this phase, the interpretation
-context holds the state for the current point within the music, for example
+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:
@itemize @bullet
@item What notes are playing at this point?
@cindex @code{\context}
@cindex context selection
-Contexts for a music expression can be selected manually, using the
-following music expression.
+Contexts for a music expression can be selected manually, using one of
+the following music expressions:
@example
+\new @var{contexttype} @var{musicexpr}
\context @var{contexttype} [= @var{contextname}] @var{musicexpr}
@end example
@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]
+@lilypond[verbatim,raggedright]
\score {
\notes \relative c'' {
- c4 <d4 \context Staff = "another" e4> f
+ c4 <<d4 \context Staff = "another" e4>> f
}
}
@end lilypond
@noindent
-In this example, the @code{c} and @code{d} are printed on the
-default staff. For the @code{e}, a context Staff called
-@code{another} is specified; since that does not exist, a new
-context is created. Within @code{another}, a (default) Voice context
-is created for the @code{e4}. When all music referring to a
-context is finished, the context is ended as well. So after the
-third quarter, @code{another} is removed.
+In this example, the @code{c} and @code{d} are printed on the default
+staff. For the @code{e}, a context @code{Staff} called @code{another}
+is specified; since that does not exist, a new context is created.
+Within @code{another}, a (default) Voice context is created for the
+@code{e4}. A context is ended when when all music referring it has
+finished, so after the third quarter, @code{another} is removed.
+
+The @code{\new} construction creates a context with a
+generated, unique @var{contextname}. An expression with
+@code{\new} always leads to a new context. This is convenient
+for creating multiple staffs, multiple lyric lines, etc.
+
+When using automatic staff changes, automatic phrasing, etc., the
+context names have special meanings, so @code{\new} cannot be
+used.
@node Default contexts
@subsection Default contexts
-Most music expressions do not need an explicit @code{\context}
-declaration: they inherit the notation context from their parent. In
+Every top level music is interpreted by the @code{Score} context; in
+other words, you may think of @code{\score} working like
+
+@example
+\score @{
+ \context Score @var{music}
+@}
+@end example
+
+Music expressions inherit their context from the enclosing music
+expression. Hence, it is not necessary to explicitly specify
+@code{\context} for most expressions. In
the following example, only the sequential expression has an explicit
context. The notes contained therein inherit the @code{goUp} context
from the enclosing music expression.
-@lilypond[verbatim,singleline]
+@lilypond[verbatim,raggedright]
\notes \context Voice = goUp { c'4 d' e' }
@end lilypond
-There are some quirks that you must keep in mind when dealing with
-defaults:
-
-First, every top level music is interpreted by the Score context; in other
-words, you may think of @code{\score} working like
-
-@example
-\score @{
- \context Score @var{music}
-@}
-@end example
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]
+@lilypond[verbatim,raggedright]
\score { \notes { c'4-( d' e'-) } }
@end lilypond
@noindent
-The sequential music is interpreted by the Score context initially
-(notice that the @code{\context} specification is redundant), 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.
-
-@node Context evaluation
-@subsection Context evaluation
-
-Scheme code can be used to modify contexts. The syntax for this is
-
-@example
- \applycontext @var{function}
-@end example
-
-@var{function} should be a Scheme function taking a single argument,
-being the context to apply it with. The following code will print the
-current bar number on the standard output during the compile.
-
-@example
- \applycontext
- #(lambda (x)
- (format #t "\nWe were called in barnumber ~a.\n"
- (ly:get-context-property x 'currentBarNumber)))
-@end example
-
+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 @code{Voice}, and @code{Staff}
+context are created. The rest of the sequential music is also
+interpreted with the same @code{Voice}, and
+@code{Staff} context, putting the notes on the same staff, in the same
+voice.
@node Context properties
@subsection Context properties
-
-Notation contexts have properties. These properties are from
-the @file{.ly} file using the following expression:
-@cindex @code{\property}
+Contexts have properties. These properties are set from the @file{.ly}
+file using the following expression:
@cindex context properties
@cindex properties, context
@example
-\property @var{contextname}.@var{propname} = @var{value}
+\set @var{contextname}.@var{propname} = @var{value}
@end example
@noindent
@internalsref{Voice} context can be set in the @internalsref{Score} context
(for example) and thus take effect in all @internalsref{Voice} contexts.
-@cindex @code{Current}
-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
-@code{\property}-command. Hence the expressions
-
-@example
-\property @var{contextname}.@var{propname} = @var{value}
-@end example
-
-@noindent
-and
-
-@example
-\context @var{contextname}
-\property Current.@var{propname} = @var{value}
-@end example
-
-@noindent
-do the same thing. The main use for this is in predefined variables.
-This construction allows the specification of a property-setting
-without restriction to a specific context.
-
Properties can be unset using the following statement.
@example
-\property @var{contextname}.@var{propname} \unset
+\unset @var{contextname}.@var{propname}
@end example
@cindex properties, unsetting
-@cindex @code{\unset}
+@cindex @code{\unset}
@noindent
This removes the definition of @var{propname} in @var{contextname}. If
@var{propname} was not defined in @var{contextname} (but was inherited
from a higher context), then this has no effect.
-@refbugs
+If @var{contextname} is left out, then it defaults to the current
+``bottom'' context: this is a context like @internalsref{Voice} that
+cannot contain any other contexts.
-The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
-the inverse of @code{\property \set}.
-@node Engravers and performers
-@subsection Engravers and performers
+@node Context evaluation
+@subsection Context evaluation
+
+Contexts can be modified during interpretation with Scheme code. The
+syntax for this is
+@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:
+
+@example
+ \applycontext
+ #(lambda (x)
+ (format #t "\nWe were called in barnumber ~a.\n"
+ (ly:context-property x 'currentBarNumber)))
+@end example
+
+
+
+@node Defining contexts
+@subsection Defining contexts
-@node Changing context definitions
-@subsection Changing context definitions
@cindex context definition
@cindex translator definition
-The most common way to define a context is by extending an existing
-context. You can change an existing context from the paper block by
-first initializing a translator with an existing context identifier:
+The most common way to create a new context definition is by extending
+an existing one. An existing context from the paper block is copied
+by referencing a context identifier:
@example
\paper @{
Every predefined context has a standard identifier. For example, the
@code{Staff} context can be referred to as @code{\StaffContext}.
-@noindent
The context can then be modified by setting or changing properties,
e.g.
@example
\translator @{
\StaffContext
- Stem \set #'thickness = #1.2
+ Stem \set #'thickness = #2.0
defaultBarType = #"||"
@}
@end example
-These assignments happen before interpretation starts, so a @code{\property}
+These assignments happen before interpretation starts, so a property
command will override any predefined settings.
@cindex engraver
variable, and apply to one @code{\translator} definition by
referencing that variable.
-@node Defining new contexts
-@subsection Defining new contexts
+@node Changing contexts locally
+@subsection Changing contexts locally
+
+
+Extending an existing context can also be done locally. A piece of
+music can be interpreted in a changed context by using the following syntax
+
+@example
+ \with @{
+ @var{context modifications}
+ @}
+@end example
+
+These statements comes between @code{\new} or @code{\context} and the
+music to be interpreted. The @var{context modifications} property
+settings and @code{\remove}, @code{\consists} and @code{\consistsend}
+commands. The syntax is similar to the @code{\translator} block.
+
+The following example shows how a staff is created with bigger spaces,
+and without a @code{Clef_engraver}.
+
+@lilypond[relative=1,fragment,verbatim]
+<<
+ \new Staff { c4 es4 g2 }
+ \new Staff \with {
+ \override StaffSymbol #'staff-space = #(magstep 1.5)
+ fontSize = #1.5
+ \remove "Clef_engraver"
+ } {
+ c4 es4 g2
+ } >>
+@end lilypond
+
+@refbugs
+
+The command @code{\with} has no effect on contexts that already
+exist.
+
+
+@node Engravers and performers
+@subsection Engravers and performers
-@cindex engraver
-@cindex plug-in
Each context is composed of a number of building blocks, or plug-ins
called engravers. An engraver is a specialized C++ class that is
objects, and the @code{Skip_event_swallow_translator} only swallows
(silently gobbles) @code{SkipEvent}s.
+
+
+@cindex engraver
+@cindex plug-in
+
An existing context definition can be changed by adding or removing an
-engraver. The syntax for these operations is
+engraver. The syntax for these operations is
@example
\consists @var{engravername}
\remove @var{engravername}
@end example
-@cindex \consists
-@cindex \remove
+@cindex @code{\consists}
+@cindex @code{\remove}
@noindent
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 middle C is at its default position, the center line:
-@lilypond[verbatim,singleline]
+@lilypond[verbatim,raggedright]
\score {
\notes {
c'4 f'4
@end lilypond
A list of all engravers is in the internal documentation,
-see @internalsref{All engravers}.
+see @internalsref{Engravers}.
+
+@node Defining new contexts
+@subsection Defining new contexts
+
It is also possible to define new contexts from scratch. To do this,
you must define give the new context a name. In the following
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{\set Staff.X = Y} will also work on @code{SimpleStaff}s.
@item @code{\consistsend} @var{engravername}:
Analogous to @code{\consists}, but makes sure that
Engravers that group context objects into axis groups or alignments
need to be at the end of the list. @code{\consistsend} insures that
engravers stay at the end even if a user adds or removes engravers.
-
+
@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}:
@cindex evaluating Scheme
@cindex LISP
-LilyPond internally uses GUILE, a Scheme-interpreter.
-
-
-Scheme is used to represent data throughout the whole program.
-
-In some places of the input file, Scheme expressions also form valid
-syntax: wherever it is allowed, GUILE can be accessed directly by
-entering a hash-sign (@code{#}). The expression following the
-hash-sign is evaluated as Scheme. For example, the boolean value @var{true} is
-@code{#t} in Scheme, so for LilyPond @var{true} looks like @code{##t},
-and can be used in property assignments:
-@example
- \property Staff.autoBeaming = ##f
-@end example
+LilyPond internally uses GUILE, a Scheme-interpreter, to represent
+data throughout the whole program, and glue together different program
+modules. For advanced usage, it is sometimes necessary to access and
+program the Scheme interpreter.
-Scheme is a full-blown programming language, from the LISP family. and
-a full discussion is outside the scope of this document. Interested
-readers are referred to the website @uref{http://www.schemers.org/}
-for more information on Scheme.
+Scheme is a full-blown programming language, from the LISP
+family. and a full discussion is outside the scope of this document.
+Interested readers are referred to the website
+@uref{http://www.schemers.org/} for more information on Scheme.
The GUILE library for extension is documented at
@uref{http://www.gnu.org/software/guile}.
@end ifinfo
@menu
+* Inline Scheme::
* Input variables and Scheme::
-* Scheme datatypes::
* Assignments::
@end menu
+@node Inline Scheme
+@subsection Inline Scheme
+
+Scheme expressions can be entered in the input file by entering a
+hash-sign (@code{#}). The expression following the hash-sign is
+evaluated as Scheme. For example, the boolean value @var{true} is
+@code{#t} in Scheme, so for LilyPond @var{true} looks like @code{##t},
+and can be used in property assignments:
+@example
+ \set Staff.autoBeaming = ##f
+@end example
+
+
@node Input variables and Scheme
@subsection Input variables and Scheme
There is also a form of scoping: in the following example, the
@code{\paper} block also contains a @code{traLaLa} variable, which is
-independent of the outer \traLaLa.
+independent of the outer @code{\traLaLa}.
@example
traLaLa = \notes @{ c'4 d'4 @}
\paper @{ traLaLa = 1.0 @}
toplevel scope.
Both variables and scoping are implemented in the GUILE module system.
-A anonymous Scheme module is attached to each scope. An assignment of
+An anonymous Scheme module is attached to each scope. An assignment of
the form
@example
- traLaLa = \notes @{ c'4 d'4 @}
+ traLaLa = \notes @{ c'4 d'4 @}
@end example
@noindent
is internally converted to a Scheme definition
@example
- (define traLaLa @var{Scheme value of @code{\notes ... }})
+ (define traLaLa @var{Scheme value of ``@code{\notes ... }''})
@end example
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
-@code{twice}
+@code{twice}:
@example
traLaLa = \notes @{ c'4 d'4 @}
-
+
#(define newLa (map ly:music-deep-copy
(list traLaLa traLaLa)))
#(define twice
-@node Scheme datatypes
-@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
-Scheme value.
-
-The following list are all lilypond specific types, that
-can exist during parsing:
-@itemize @bullet
-@item Duration
-@item Identifier
-@item Input
-@item Moment
-@item Music
-@item Music_output_def
-@item Pitch
-@item Score
-@item Translator_def
-@end itemize
-
-
-During a run, transient objects are also created and destroyed.
-
-@itemize @bullet
-@item Grob: short for `Graphical object'.
-@item Scheme_hash_table
-@item Music_iterator
-
-@item Molecule: Device-independent page output object,
-including dimensions.
-
-@item Syllable_group
-
-@item Spring_smob
-
-@item Translator: An object that produces audio objects or Grobs. This is
-not yet user-accessible.
-
-@item Font_metric: An object representing a font.
-@end itemize
-
-Many functions are defined to manipulate these data structures. They
-are all listed and documented in the internals manual, see
-@internalsref{All scheme functions}.
-
-
@node Assignments
@subsection Assignments
@cindex Assignments
-Identifiers allow objects to be assigned to names during the parse
-stage. To assign an identifier, use @var{name}@code{=}@var{value}.
-To refer to an identifier, precede its name with a backslash:
+Variables allow objects to be assigned to names during the parse
+stage. To assign a variable, use
+@example
+@var{name}@code{=}@var{value}
+@end example
+To refer to a variable, precede its name with a backslash:
`@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
-the input-types listed above. Identifier assignments can appear at top
+the input-types listed above. Variable assignments can appear at top
level in the LilyPond file, but also in @code{\paper} blocks.
-An identifier can be created with any string for its name, but you will
-only be able to refer to identifiers whose names begin with a letter,
-being entirely alphabetical. It is impossible to refer to an identifier
-whose name is the same as the name of a keyword.
-
-The right hand side of an identifier assignment is parsed completely
-before the assignment is done, so it is allowed to redefine an
-identifier in terms of its old value, e.g.
+A variable can be created with any string for its name, but for
+accessing it in the LilyPond syntax, its name must consist of
+alphabetic characters only, and may not be a keyword of the syntax.
+There are no restrictions for naming and accessing variables in the
+Scheme interpreter,
+The right hand side of a variable assignment is parsed completely
+before the assignment is done, so variables may be redefined in terms
+of its old value, e.g.
+@c
@example
foo = \foo * 2.0
@end example
-When an identifier is referenced, the information it points to is
-copied. For this reason, an identifier reference must always be the
-first item in a block.
+When a variable is referenced in LilyPond syntax, the information it
+points to is copied. For this reason, a variable reference must
+always be the first item in a block.
@example
\paper @{
@}
@end example
-
+
@node Music storage format
@section Music storage format
+Music in LilyPond is entered as music expressions. This section
+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.
+
@menu
* Music expressions::
* Internal music representation::
@subsection Music expressions
@cindex music expressions
-Music in LilyPond is entered as a music expression. Notes, rests, lyric
-syllables are music expressions, and you can combine music expressions
-to form new 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}:
+Notes, rests, lyric syllables are music expressions. Small music
+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}:
-@example
-\sequential @{ c4 d4 @}
-@end example
+@example
+\sequential @{ c4 d4 @}
+@end example
@cindex Sequential music
@cindex @code{\sequential}
@cindex sequential music
-@cindex @code{<}
-@cindex @code{>}
+@cindex @code{<<}
+@cindex @code{>>}
@cindex Simultaneous music
@cindex @code{\simultaneous}
The two basic compound music expressions are simultaneous and
-sequential music.
+sequential music:
@example
\sequential @code{@{} @var{musicexprlist} @code{@}}
for sequential and
@example
-@code{<} @var{musicexprlist} @code{>}
+@code{<<} @var{musicexprlist} @code{>>}
@end example
@noindent
produce music is not relevant. In the following example, three chords
are expressed in two different ways:
-@lilypond[fragment,verbatim,center,quote]
+@lilypond[fragment,verbatim,center]
\notes \context Voice {
- <a c'> <b d'> <c' e'>
- < { a b c' } { c' d' e' } >
+ <<a c'>> <<b d'>> <<c' e'>>
+ << { a b c' } { c' d' e' } >>
}
@end lilypond
-However, using @code{<} and @code{>} for entering chords leads to
+However, using @code{<<} and @code{>>} for entering chords leads to
various peculiarities. For this reason, a special syntax
-for chords was introduced in version 1.7: @code{<< >>}.
+for chords was introduced in version 1.7: @code{< >}.
-Other compound music expressions include
+Other compound music expressions include:
@example
\repeat @var{expr}
\transpose @var{from} @var{to} @var{expr}
-@node Manipulating music expressions
-@subsection Manipulating music expressions
-
When a music expression is parsed, it is converted into a set of
Scheme music objects. The defining property of a music object is that
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}.
+ @internalsref{Music classes}.
@item
-Each music object is represented by a C++ object. may be represented
-by different C++ classes. 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.
-
- The distinctions between different C++ types will disappear in the
-future.
+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.
+
+We expect that distinctions between different C++ types will disappear
+in the future.
@end itemize
The actual information of a music expression is stored in properties.
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
@internalsref{RepeatedMusic}, and the alternatives in @code{elements}.
-These properties and objects can be directly accessed and manipulated,
-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!}.
+@node Manipulating music expressions
+@subsection Manipulating music expressions
-The syntax for @code{\apply}
+Music objects and their properties can be accessed and manipulated
+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:music-property} and
+@code{ly:music-set-property!}.
An example is a function that reverses the order of elements in
its argument:
-@example
+@lilypond[verbatim,raggedright]
#(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:music-set-property! m 'elements (reverse
+ (ly:music-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.
@example
#(define (reverse-music music)
- (let* ((elements (ly:get-mus-property music 'elements))
- (child (ly:get-mus-property music 'element))
+ (let* ((elements (ly:music-property music 'elements))
+ (child (ly:music-property music 'element))
(reversed (reverse elements)))
; set children
- (ly:set-mus-property! music 'elements reversed)
+ (ly:music-set-property! music 'elements reversed)
; recurse
(if (ly:music? child) (reverse-music child))
(map reverse-music reversed)
-
+
music))
@end example
Some of the input syntax is also implemented as recursive music
functions. For example, the syntax for polyphony
@example
- < a \\ b>
+ <<a \\ b>>
@end example
@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 a @} >
+ << \context Voice = "1" @{ \voiceOne 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
-Begins and ends with the @code{"} character. To include a @code{"}
-character in a string write @code{\"}. Various other backslash
-sequences have special interpretations as in the C language. A string
-that contains no spaces can be written without the quotes. Strings can
-be concatenated with the @code{+} operator.
-
+By enclosing text in quotes (@code{"}), strings are formed. To
+include a @code{"} character in a string write @code{\"}. Various
+other backslash sequences have special interpretations as in the C
+language. A string that does not contain spaces or special characters
+can be written without the quotes. The exact form of such unquoted
+strings depends on the input mode; there are different rules for
+lyrics, notes and markups. Strings can be concatenated with the
+@code{+} operator.
@node Output details
@section Output details
-LilyPond's default output format is @TeX{}. Using the option @option{-f}
+The default output format is La@TeX{}, which should be run
+through La@TeX{}. Using the option @option{-f}
(or @option{--format}) other output formats can be selected also, but
-currently none of them reliably work.
-
-At the beginning of the output file, various global parameters are defined.
-It also contains a large @code{\special} call to define PostScript routines
-to draw items not representable with @TeX{}, mainly slurs and ties. A DVI
-driver must be able to understand such embedded PostScript, or the output
-will be rendered incompletely.
+currently none of them work reliably.
-Then the file @file{lilyponddefs.tex} is loaded to define the macros used
-in the code which follows. @file{lilyponddefs.tex} includes various other
-files, partially depending on the global parameters.
+At the beginning of the output file, various global parameters are
+defined. Then the file @file{lilyponddefs.tex} is loaded to define
+the macros used in the code which follows. @file{lilyponddefs.tex}
+includes various other files, partially depending on the global
+parameters.
Now the music is output system by system (a `system' consists of all
staves belonging together). From @TeX{}'s point of view, a system is an
The horizontal dimension of the @code{\hbox} is given by the
@code{linewidth} parameter from LilyPond's @code{\paper} block.
-
After the last system LilyPond emits a stronger variant of
@code{\interscoreline} only if the macro
@code{\lilypondpaperlastpagefill} is not defined (flushing the systems
@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.
-
-The code produced by LilyPond should be run through La@TeX{}, not
-plain @TeX{}.
+where @code{\baselineskip} is the distance from one text line to the next.
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@}
The file @file{foo.tex} has been simply produced with
@example
-lilypond foo.ly
+ lilypond-bin foo.ly
@end example
-It is important to set the @code{indent} parameter to zero in the
-@code{\paper} block of @file{foo.ly}.
-
The call to @code{\lineskip} assures that there is enough vertical space
between the LilyPond box and the surrounding text lines.
projects / lilypond.git / blobdiff