@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}.
+
+@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.
-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.
+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::
* 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 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{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
Contexts have properties. These properties are set from the @file{.ly}
file using the following expression:
-@cindex @code{\property}
@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 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
#(lambda (x)
(format #t "\nWe were called in barnumber ~a.\n"
- (ly:get-context-property x 'currentBarNumber)))
+ (ly:context-property x 'currentBarNumber)))
@end example
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 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 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
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}:
@menu
* Inline Scheme::
* Input variables and Scheme::
-* Scheme datatypes::
* Assignments::
@end menu
@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
-@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:
-@table @code
-@item Duration
-@item Identifier
-@item Input
-@item Moment
-@item Music
-@item Music_output_def
-@item Pitch
-@item Score
-@item Translator_def
-@end table
-
-
-During a run, transient objects are also created and destroyed.
-
-@table @code
-@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 table
-
-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
@end example
When a variable is referenced in LilyPond syntax, the information it
-points to is copied. For this reason, an variable reference must
+points to is copied. For this reason, a variable reference must
always be the first item in a block.
@example
@}
@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
+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::
@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
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}
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. 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: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 work reliably.
-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.
-
-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