@c UNUSED !! -*-texinfo-*-

@node Advanced concepts
@section Advanced concepts



To understand this concept, imagine that you are performing a piece of
music. When you are playing, you combine the symbols printed at a
certain point with contextual information. For example, without
knowing the current clef, and the accidentals in the last measure, it
would be impossible to determine the pitch of a note. In other words,
this information forms a context that helps you decipher a
score. LilyPond produces notation from music, so in effect, it does
the inverse of reading scores. Therefore, it also needs to keep track
of contextual information. This information is maintained in
``notation contexts.''  

****************

Although LilyPond was designed to produce standard music notation, its
architecture is flexible, and it is possible to manipulate the
translation from a @file{.ly} file to a PDF file in many ways. This
chapter discusses outlines the options for customization.

Before we can explain what is possible, it it is necessary to
understand the general architecture of LilyPond.  The following
diagram shows the different steps in producing a PDF file:

@verbatim

       Parsing    Interpretation  Formatting     
  
.ly file  ->  Music    ->   Notation  ->


  Formatting   Dumping   Titling   

    -> Typography -> .tex   ->   .pdf file

@end verbatim

@enumerate

@item @emph{Parsing} means reading a file, and translating letters and
  numbers into data structures.

@item The central data structure is the @emph{Music} expression. It is
the structure that stores music events (notes, chords, lyric
syllables, etc.)  and their combinations.

@item In order to print a piece music, separate events have to be
synchronized. For example, notes that sound together must be combined
horizontally, while syllables must be combined on a line. This happens
in the @emph{interpretating} step.

@item The result of @emph{interpreting} is  @emph{notation}, a
collection of layout objects.

@item The exact appearance of the layout objects is determined during
@emph{formatting}.  For example, in this step spacing and beam slopes
are determined.

@item After formatting, LilyPond dumps a @TeX{} file containing the
symbols and their offsets.

@item In a final step, titles are added to the music, resulting in a
PostScript, DVI or PDF file.

@end enumerate

This chapter discusses Steps@tie{}1. to@tie{}4. Step@tie{}5 is
discussed in @ref{Tuning output}, while Step@tie{}6 is discussed in
@ref{Invoking LilyPond}.

The diagram above shows how music typesetting has been split-up in
multiple subproblems. However, splitting up problems always produces
the new problem of putting together the subsolutions to these
subproblems. Therefore, we will start our advanced topics class with a
discussion of the programming language Scheme, which lubricates the
interactions between different modules of LilyPond.



@section Scheme in LilyPond
@node Scheme in LilyPond

LilyPond includes an interpreter for the programming language Scheme,
a member of the LISP family. This interpreter,
@uref{http://www.gnu.org/software/guile/,GUILE}, 
forms the basis of the 

****************************************************************

@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 automatically fill in these menus
@c before saving changes


@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.

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