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 Staff wide, contains
 178         Local_key_register
 179         Bar_register
 180         Key_register
 181         Meter_register
 182         Clef_register
 183
 184 =item *
 185 Voice group, contains
 186         Stem_beam_register
 187         Script_register
 188         Text_register
 189
 190 =item *
 191 Voice, contains
 192         Slur_register
 193         Notehead_register
 194
 195
 196 =item 1
 197
 198
 199 =head1 BREAKING
 200
 201 [Source files: F<command.hh>, F<scommands.cc>]
 202
 203 BREAKING, PREBREAK POSTBREAK, etc.
 204
 205 So what's the deal with PREBREAK and POSTBREAK and all this
 206 stuff?
 207
 208 Let's take text as an example. In German some compound
 209 words change their spelling if they are broken: "backen" becomes
 210 "bak-ken".  TeX has a mechanism to deal with this, you would define
 211 the spelling of "backen" in TeX in this way
 212
 213         \discretionary{bak-}{ken}{backen}
 214
 215 These 3 arguments are called "prebreak", "postbreak" and "nobreak"
 216 text.
 217
 218 The same problem exists when typesetting music. If a line of music is
 219 broken, the next line usually gets a clef. So in TeX terms, the clef
 220 is a postbreak. The same thing happens with meter signs: Normally the
 221 meter follows the bar. If a line is broken at that bar, the bar along
 222 with the meter stays on the "last" line, but the next line also gets a
 223 meter sign after the clef. Using the previous notation,
 224
 225         \discretionary{bar meter}{clef meter}{ bar meter }
 226
 227 In Lilypond, we have the same concepts (and the same
 228 terminology). Each (nonrhythmic) symbol is typeset using a Command
 229 (code: TYPESET). At a breakpoint, TYPESET commands can be grouped
 230 using separators (in lower case):
 231
 232         BREAK_PRE, typeset(bar), typeset(meter),
 233         BREAK_MID, typeset(bar), typeset(meter),
 234         BREAK_POST, typeset(clef), typeset(meter), BREAK_END
 235
 236 The BREAK command sequence is terminated with BREAK_END, so other
 237 commands (like INTERPRET) may follow this sequence.
 238
 239 =head1 SPACING
 240
 241 I think my method is the most elegant algorithm i've seen so far.
 242 Some terminology: I call a vertical group of symbols (notes) which
 243 start at the same time a "column".  Each line of a score has notes in
 244 it, grouped in columns. The difference in starting time between those
 245 columns makes it possible to determine ideal distances between those
 246 columns.
 247
 248 Example:
 249
 250                 time ----->
 251
 252                 col1    col2    col3    col4
 253
 254
 255         voice1  1               1
 256
 257         voice2  2       2       2       2
 258
 259
 260         (1 is a whole note, 2 a half note.)
 261
 262         time_difference (col1 , col2) = 0.5 wholes,
 263         time_difference (col1 , col3) = 1 wholes,
 264         time_difference (col2 , col3) = 0.5 wholes,
 265         etc.
 266
 267 these differences are translated into ideal distances (these translations
 268 have been the subject of discussion in this thread).
 269
 270         distance (col1,col2) = 10 pt
 271         distance (col1,col3) = 14.1 pt
 272         distance (col2,col3) = 10 pt
 273         etc.
 274
 275 as you can see, these distance are conflicting. So instead of
 276 satisfying all those ideals simultaneously, a compromise is sought.
 277
 278 This is Columbus' egg: LilyPond attaches "springs" to each
 279 column-pair.  each spring has an equilibrium-position which is equal to
 280 the above mentioned distance, so
 281
 282 spring (col1, col2) and spring (col2,col3) try to push column 1
 283 and 3 away (to a distance of 20pt) from each other, whereas the spring
 284 between col 1 and col 3 tries to pull those two together (to a
 285 distance of 14.1 pt). The net result of this pushing and pulling is an
 286 equilibrium situation (the pushing cancels the pulling), which can be
 287 calculated as the solution of Quadratic program: it is the solution
 288 with minimum potential energy, for you physicists out there.
 289
 290 This algorithm for doing one line, gives a "badness" parameter for
 291 each line (the potential energy). Now one can use TeX's algorithm for
 292 making paragraphs (using this new version of "badness"): one should
 293 try to minimise the overall badness of a paragraph. LilyPond also uses the
 294 concept of pre- and post-breaks.
 295
 296 (actually, it is a bit more complicated: each column also has a
 297 minimum distance to other columns, to prevent symbols from running
 298 into symbols of other columns.)
 299
 300 =head1 SEE ALSO
 301
 302 =head2 References
 303
 304 [partly by Mark Basinski <basinski@arizona.edu>]
 305
 306 Herbert Chlapik,
 307
 308 W.A. Hegazy and J. S. Gourlay. Optimal line breaking in music. In
 309 ``Document Manipulation and Typography'', J.C. van Vliet (ed) 1988.
 310
 311 Ross, Ted. ``Teach yourself the art of music engraving and processing''
 312 (3rd edition). Hansen House, Miami Beach, FL.
 313
 314         Hansen House
 315         1820 West Ave.
 316         Miami, FL  33139
 317         (305) 532-5461
 318
 319 [This is about *engraving* i.e. professional music typesetting, and includes
 320 some good spacing tables]
 321
 322 Read, Gardner. ``Modern Rhythmic Notation.'' Indiana University Press, 1978.
 323
 324 Read, Gardner. ``Music Notation'' (2nd edition). Taplinger Publishing,
 325 New York.
 326
 327 [This is as close to the ``standard'' reference work for music notation issues
 328 as one is likely to get.]
 329
 330
 331 =head2  Further reading
 332
 333 (of varying usefulness):
 334
 335 Donato, Anthony. Preparing Music Manuscript. Englewood Cliffs:
 336 Prentice-Hall, 1963.
 337
 338 Donemus. "Uitgeven van muziek". Donemus Amsterdam, 1900
 339
 340 Heussenstamm, George. The Norton Manual of Music Notation. New York:
 341 Norton, 1987.
 342
 343 Karkoshka, Erdhard. Notation in New Music. Trans. Ruth Koenig. New York:
 344 Praeger    Publishers, 1972.  Out of print.
 345
 346 Roelofs, Ren\'e. ``Een Geautomatiseerd Systeem voor het Afdrukken van
 347 Muziek'' afstudeerscriptie Bestuurlijke informatica, no 45327, Erasmus
 348 universiteit Rotterdam, 1991.  (``An automated system for printing
 349 music'' Master's Thesis Management and Computer Science.)
 350
 351 C. Roemer, The Art of Music Copying. Roerick music co., Sherman Oaks
 352 (CA), 1973.
 353
 354 Rosecrans, Glen. Music Notation Primer. New York: Passantino, 1979.
 355
 356 Stone, Kurt. Music Notation in the Twentieth Century. New York: Norton, 1980.
 357
 358