Documentation/lilygut.pod

   1 =head1 NAME
   2
   3 LilyGuts - doco to the internals of LilyPond
   4
   5 =head1 DESCRIPTION
   6
   7 This page documents some aspects of the internals of LilyPond. Some of
   8 this stuff comes from e-mail I wrote, some from e-mail others wrote,
   9 some are large comments taken away from the headers
  10
  11 You should use doc++ to take a peek at the sources.
  12
  13 [have to do more doco; see TODO]
  14
  15 =head1 OVERVIEW
  16
  17 LilyPond is a "5-pass" system:
  18
  19 =over 5
  20
  21 =item 1. Parsing:
  22
  23 No difficult algorithms. Associated datastructures have prefix Input
  24 (eg Input_score, Input_command)
  25
  26 =item 2. Processing:
  27
  28 Requests are processed and granted. This is done by three cooperating
  29 structeres: Staff, Staff_walker and Staff_column.  In this step
  30 data-structures for 3. are created and filled with data: PScore, PCol,
  31 PStaff
  32
  33 =item 3. Calculation:
  34
  35 This step uses structures which have names starting with 'P'.
  36 linebreaks and horizontal positions of PCols are determined. Line_of_*
  37 generated.
  38
  39 =item 4. Postprocesing:
  40
  41 Some items and all spanners need computation after the PCol positions
  42 are determined.
  43
  44 =item 5. Output
  45
  46 Very simple, just walk all Line_of_* and follow the links over there
  47
  48 =back
  49
  50 =head1 REQUESTS
  51
  52 [see F<request.hh>]
  53
  54 Any Voice_element can do a number of requests. A request is done
  55 to the C<Staff> which contains the C<Voice_element>. The staff decides
  56 whether to to honor the request, ignore it, or merge it with other
  57 requests. Merging of requests is preferably done with other
  58 requests done by members of the same voicegroups (beams, brackets, stems)
  59
  60 Please refer to the documentation of the Child classes of
  61 C<Request> for explanation of each request type.
  62
  63 The result of a request will be an C<Item> or a C<Spanner>, which
  64 will be put on a C<PStaff>. Note that the C<PStaff> and the original
  65 C<Staff> need not have anything in common. For example, the
  66 ``double'' piano Staff could interpret commands which juggle
  67 melodies across the left and right hand, and may put the result in
  68 two five-line PStaffs (maybe with extra PStaffs to carry the dynamic
  69 signs and any lyric.
  70
  71 The class C<Staff> should be thought as a container for the
  72 C<Voice>s, and an interpreter for C<Request>s and C<Command>s.
  73 Different staffs can produce different outputs; a melodious voice
  74 which is put into a percussion-Staff, will be typeset as the rythm of
  75 that voice.
  76
  77 After C<Staff> made up her mind, the resultant items and
  78 spanners are put on the PScore.
  79
  80 =over 5
  81
  82 =item C<Barcheck_req>
  83
  84 Checks during music processing if start of this voice element
  85 coincides with the start of a measure. Handy to check if you left out
  86 some voice elts.
  87
  88 =item C<Note_req>
  89
  90 Staff has to decide if the ball should be hanging left or right. This
  91 influences the horizontal dimensions of a column, and this  is why
  92 request processing should be done before horizontal spacing.
  93
  94 Other voices' frivolities may cause the need for accidentals, so this
  95 is also for the  C<Staff> to decide. The  C<Staff> can decide on positioning
  96 based on ottava commands and the appropriate clef.
  97
  98 =item C<Rest_req>
  99
 100 Why a request? It might be a good idea to not typeset the rest, if the
 101 paper is too crowded.
 102
 103 =item C<Span_req>
 104
 105 This type of request typically results in the creation of a C<Spanner>
 106
 107 =item C<Beam_req>
 108
 109 Staff has to combine this request with the stem_request, since the
 110 number of flags that a stem wants to carry will determine the
 111 number of beams.
 112
 113 =item  C<Dynamic>
 114
 115 Each dynamic is bound to one note (a crescendo spanning multiple
 116 notes is thought to be made of two "dynamics": a start and a stop).
 117 Dynamic changes can occur in a smaller time than the length of its
 118 note, therefore fore each  C<Dynamic> request carries a time, measured
 119 from the start of its note.
 120
 121 This subfield would come in handy, if LilyPond  was adapted for midi
 122 support.
 123
 124 =back
 125
 126 =head1 Request_register
 127
 128 In the previous section the idea of Request has been explained, but
 129 this only solves one half of the problem. The other half is
 130 deciding which requests should be honored, which should merged with
 131 other requests, and which should be ignored. Consider this (pseudo)input
 132
 133         { % chord
 134                 \music { [c() c] }
 135                 \music { [e() e] }
 136         }
 137
 138 Both the c and e are part of a chord (they are in the same
 139 Voice_group), so they should share the beams, and the two [ ] pairs
 140 should be merged. The slurs OTOH are specific for each voice, so they
 141 should not be shared.
 142
 143 The judge in this "allocation" problem is Staff (actually, it's child
 144 C<Complex_staff>). It uses the C<Request_register> to do most of the
 145 work.  For each request C<Complex_staff> queries so-called
 146 C<Request_register>s if they want to accept a request eg, the
 147 C<Notehead_register> will accept C<Note_req>s, and turn down
 148 C<Slur_req>s. If C<Complex_staff> cannot find a register that wants
 149 the request, it is junked (with a warning message).
 150
 151 After all requests have been either assigned, or junked, the Register
 152 will process the requests (which usually means creating an C<Item> or
 153 C<Spanner>). If a C<Request_register> creates something, it tells
 154 C<Complex_staff>. If all requests have been processed, then each
 155 Register is notified of any created Staff_element.
 156
 157 =head2 example:
 158
 159         c4
 160
 161 produces:
 162
 163         note_request (duration 1/4)
 164         stem_request (duration 1/4)
 165
 166 note_request will be taken by a C<Notehead_register>, stem_request
 167 will be taken by a C<Stem_beam_register>. C<Notehead_register> creates
 168 a C<Notehead>, C<Stem_beam_register> creates a C<Stem>. Both announce
 169 this to the Staff. Staff will tell C<Stem_beam_register> about the
 170 C<Notehead>, which will add the C<Notehead> to the C<Stem> it just
 171 created.
 172
 173 To decide on merging, C<Complex_staff> has grouped several
 174 registers. There are a few groups:
 175
 176 =item *
 177
 178 Staff wide, contains
 179
 180         Local_key_register
 181         Bar_register
 182         Key_register
 183         Meter_register
 184         Clef_register
 185
 186 =item *
 187
 188 Voice group, contains
 189
 190         Stem_beam_register
 191         Script_register
 192         Text_register
 193
 194 =item *
 195
 196 Voice, contains
 197
 198         Slur_register
 199         Notehead_register
 200
 201
 202 =item 1
 203
 204
 205 =head1 BREAKING
 206
 207 [Source files: F<command.hh>, F<scommands.cc>]
 208
 209 BREAKING, PREBREAK POSTBREAK, etc.
 210
 211 So what's the deal with PREBREAK and POSTBREAK and all this
 212 stuff?
 213
 214 Let's take text as an example. In German some compound
 215 words change their spelling if they are broken: "backen" becomes
 216 "bak-ken".  TeX has a mechanism to deal with this, you would define
 217 the spelling of "backen" in TeX in this way
 218
 219         \discretionary{bak-}{ken}{backen}
 220
 221 These 3 arguments are called "prebreak", "postbreak" and "nobreak"
 222 text.
 223
 224 The same problem exists when typesetting music. If a line of music is
 225 broken, the next line usually gets a clef. So in TeX terms, the clef
 226 is a postbreak. The same thing happens with meter signs: Normally the
 227 meter follows the bar. If a line is broken at that bar, the bar along
 228 with the meter stays on the "last" line, but the next line also gets a
 229 meter sign after the clef. Using the previous notation,
 230
 231         \discretionary{bar meter}{clef meter}{ bar meter }
 232
 233 In Lilypond, we have the same concepts (and the same
 234 terminology). Each (nonrhythmic) symbol is typeset using a Command
 235 (code: TYPESET). At a breakpoint, TYPESET commands can be grouped
 236 using separators (in lower case):
 237
 238         BREAK_PRE, typeset(bar), typeset(meter),
 239         BREAK_MID, typeset(bar), typeset(meter),
 240         BREAK_POST, typeset(clef), typeset(meter), BREAK_END
 241
 242 The BREAK command sequence is terminated with BREAK_END, so other
 243 commands (like INTERPRET) may follow this sequence.
 244
 245 =head1 SPACING
 246
 247 I think my method is the most elegant algorithm i've seen so far.
 248 Some terminology: I call a vertical group of symbols (notes) which
 249 start at the same time a "column".  Each line of a score has notes in
 250 it, grouped in columns. The difference in starting time between those
 251 columns makes it possible to determine ideal distances between those
 252 columns.
 253
 254 Example:
 255
 256                 time ----->
 257
 258                 col1    col2    col3    col4
 259
 260
 261         voice1  1               1
 262
 263         voice2  2       2       2       2
 264
 265
 266         (1 is a whole note, 2 a half note.)
 267
 268         time_difference (col1 , col2) = 0.5 wholes,
 269         time_difference (col1 , col3) = 1 wholes,
 270         time_difference (col2 , col3) = 0.5 wholes,
 271         etc.
 272
 273 these differences are translated into ideal distances (these translations
 274 have been the subject of discussion in this thread).
 275
 276         distance (col1,col2) = 10 pt
 277         distance (col1,col3) = 14.1 pt
 278         distance (col2,col3) = 10 pt
 279         etc.
 280
 281 as you can see, these distance are conflicting. So instead of
 282 satisfying all those ideals simultaneously, a compromise is sought.
 283
 284 This is Columbus' egg: LilyPond attaches "springs" to each
 285 column-pair.  each spring has an equilibrium-position which is equal to
 286 the above mentioned distance, so
 287
 288 spring (col1, col2) and spring (col2,col3) try to push column 1
 289 and 3 away (to a distance of 20pt) from each other, whereas the spring
 290 between col 1 and col 3 tries to pull those two together (to a
 291 distance of 14.1 pt). The net result of this pushing and pulling is an
 292 equilibrium situation (the pushing cancels the pulling), which can be
 293 calculated as the solution of Quadratic program: it is the solution
 294 with minimum potential energy, for you physicists out there.
 295
 296 This algorithm for doing one line, gives a "badness" parameter for
 297 each line (the potential energy). Now one can use TeX's algorithm for
 298 making paragraphs (using this new version of "badness"): one should
 299 try to minimise the overall badness of a paragraph. LilyPond also uses the
 300 concept of pre- and post-breaks.
 301
 302 (actually, it is a bit more complicated: each column also has a
 303 minimum distance to other columns, to prevent symbols from running
 304 into symbols of other columns.)
 305
 306 =head1 SEE ALSO
 307
 308 =head2 References
 309
 310 [partly by Mark Basinski <basinski@arizona.edu>]
 311
 312 Herbert Chlapik,
 313
 314 W.A. Hegazy and J. S. Gourlay. Optimal line breaking in music. In
 315 ``Document Manipulation and Typography'', J.C. van Vliet (ed) 1988.
 316
 317 Ross, Ted. ``Teach yourself the art of music engraving and processing''
 318 (3rd edition). Hansen House, Miami Beach, FL.
 319
 320         Hansen House
 321         1820 West Ave.
 322         Miami, FL  33139
 323         (305) 532-5461
 324
 325 [This is about I<engraving> i.e. professional music typesetting, and includes
 326 some good spacing tables]
 327
 328 Read, Gardner. ``Modern Rhythmic Notation.'' Indiana University Press, 1978.
 329
 330 Read, Gardner. ``Music Notation'' (2nd edition). Taplinger Publishing,
 331 New York.
 332
 333 [This is as close to the ``standard'' reference work for music notation issues
 334 as one is likely to get.]
 335
 336
 337 =head2  Further reading
 338
 339 (of varying usefulness):
 340
 341 Donato, Anthony. Preparing Music Manuscript. Englewood Cliffs:
 342 Prentice-Hall, 1963.
 343
 344 Donemus. "Uitgeven van muziek". Donemus Amsterdam, 1900
 345
 346 Heussenstamm, George. The Norton Manual of Music Notation. New York:
 347 Norton, 1987.
 348
 349 Karkoshka, Erdhard. Notation in New Music. Trans. Ruth Koenig. New York:
 350 Praeger    Publishers, 1972.  Out of print.
 351
 352 Roelofs, Ren\'e. ``Een Geautomatiseerd Systeem voor het Afdrukken van
 353 Muziek'' afstudeerscriptie Bestuurlijke informatica, no 45327, Erasmus
 354 universiteit Rotterdam, 1991.  (``An automated system for printing
 355 music'' Master's Thesis Management and Computer Science.)
 356
 357 C. Roemer, The Art of Music Copying. Roerick music co., Sherman Oaks
 358 (CA), 1973.
 359
 360 Rosecrans, Glen. Music Notation Primer. New York: Passantino, 1979.
 361
 362 Stone, Kurt. Music Notation in the Twentieth Century. New York: Norton, 1980.
 363
 364