+\version "2.1.22"
@c -*-texinfo-*-
@c Note:
@c
@chapter Technical manual
-When LilyPond is run, it reads an input file which is parsed. 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.
+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 =
+ \property
+
+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}.
+
+@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::
-* Scheme integration::
-* Music storage format::
-* Lexical details::
-* Output details::
+* Interpretation context::
+* Scheme integration::
+* Music storage format::
+* Lexical details::
+* Output details::
@end menu
@section Interpretation context
@menu
-* Creating contexts::
-* Default contexts::
-* Context properties::
-* Context evaluation::
-* Defining contexts::
-* Engravers and performers::
-* Defining new contexts::
+* Creating contexts::
+* Default contexts::
+* Context properties::
+* Context evaluation::
+* Defining contexts::
+* Changing contexts locally::
+* Engravers and performers::
+* Defining new contexts::
@end menu
@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 @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
@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
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
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,
but when a note is encountered, contexts are setup to accept that
-note. In this case, a @code{Thread},@code{Voice}, and @code{Staff}
+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{Thread}, @code{Voice}, and
+interpreted with the same @code{Voice}, and
@code{Staff} context, putting the notes on the same staff, in the same
voice.
@cindex properties, context
@example
-\property @var{contextname}.@var{propname} = @var{value}
+\set @var{contextname}.@var{propname} = @var{value}
@end example
@noindent
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{Voice} context,
+but you can force another context with the
@code{\property}-command. Hence the expressions
@example
-\property @var{contextname}.@var{propname} = @var{value}
+\set @var{contextname}.@var{propname} = @var{value}
@end example
@noindent
@example
\context @var{contextname}
-\property Current.@var{propname} = @var{value}
+\set Current.@var{propname} = @var{value}
@end example
@noindent
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
@refbugs
-The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
-the inverse of @code{\property \set}.
+The context @code{Current} is confusing.
@node Context evaluation
@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
variable, and apply to one @code{\translator} definition by
referencing that variable.
+@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 {
+ StaffSymbol \set #'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. Neither can it be used for @internalsref{Score} contexts.
+
+
@node Engravers and performers
@subsection Engravers and performers
@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}
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]
+@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
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}:
@end ifinfo
@menu
-* Inline Scheme::
-* Input variables and Scheme::
-* Scheme datatypes::
-* Assignments::
+* Inline Scheme::
+* Input variables and Scheme::
+* Scheme datatypes::
+* Assignments::
@end menu
@node Inline Scheme
@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
+ \set Staff.autoBeaming = ##f
@end example
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
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
@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.
+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
@table @code
@item Grob: short for `Graphical object'.
-@item Scheme_hash_table
+@item Scheme_hash_table
@item Music_iterator
-@item Molecule: Device-independent page output object,
-including dimensions.
+@item Stencil: Device-independent page output object,
+including dimensions.
@item Syllable_group
@}
@end example
-
+
@node Music storage format
@section Music storage format
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.
+manipulated using Scheme functions.
@menu
-* Music expressions::
-* Internal music representation::
-* Manipulating music expressions::
+* Music expressions::
+* Internal music representation::
+* Manipulating music expressions::
@end menu
@node Music expressions
@cindex music expressions
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
+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
@lilypond[fragment,verbatim,center,quote]
\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}
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. 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.
-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. @var{func} may read and write music
+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:
-@lilypond[verbatim,singleline]
+@lilypond[verbatim,raggedright]
#(define (rev-music-1 m)
- (ly:set-mus-property! 'elements (reverse
- (ly:get-mus-property mus 'elements)))
+ (ly:set-mus-property! m 'elements (reverse
+ (ly:get-mus-property m 'elements)))
m)
- \apply #rev-music-1 { c4 d4 }
+ \score { \notes \apply #rev-music-1 { c4 d4 } }
@end lilypond
The use of such a function is very limited. The effect of this
@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{\apply} must --like music expressions
-themselves-- be recursive.
+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.
; 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 b @} >
+ << \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
@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
@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@}
projects / lilypond.git / blobdiff