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