Documentation/user/advanced.itely

   1 @c UNUSED !! -*-texinfo-*-
   2
   3 @node Advanced concepts
   4 @section Advanced concepts
   5
   6
   7
   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.''
  18
  19 ****************
  20
  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.
  25
  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:
  29
  30 @verbatim
  31
  32        Parsing    Interpretation  Formatting
  33
  34 .ly file  ->  Music    ->   Notation  ->
  35
  36
  37   Formatting   Dumping   Titling
  38
  39     -> Typography -> .tex   ->   .pdf file
  40
  41 @end verbatim
  42
  43 @enumerate
  44
  45 @item @emph{Parsing} means reading a file, and translating letters and
  46   numbers into data structures.
  47
  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.
  51
  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.
  56
  57 @item The result of @emph{interpreting} is  @emph{notation}, a
  58 collection of layout objects.
  59
  60 @item The exact appearance of the layout objects is determined during
  61 @emph{formatting}.  For example, in this step spacing and beam slopes
  62 are determined.
  63
  64 @item After formatting, LilyPond dumps a @TeX{} file containing the
  65 symbols and their offsets.
  66
  67 @item In a final step, titles are added to the music, resulting in a
  68 PostScript, DVI or PDF file.
  69
  70 @end enumerate
  71
  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}.
  75
  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.
  82
  83
  84
  85 @section Scheme in LilyPond
  86 @node Scheme in LilyPond
  87
  88 LilyPond includes an interpreter for the programming language Scheme,
  89 a member of the LISP family. This interpreter,
  90 @uref{http://www.gnu.org/software/guile/,GUILE},
  91 forms the basis of the
  92
  93 ****************************************************************
  94
  95 @c -*-texinfo-*-
  96 @c Note:
  97 @c
  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
 102
 103
 104 @node Technical manual
 105 @chapter Technical manual
 106
 107
 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.
 114
 115
 116 @verbatim
 117
 118                   +-------------+         Translation      +----------+
 119                   |             |                          |          |
 120                   |    Music    |     ------------------>  | Layout   |
 121                   |             |                          |          |
 122                   +-------------+                          +----------+
 123
 124
 125 Syntax:            c4                     \context           \set #'padding =
 126                                           \override
 127
 128 Objects:           Music expressions     Contexts            Layout object
 129                                          Engravers           (aka. Grob)
 130
 131 Example objects:   NoteEvent             Voice               NoteHead
 132                                          Note_heads_engraver
 133
 134 Example properties: #'pitch              keySignature        #'line-count
 135
 136 User applications: none                  various             tuning layout
 137
 138 @end verbatim
 139
 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
 144 properties:
 145
 146 @cindex properties
 147 @cindex concepts, main
 148 @cindex context
 149 @cindex music expressions
 150 @cindex layout
 151 @cindex grob
 152
 153
 154 @table @b
 155 @item Music properties
 156 These are used internally, and most users will not see or use them.
 157
 158 They use Scheme-style naming, i.e.  lowercase words separated with
 159 dashes: @code{pitch}, @code{tremolo-type}.
 160
 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}.
 165
 166 These use mixed-caps naming: @code{autoBeamSettings},
 167 @code{ignoreMelismata}. They are assigned as follows:
 168 @example
 169   \set ignoreMelismata = ...
 170 @end example
 171
 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.
 177
 178 These properties use Scheme-style naming: @code{c0-position},
 179 @code{break-align-symbol}. They most often assigned as follows:
 180
 181 @example
 182   \override Score.RehearsalMark #'break-align-symbol = ...
 183 @end example
 184
 185 @noindent
 186 Here, @code{RehearsalMark} is the type of the layout object.
 187
 188 @end table
 189