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