@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
@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 =
+ \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.
+
+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::
of type @var{contexttype} (with name @var{contextname} if specified).
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
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:
-@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.
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
\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
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
+music can be interpreted in a changed context by using the following syntax
@example
\with @{
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:
+The following example shows how a staff is created with bigger spaces,
+and without a @code{Clef_engraver}.
-@lilypond[relative=1,fragment]
+@lilypond[relative=1,fragment,verbatim]
<<
\new Staff { c4 es4 g2 }
\new Staff \with {
- StaffSymbol \set #'staff-space = #(magstep 1.5)
+ \override StaffSymbol #'staff-space = #(magstep 1.5)
fontSize = #1.5
\remove "Clef_engraver"
} {
@refbugs
-@code{\with} has no effect on contexts that already exist. Neither can
-it be used for @internalsref{Score} contexts.
+The command @code{\with} has no effect on contexts that already
+exist.
@node 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
@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 (e.g. notes
@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
@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 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 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.
-It may be accessed with @code{\applyoutput}.
-
-@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
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::
>>}. 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}
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' } >>
@item
`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},
+ 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
C++ object: Each music object is represented by a C++ object. For technical
reasons, different music objects may be represented by different C++
@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} is
+directly, through the @code{\apply} mechanism.
+The syntax for @code{\apply} is
@example
\apply #@var{func} @var{music}
@end example
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 expression. @var{func} may read and write music
-properties using the functions @code{ly:get-mus-property} and
-@code{ly:set-mus-property!}.
+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:
-@lilypond[verbatim,singleline]
+@lilypond[verbatim,raggedright]
#(define (rev-music-1 m)
- (ly:set-mus-property! m 'elements (reverse
- (ly:get-mus-property m 'elements)))
+ (ly:music-set-property! m 'elements (reverse
+ (ly:music-property m 'elements)))
m)
\score { \notes \apply #rev-music-1 { c4 d4 } }
@end lilypond
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
@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
@noindent
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}):
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