1 @c UNUSED !! -*-texinfo-*-
3 @node Advanced concepts
4 @section Advanced concepts
8 To understand this concept, imagine that you are performing a piece of
9 music. When you are playing, you combine the symbols printed at a
10 certain point with contextual information. For example, without
11 knowing the current clef, and the accidentals in the last measure, it
12 would be impossible to determine the pitch of a note. In other words,
13 this information forms a context that helps you decipher a
14 score. LilyPond produces notation from music, so in effect, it does
15 the inverse of reading scores. Therefore, it also needs to keep track
16 of contextual information. This information is maintained in
17 ``notation contexts.''
21 Although LilyPond was designed to produce standard music notation, its
22 architecture is flexible, and it is possible to manipulate the
23 translation from a @file{.ly} file to a PDF file in many ways. This
24 chapter discusses outlines the options for customization.
26 Before we can explain what is possible, it it is necessary to
27 understand the general architecture of LilyPond. The following
28 diagram shows the different steps in producing a PDF file:
32 Parsing Interpretation Formatting
34 .ly file -> Music -> Notation ->
37 Formatting Dumping Titling
39 -> Typography -> .tex -> .pdf file
45 @item @emph{Parsing} means reading a file, and translating letters and
46 numbers into data structures.
48 @item The central data structure is the @emph{Music} expression. It is
49 the structure that stores music events (notes, chords, lyric
50 syllables, etc.) and their combinations.
52 @item In order to print a piece music, separate events have to be
53 synchronized. For example, notes that sound together must be combined
54 horizontally, while syllables must be combined on a line. This happens
55 in the @emph{interpretating} step.
57 @item The result of @emph{interpreting} is @emph{notation}, a
58 collection of layout objects.
60 @item The exact appearance of the layout objects is determined during
61 @emph{formatting}. For example, in this step spacing and beam slopes
64 @item After formatting, LilyPond dumps a @TeX{} file containing the
65 symbols and their offsets.
67 @item In a final step, titles are added to the music, resulting in a
68 PostScript, DVI or PDF file.
72 This chapter discusses Steps@tie{}1. to@tie{}4. Step@tie{}5 is
73 discussed in @ref{Tuning output}, while Step@tie{}6 is discussed in
74 @ref{Invoking LilyPond}.
76 The diagram above shows how music typesetting has been split-up in
77 multiple subproblems. However, splitting up problems always produces
78 the new problem of putting together the subsolutions to these
79 subproblems. Therefore, we will start our advanced topics class with a
80 discussion of the programming language Scheme, which lubricates the
81 interactions between different modules of LilyPond.
85 @section Scheme in LilyPond
86 @node Scheme in LilyPond
88 LilyPond includes an interpreter for the programming language Scheme,
89 a member of the LISP family. This interpreter,
90 @uref{GUILE,http://www.gnu.org/software/guile/},
91 forms the basis of the
93 ****************************************************************
98 @c A menu is needed before every deeper *section nesting of @nodes
99 @c Run M-x texinfo-all-menus-update
100 @c to automatically fill in these menus
101 @c before saving changes
104 @node Technical manual
105 @chapter Technical manual
108 When LilyPond is run, it reads music from a file, translates that into
109 notation, and outputs the result to a file. The most important steps
110 are the first three. Consequently, there are three important basic
111 concepts within LilyPond: music, translation and layout. The
112 following diagram illustrates the concepts, and list the terminology
113 associated with each step.
118 +-------------+ Translation +----------+
120 | Music | ------------------> | Layout |
122 +-------------+ +----------+
125 Syntax: c4 \context \set #'padding =
128 Objects: Music expressions Contexts Layout object
129 Engravers (aka. Grob)
131 Example objects: NoteEvent Voice NoteHead
134 Example properties: #'pitch keySignature #'line-count
136 User applications: none various tuning layout
140 The objects passed around in LilyPond have @emph{properties},
141 variables that can contain many different types of information. Users
142 can set these variables, to modify the default behavior. Since there
143 are three different main concepts, there are also three types of
147 @cindex concepts, main
149 @cindex music expressions
155 @item Music properties
156 These are used internally, and most users will not see or use them.
158 They use Scheme-style naming, i.e. lowercase words separated with
159 dashes: @code{pitch}, @code{tremolo-type}.
161 @item Translation properties
162 These influence the translation process, and most users will encounter them
163 regularly. For example, beaming behavior is tuned with
164 @code{autoBeamSettings}.
166 These use mixed-caps naming: @code{autoBeamSettings},
167 @code{ignoreMelismata}. They are assigned as follows:
169 \set ignoreMelismata = ...
172 @item Layout properties
173 These are internally used in the formatting process. Consequently, to
174 tune formatting details, it is necessary to adjust these
175 properties. For example, some objects may be moved around vertically
176 by setting their @code{padding} property.
178 These properties use Scheme-style naming: @code{c0-position},
179 @code{break-align-symbol}. They most often assigned as follows:
182 \override Score.RehearsalMark #'break-align-symbol = ...
186 Here, @code{RehearsalMark} is the type of the layout object.