@c -*-texinfo-*-
@c Note:
@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 before saving changes


@node Internals
@chapter Internals


When translating the input to notation, there are number of distinct
phases.  We list them here:

@c todo: moved from refman. 

The purpose of LilyPond is explained informally by the term `music
typesetter'.  This is not a fully correct name: not only does the
program print musical symbols, it also makes aesthetic decisions.
Symbols and their placements are @emph{generated} from a high-level
musical description.  In other words, LilyPond would be best described
by `music compiler' or `music to notation compiler'.

LilyPond is linked to GUILE, GNU's Scheme library for extension
programming. The Scheme library provides the glue that holds together
the low-level routines and separate modules which are written in C++.

When lilypond is run to typeset sheet music, the following happens:
@itemize @bullet
@item GUILE Initialization: various scheme files are read
@item parsing: first standard @code{ly} initialization  files are read, and
then the user @file{ly} file is read.
@item interpretation: the music in the file is processed ``in playing
order'', i.e. the order that  you  use to read sheet music, or the
order in which notes are played. The result of this step is a typesetting
specification.

@item typesetting:
The typesetting specification is solved: positions and formatting is
calculated.

@item the visible results ("virtual ink") are written to the output file.
@end itemize

During these stages different types of data play the the main role:
during parsing, @strong{Music} objects are created.  During the
interpretation, @strong{contexts} are constructed, and with these
contexts a network of @strong{graphical objects} (``grobs'') is
created. These grobs contain unknown variables, and the network forms a
set of equations. After solving the equations and filling in these
variables, the printed output is written to an output file.

These threemanship of tasks (parsing, translating, typesetting) and
data-structures (music, context, graphical objects) permeates the entire
design of the program.



@table @b

@item Parsing:

The LY file is read, and converted to a list of @code{Scores}, which
each contain @code{Music} and paper/midi-definitions. Here @code{Music},
@code{Pitch} and @code{Duration}  objects are created.

@item Interpreting music
@cindex interpreting music

All music events are "read" in the same order as they would be played
(or read from paper). At every step of the interpretation, musical
events are delivered to
interpretation contexts,
@cindex engraver
which use them to build @code{Grob}s (or MIDI objects, for MIDI output).

In this stage @code{Music_iterators} do a traversal of the @code{Music}
structure. The music events thus encountered are reported to
@code{Translator}s, a set of objects that collectively form interpretation
contexts.


@item Prebreaking

@cindex prebreaking

At places where line breaks may occur, clefs and bars are prepared for
a possible line break. 

@item Preprocessing

@cindex preprocessing

In this stage, all information that is needed to determine line breaking
is computed. 

@item Break calculation:

The lines and horizontal positions of the columns are determined.

@item Breaking

Relations between all grobs are modified to reflect line breaks: When a
spanner, e.g. a slur, crosses a line-break, then the spanner is "broken
into pieces", for every line that the spanner is in, a copy of the grob
is made. A substitution process redirects all grob-reference so that
each spanner grob will only reference other grobs in the same line.

@item Outputting:

All vertical dimensions and spanning objects are computed, and all grobs
are output, line by line. The output is encoded in the form of
@code{Molecule}s

@end table

The data types that are mentioned here are all discussed in this
section.