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
  51 =back
  52
  53 =head1 Request_register
  54
  55 In the previous section the idea of Request has been explained, but
  56 this only solves one half of the problem. The other half is
  57 deciding which requests should be honored, which should merged with
  58 other requests, and which should be ignored. Consider this (pseudo)input
  59
  60         < % chord
  61                 \music { [c() c] }
  62                 \music { [e() e] }
  63         >
  64
  65 Both the c and e are part of a chord (they are in the same
  66 Voice_group), so they should share the beams, and the two [ ] pairs
  67 should be merged. The slurs OTOH are specific for each voice, so they
  68 should not be shared.
  69
  70 The judge in this "allocation" problem is Staff (actually, it's child
  71 C<Complex_staff>). It uses the C<Request_register> to do most of the
  72 work.  For each request C<Complex_staff> queries so-called
  73 C<Request_register>s if they want to accept a request eg, the
  74 C<Notehead_register> will accept C<Note_req>s, and turn down
  75 C<Slur_req>s. If C<Complex_staff> cannot find a register that wants
  76 the request, it is junked (with a warning message).
  77
  78 After all requests have been either assigned, or junked, the Register
  79 will process the requests (which usually means creating an C<Item> or
  80 C<Spanner>). If a C<Request_register> creates something, it tells
  81 C<Complex_staff>. If all requests have been processed, then each
  82 Register is notified of any created Staff_element.
  83
  84 =head2 example:
  85
  86         c4
  87
  88 produces:
  89
  90         note_request (duration 1/4)
  91         stem_request (duration 1/4)
  92
  93 note_request will be taken by a C<Notehead_register>, stem_request
  94 will be taken by a C<Stem_beam_register>. C<Notehead_register> creates
  95 a C<Notehead>, C<Stem_beam_register> creates a C<Stem>. Both announce
  96 this to the Staff. Staff will tell C<Stem_beam_register> about the
  97 C<Notehead>, which will add the C<Notehead> to the C<Stem> it just
  98 created.
  99
 100 To decide on merging, C<Complex_staff> has grouped several
 101 registers. There are a few groups:
 102
 103 =item *
 104
 105 Staff wide, contains
 106
 107         Local_key_register
 108         Bar_register
 109         Key_register
 110         Meter_register
 111         Clef_register
 112
 113 =item *
 114
 115 Voice group, contains
 116
 117         Stem_beam_register
 118         Script_register
 119         Text_register
 120
 121 =item *
 122
 123 Voice, contains
 124
 125         Slur_register
 126         Notehead_register
 127
 128
 129 =item 1
 130
 131
 132 =head1 BREAKING
 133
 134 [Source files: F<command.hh>, F<scommands.cc>]
 135
 136 BREAKING, PREBREAK POSTBREAK, etc.
 137
 138 So what's the deal with PREBREAK and POSTBREAK and all this
 139 stuff?
 140
 141 Let's take text as an example. In German some compound
 142 words change their spelling if they are broken: "backen" becomes
 143 "bak-ken".  TeX has a mechanism to deal with this, you would define
 144 the spelling of "backen" in TeX in this way
 145
 146         \discretionary{bak-}{ken}{backen}
 147
 148 These 3 arguments are called "prebreak", "postbreak" and "nobreak"
 149 text.
 150
 151 The same problem exists when typesetting music. If a line of music is
 152 broken, the next line usually gets a clef. So in TeX terms, the clef
 153 is a postbreak. The same thing happens with meter signs: Normally the
 154 meter follows the bar. If a line is broken at that bar, the bar along
 155 with the meter stays on the "last" line, but the next line also gets a
 156 meter sign after the clef. Using the previous notation,
 157
 158         \discretionary{bar meter}{clef meter}{ bar meter }
 159
 160 In Lilypond, we have the same concepts (and the same
 161 terminology). Each (nonrhythmic) symbol is typeset using a Command
 162 (code: TYPESET). At a breakpoint, TYPESET commands can be grouped
 163 using separators (in lower case):
 164
 165         BREAK_PRE, typeset(bar), typeset(meter),
 166         BREAK_MID, typeset(bar), typeset(meter),
 167         BREAK_POST, typeset(clef), typeset(meter), BREAK_END
 168
 169 The BREAK command sequence is terminated with BREAK_END, so other
 170 commands (like INTERPRET) may follow this sequence.
 171
 172 =head1 SPACING
 173
 174 I think my method is the most elegant algorithm i've seen so far.
 175 Some terminology: I call a vertical group of symbols (notes) which
 176 start at the same time a "column".  Each line of a score has notes in
 177 it, grouped in columns. The difference in starting time between those
 178 columns makes it possible to determine ideal distances between those
 179 columns.
 180
 181 Example:
 182
 183                 time ----->
 184
 185                 col1    col2    col3    col4
 186
 187
 188         voice1  1               1
 189
 190         voice2  2       2       2       2
 191
 192
 193         (1 is a whole note, 2 a half note.)
 194
 195         time_difference (col1 , col2) = 0.5 wholes,
 196         time_difference (col1 , col3) = 1 wholes,
 197         time_difference (col2 , col3) = 0.5 wholes,
 198         etc.
 199
 200 these differences are translated into ideal distances (these translations
 201 have been the subject of discussion in this thread).
 202
 203         distance (col1,col2) = 10 pt
 204         distance (col1,col3) = 14.1 pt
 205         distance (col2,col3) = 10 pt
 206         etc.
 207
 208 as you can see, these distance are conflicting. So instead of
 209 satisfying all those ideals simultaneously, a compromise is sought.
 210
 211 This is Columbus' egg: LilyPond attaches "springs" to each
 212 column-pair.  each spring has an equilibrium-position which is equal to
 213 the above mentioned distance, so
 214
 215 spring (col1, col2) and spring (col2,col3) try to push column 1
 216 and 3 away (to a distance of 20pt) from each other, whereas the spring
 217 between col 1 and col 3 tries to pull those two together (to a
 218 distance of 14.1 pt). The net result of this pushing and pulling is an
 219 equilibrium situation (the pushing cancels the pulling), which can be
 220 calculated as the solution of Quadratic program: it is the solution
 221 with minimum potential energy, for you physicists out there.
 222
 223 This algorithm for doing one line, gives a "badness" parameter for
 224 each line (the potential energy). Now one can use TeX's algorithm for
 225 making paragraphs (using this new version of "badness"): one should
 226 try to minimise the overall badness of a paragraph. LilyPond also uses the
 227 concept of pre- and post-breaks.
 228
 229 (actually, it is a bit more complicated: each column also has a
 230 minimum distance to other columns, to prevent symbols from running
 231 into symbols of other columns.)
 232
 233 =head1 SEE ALSO
 234
 235 =head2 References
 236
 237 [partly by Mark Basinski <basinski@arizona.edu>]
 238
 239 Herbert Chlapik,
 240
 241 W.A. Hegazy and J. S. Gourlay. Optimal line breaking in music. In
 242 ``Document Manipulation and Typography'', J.C. van Vliet (ed) 1988.
 243
 244 Ross, Ted. ``Teach yourself the art of music engraving and processing''
 245 (3rd edition). Hansen House, Miami Beach, FL.
 246
 247         Hansen House
 248         1820 West Ave.
 249         Miami, FL  33139
 250         (305) 532-5461
 251
 252 [This is about I<engraving> i.e. professional music typesetting, and includes
 253 some good spacing tables]
 254
 255 Read, Gardner. ``Modern Rhythmic Notation.'' Indiana University Press, 1978.
 256
 257 Read, Gardner. ``Music Notation'' (2nd edition). Taplinger Publishing,
 258 New York.
 259
 260 [This is as close to the ``standard'' reference work for music notation issues
 261 as one is likely to get.]
 262
 263
 264 =head2  Further reading
 265
 266 (of varying usefulness):
 267
 268 Donato, Anthony. Preparing Music Manuscript. Englewood Cliffs:
 269 Prentice-Hall, 1963.
 270
 271 Donemus. "Uitgeven van muziek". Donemus Amsterdam, 1900
 272
 273 Heussenstamm, George. The Norton Manual of Music Notation. New York:
 274 Norton, 1987.
 275
 276 Karkoshka, Erdhard. Notation in New Music. Trans. Ruth Koenig. New York:
 277 Praeger    Publishers, 1972.  Out of print.
 278
 279 Roelofs, Ren\'e. ``Een Geautomatiseerd Systeem voor het Afdrukken van
 280 Muziek'' afstudeerscriptie Bestuurlijke informatica, no 45327, Erasmus
 281 universiteit Rotterdam, 1991.  (``An automated system for printing
 282 music'' Master's Thesis Management and Computer Science.)
 283
 284 C. Roemer, The Art of Music Copying. Roerick music co., Sherman Oaks
 285 (CA), 1973.
 286
 287 Rosecrans, Glen. Music Notation Primer. New York: Passantino, 1979.
 288
 289 Stone, Kurt. Music Notation in the Twentieth Century. New York: Norton, 1980.
 290
 291