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