+++ /dev/null
-=head1 NAME
-
-LilyGuts - doco to the internals of GNU LilyPond
-
-=head1 DESCRIPTION
-
-This page documents some aspects of the internals of GNU LilyPond. Some of
-this stuff comes from e-mail I wrote, some from e-mail others wrote,
-some are large comments taken away from the headers. This is why this
-page may be a little incoherent.
-
-You should use doc++ to take a peek at the sources.
-
-This should become a Hacking-HOWTO. If you find any confusing stuff
-here, let me know. I am a hacker, and don't spend enough time doccing
-what I write. (Most stuff here which refers to the code is slightly outdated)
-
-If you finally have mastered some internal piece of lily, your
-explanation could be added here.
-
-=head1 OVERVIEW
-
-GNU LilyPond is a "multi-pass" system. The different passes have been
-created so that they do not depend on each other. In a later stage
-some parts may be moved into libraries, or seperate programs, or they
-might be integrated in larger systems.
-
-=over 4
-
-=item Parsing:
-
-No difficult algorithms. The .ly file is read, and converted to a list
-of C<Scores>, which each contain C<Music> and paper/midi-definitions.
-
-=item Creating elements
-
-The music is walked column by column. The iterators which do the
-walking report the Request to Translators which use this information
-to create elements, either MIDI or "visual" elements. The translators
-form a hierarchy; the ones for paper output are Engravers, for MIDI
-Performers).
-
-The translators swallow requests, create elements, broadcast them to
-other translators on higher or same level in the hierarchy:
-
-The stem of a voice A is broadcast to the staff which contains A, but
-not to the noteheads of A, and not to the stems, beams and noteheads
-of a different voice (say B) or a different staff. The stem and
-noteheads of A are coupled, because the the Notehead_engraver
-broadcasts its heads, and the Stem catches these.
-
-The engraver which agrees to handle a request decides whether to to
-honor the request, ignore it, or merge it with other requests. Merging
-of requests is preferably done with other requests done by members of
-the same voicegroups (beams, brackets, stems). In this way you can put
-the voices of 2 instruments in a conductor's score so they make chords
-(the Stem_reqs of both instruments will be merged).
-
-=item Prebreaking
-
-Breakable stuff (eg. clefs and bars) are copied into pre and postbreaks.
-
-=item Preprocessing
-
-Some dependencies are resolved, such as the direction of stems, beams,
-and "horizontal" placement issues (the order of clefs, keys etc,
-placement of chords in multi-voice music),
-
-=item Break calculation:
-
-The lines and horizontal positions of the columns are determined.
-
-=item Breaking
-
-Through some magical interactions with Line_of_score and Super_elem
-(check out the source) the "lines" are produced.
-
-All other spanners can figure across which lines they are spread. If
-applicable, they break themselves into pieces. After this, each piece
-(or, if there are no pieces, the original spanner itself) throws out
-any dependencies which are in the wrong line.
-
-=item Postprocesing:
-
-Some items and all spanners need computation after the PCol positions
-are determined. Examples: slurs, vertical positions of staffs.
-
-=item Output paper
-
-=back
-
-=head1 INTERNALS
-
-This chapter deals with the internals of Mudela.
-
-=head2 Requests
-
-As you can see, most information is stored in the form of a request.
-In music typesetting, the user might want to cram a lot more symbols
-on the paper than actually fits. To reflect this idea (the user asks
-more than we can do), the container for this data is called Request.
-
-In a lot of other formats this would be called an 'Event'
-
-=over 4
-
-=item C<Barcheck_req>
-
-Checks during music processing if start of this voice element
-coincides with the start of a measure. Handy to check if you left out
-some voice elts.
-
-=item C<Note_req>
-
-LilyPond has to decide if the ball should be hanging left or
-right. This influences the horizontal dimensions of a column, and this
-is why request processing should be done before horizontal spacing.
-
-Other voices' frivolities may cause the need for accidentals, so this
-is also for the to decide. The engraver can decide on positioning based on
-ottava commands and the appropriate clef.
-
-=item C<Rest_req>
-
-Typeset a rest.
-
-=item C<Span_req>
-
-This type of request typically results in the creation of a C<Spanner>
-
-=item C<Beam_req>
-
-Start/stop a beam.
-
-Engraver has to combine this request with the stem_request, since the
-number of flags that a stem wants to carry will determine the
-number of beams.
-
-=item C<Dynamic>
-
-Each dynamic is bound to one note (a crescendo spanning multiple
-notes is thought to be made of two "dynamics": a start and a stop).
-Dynamic changes can occur in a smaller time than the length of its
-note, therefore fore each C<Dynamic> request carries a time, measured
-from the start of its note.
-
-=head2 Voice groups
-
-Voice group is a (time-dependent) collection of voices which share
-some characteristics (slurs, stems) at some time.
-
-=head1 Request_engraver
-
-In the previous section the idea of Request has been explained, but
-this only solves one half of the problem. The other half is
-deciding which requests should be honored, which should merged with
-other requests, and which should be ignored. Consider this (pseudo)input
-
- < % chord
- \music { [c() c] }
- \music { [e() e] }
- >
-
-Both the c and e are part of a chord (they are in the same
-Voice_group), so they should share the beams, and the two [ ] pairs
-should be merged. The slurs OTOH are specific for each voice, so they
-should not be shared.
-
-The judge in this "allocation" problem a set of broker. It uses the
-C<Request_engraver> to do most of the work. For each request
-C<Complex_staff> queries so-called C<Request_engraver>s if they want
-to accept a request eg, the C<Notehead_engraver> will accept
-C<Note_req>s, and turn down C<Slur_req>s. If the Music_iterator
-cannot find a engraver that wants the request, it is junked (with a
-warning message).
-
-After all requests have been either assigned, or junked, the Engraver
-will process the requests (which usually means creating an C<Item> or
-C<Spanner>). If a C<Request_engraver> creates something, it tells
-If all requests have been processed, then each Engraver is notified
-of any created Score_element, via a broadcasting system.
-
-=head2 example:
-
- c4
-
-produces:
-
- note_request (duration 1/4)
- stem_request (duration 1/4)
-
-note_request will be taken by a C<Notehead_engraver>, stem_request
-will be taken by a C<Stem_beam_engraver>. C<Notehead_engraver> creates
-a C<Notehead>, C<Stem_beam_engraver> creates a C<Stem>. Both announce
-this to the Staff_engraver. Staff_engraver will tell
-C<Stem_beam_engraver> about the C<Notehead>, which will add the
-C<Notehead> to the C<Stem> it just created.
-
-To decide on merging, several engravers have been grouped. Please
-check F<init/engraver.ly>.
-
-
-=head1 ITEMS and SPANNERS
-
-The symbols that are printed, are generated by items and spanners
-(staff-elements). An item has one horizontal position, whereas a
-spanner spans several columns.
-
-=head1 DEPENDENCIES
-
-In music symbols depend on each other: the stems of a beam should
-point in the same direction as the beam itself, so the stems of a beam
-depend on the beam. In the same way do scripts depend on the direction
-of the stem. To reflect this, LilyPond has the notion of dependency.
-It works in the same fashion that C<make> uses to build programs: before
-a stem is calculated, its dependencies (the beam) should be
-calculated. Before a slur is calculated, its dependencies (stems, noteheads)
-should be calculated.
-
-=head1 BREAKING
-
-So what is this PREBREAK and POSTBREAK stuff?
-
-Let's take text as an example. In German some compound
-words change their spelling if they are broken: "backen" becomes
-"bak-ken". TeX has a mechanism to deal with this, you would define
-the spelling of "backen" in TeX in this way
-
- \discretionary{bak-}{ken}{backen}
-
-These 3 arguments are called "prebreak", "postbreak" and "nobreak"
-text.
-
-The same problem exists when typesetting music. If a line of music is
-broken, the next line usually gets a clef. So in TeX terms, the clef
-is a postbreak. The same thing happens with meter signs: Normally the
-meter follows the bar. If a line is broken at that bar, the bar along
-with the meter stays on the "last" line, but the next line also gets a
-meter sign after the clef. Using the previous notation,
-
- \discretionary{bar meter}{clef meter}{ bar meter }
-
-In GNU Lilypond, we have the same concepts (and the same
-terminology). Each (nonrhythmic) symbol is typeset in a nonrhythmic column
-At a breakpoint, multiple symbols are printed; symbols to be printed
-if the line is not broken, symbols to appear on the previous line, and
-on the next line if it is broken.
-
-=head1 SPACING
-
-
-Some terminology: I call a vertical group of symbols (notes) which
-start at the same time a "column". Each line of a score has notes in
-it, grouped in columns. The difference in starting time between those
-columns makes it possible to determine ideal distances between those
-columns.
-
-Example:
-
- time ----->
-
- cols: col1 col2 col3 col4
-
-
- voice1 1 1
-
- voice2 2 2 2 2
-
-
- (1 is a whole note, 2 a half note.)
-
- time_difference (col1 , col2) = 0.5 wholes,
- time_difference (col1 , col3) = 1 wholes,
- time_difference (col2 , col3) = 0.5 wholes,
- etc.
-
-these differences are translated into ideal distances
-
- distance (col1,col2) = 10 pt
- distance (col1,col3) = 14.1 pt
- distance (col2,col3) = 10 pt
- etc.
-
-as you can see, these distance are conflicting. So instead of
-satisfying all those ideals simultaneously, a compromise is sought.
-
-This is Columbus' egg: GNU LilyPond attaches "springs" to each
-column-pair. each spring has an equilibrium-position which is equal to
-the above mentioned distance, so
-
-spring (col1, col2) and spring (col2,col3) try to push column 1
-and 3 away (to a distance of 20pt) from each other, whereas the spring
-between col 1 and col 3 tries to pull those two together (to a
-distance of 14.1 pt). The net result of this pushing and pulling is an
-equilibrium situation (the pushing cancels the pulling), which can be
-calculated as the solution of Quadratic program: it is the solution
-with minimum potential energy, for you physicists out there.
-
-This algorithm for doing one line, gives a "badness" parameter for
-each line (the potential energy). Now one can use TeX's algorithm for
-making paragraphs (using this new version of "badness"): one should
-try to minimise the overall badness of a paragraph. GNU LilyPond also
-uses the concept of pre- and post-breaks.
-
-(actually, it is a bit more complicated: each column also has a
-minimum distance to other columns, to prevent symbols from running
-into symbols of other columns.)
-
-
-=head1 SPACING 2
-
-
-This of course does not solve the problem of generating the
-springs. This is an area that needs a lot of work, and the optimal
-solution to find is not of a mathematical nature.
-
-Gourlay's solution is used.
-
-
+++ /dev/null
-=head1 NAME
-
-Lily Literature -- reading on music engraving/typesetting/etc.
-
-=head1 DESCRIPTION
-
-A list of resources on music printing/writing and engraving. Please
-note that don't have access to most material.
-
-[Personal comments appear in brackets. What I (HWN) know, I've
-commented myself. They are just my personal comments, not to be taken
-too seriously]
-
-=head2 Music engraving: references
-
-Helene Wanske. ``Musiknotation --- Von der Syntax des Notenstichs zum
-EDV-gesteuerten Notensatz'', Schott-Verlag, Mainz 1988.ISBN 3-7957-2886-x.
-
-[I. A very thorough overview of engraving practices of various
-craftsmen. It includes detailed specs of characters, dimensions etc.
-II. a thorough overview of a (by now antiquated) automated system
-called Ikarus; EDV Means e(lektronischen) D(aten)v(erarbeitung),
-electronic data processing HWN]
-
-Maxwell Weaner and Walter Boelke, Standard Music Notation Practice,
-revised edition by Arnold Broido and Daniel Dorff. Music Publisher's
-Association of the United States Inc., 1993.
-
-Ted Ross. ``Teach yourself the art of music engraving and processing''
-(3rd edition). Hansen House, Miami Beach, FLorida.
-
-[This is about I<engraving> i.e. professional music typesetting, and
-includes some good spacing tables MB]
-
-Gardner Read. ``Modern Rhythmic Notation.'' Indiana University Press,
-1978.
-
-Gardner Read. ``Music Notation'' (2nd edition). Taplinger Publishing,
-New York.
-
-[This is as close to the ``standard'' reference work for music
-notation issues as one is likely to get. MB]
-
-K. Hader. ``Aus der Werkstatt eines Notenstechers'' Waldheim--Eberle
-Verlag, Vienna 1948
-
-MPA. Standard music notation specifications for computer programming.
-December 1996
-
-[Pamphlet explaining some fine points in music font design HWN]
-
-
-=head2 Notation with computers
-
-Donald Byrd. ``Music Notation by Computer''. Dissertation Indiana
-University, 1985.
-
-Donald Byrd. ``A System for Music Printing by Computer.'' Computers
-and the Humanities, 8 (1974), 161-72.
-
-Leland Smith. ``Editing and Printing Music by Computer.'' Journal of
-Music Theory, 17 (1973), 292-309.
-
-[If I remember correctly, this was concerned more with an input
-language than with the typography. SP.]
-
-David A Gomberg. ``A Computer-Oriented System for Music Printing.''
-Dissertation Washington University. 1975.
-
-Walter B Hewlett. and Eleanor Selfridge-Field. ``Directory of Computer
-Assisted Research in Musicology''. Menlo Park, CA: Center for Computer
-Assisted Research in the Humanities.
-
-[Annual editions since 1985, many containing surveys of music
-typesetting technology. SP]
-
-David A. Gomberg; ``A Computer-oriented System for Music Printing.''
-Computers and the Humanities, Vol.11, pp 63-80.
-
-John S. Gourlay. ``Spacing a Line of Music,'' Technical Report
-OSU-CISRC-10/87-TR35, Department of Computer and Information Science,
-The Ohio State University, 1987.
-
-[Algorithm for generating spacing in one line of (polyphonic) music,
-tailored for use with MusiCopy. LilyPond uses a variant of it (as of
-pl 76) HWN]
-
-Allen Parish, Wael A. Hegazy, John S. Gourlay, Dean K. Roush and
-F. Javier Sola. ``MusiCopy: An automated Music Formatting System''.
-Technical Report OSU-CISRC-10/87-TR29, Department of Computer and
-Information Science, The Ohio State University, 1987.
-
-[A brief overview of MusiCopy HWN]
-
-John S. Gourlay, A. Parrish, D. Roush, F. Sola, Y. Tien. ``Computer
-Formatting of Music,'' Technical Report OSU-CISRC-2/87-TR3, Department
-of Computer and Information Science, The Ohio State University, 1987.
-
-[This paper discusses the development of algorithms for the formatting
-of musical scores (from abstract). It also appeared at PROTEXT III,
-Ireland 1986]
-
-Wael A. Hegazy. ``On the Implementation of the MusiCopy Language
-Processor,'' Technical Report OSU-CISRC-10/87-TR34, Department of
-Computer and Information Science, The Ohio State University, 1987.
-
-[Describes the "parser" which converts MusiCopy MDL to MusiCopy
-Simultaneities & columns HWN]
-
-Wael A. Hegazy and John S. Gourlay. ``Optimal line breaking in
-music''. Technical Report OSU-CISRC-8/87-TR33, Department of Computer
-and Information Science, The Ohio State University, 1987
-
-[This generalizes TeX's breaking algorithm to music. It also appeared in
-Document Manipulation and Typography, J.C. van Vliet (ed) 1988. HWN]
-
-Dean K. Roush. ``Using MusiCopy''. Technical Report
-OSU-CISRC-18/87-TR31, Department of Computer and Information Science,
-The Ohio State University, 1987
-
-[User manual of MusiCopy. Includes an impressive example piece. HWN.]
-
-A. Parrish and John S. Gourlay. ``Computer Formatting of Musical
-Simultaneities,'' Technical Report OSU-CISRC-10/87-TR28, Department of
-Computer and Information Science, The Ohio State University, 1987.
-
-[Placement of balls, stems, dots which occur at the same moment
-("Simultaneity") HWN]
-
-D. Roush. ``Music Formatting Guidelines,'' Technical Report
-OSU-CISRC-3/88-TR10, Department of Computer and Information Science,
-The Ohio State University, 1988.
-
-[Rules on formatting music formulated for use in computers HWN]
-
-F. Sola. ``Computer Design of Musical Slurs, Ties and Phrase Marks,''
-Technical Report OSU-CISRC-10/87-TR32, Department of Computer and
-Information Science, The Ohio State University, 1987.
-
-[Overview of a procedure for generating slurs HWN]
-
-F. Sola and D. Roush. ``Design of Musical Beams,'' Technical Report
-OSU-CISRC-10/87-TR30, Department of Computer and Information Science,
-The Ohio State University, 1987.
-
-[Calculating beam slopes HWN]
-
-John. S. Gourlay. ``A language for music printing'', Communications
-of the ACM, Vol. 29(5), 388--401, 1986.
-
-[This paper describes the MusiCopy musicsetting system and an input
-language to go with it. HWN]
-
-Dorothea Blostein and Lippold Haken, ``The Lime Music Editor: A Diagram
-Editor Involving Complex Translations'', Software Practice and
-Experience, Vol. 24, No. 3, March 1994, pp. 289-306.
-
-[A description of various conversions, decisions and issues relating
-to this interactive editor HWN]
-
-Lippold Haken and Dorothea Blostein, ``The Tilia Music Representation:
-Extensibility, Abstraction, and Notation Contexts for the Lime Music
-Editor'', Computer Music Journal, Vol. 17, No. 3, 1993, pp. 43-58
-
-[A description of Lime internals (which resemble older (before
-0.0.68pre) LilyPond data structures somewhat) HWN]
-
-Lippold Haken and Dorothea Blostein, ``A New Algorithm for Horizontal
-Spacing of Printed Music'', International Computer Music Conference,
-Banff, Sept. 1995, pp. 118-119.
-
-[This describes an algorithm which uses springs between adjacent
-columns. This algorithm is a "subclass" of the LilyPond algorithm. HWN]
-
-Dorothea Blostein and Lippold Haken, ``Justification of Printed Music'',
-Communications of the ACM, VolJ34, No. 3, March 1991, pp. 88-99.
-
-[This paper provides a shallow overview of the algorithm used in LIME
-for spacing individual lines. HWN]
-
-Gary M. Rader. ``Creating Printed Music Automatically''. Computer Vol
-29(6), June 1996, pp 61--69.
-
-[Describes a system called MusicEase, and explains that it uses
-"constraints" (which go unexplained) to automatically position various
-elements. HWN]
-
-Stephen Dowland Page. ``Computer Tools for Music Information
-Retrieval''. Dissertation University of Oxford, 1988.
-
-[Don't ask Stephen for a copy. Write to the Bodleian Library, Oxford,
-or to the British Library, instead. SP]
-
-Ren\'e Roelofs. ``Een Geautomatiseerd Systeem voor het Afdrukken van
-Muziek'' afstudeerscriptie Bestuurlijke informatica, no 45327, Erasmus
-universiteit Rotterdam, 1991. (``An automated system for printing
-music'' Master's Thesis Managerial Computer Science.)
-
-[This dutch thesis describes a simplistic (monophonic) typesetting system,
-and focuses on the breaking algorithm, which is taken from Hegazy &
-Gourlay HWN]
-
-Miguel Filgueiras and Jos\'e Paulo Leal. ``Representation and
-manipulation of music documents in SceX''. Electronic Publishing,
-vol. 6 (4), 507--518, 1993.
-
-Eric Foxley, Music --- A language for typesetting music scores.
-Software --- Practice and Experience, Vol. 17(8), 485--502, 1987.
-
-[A paper on a TROFF preprocessor to typeset music. The output shown is
-not very sophisticated, and contains some typographical atrocities HWN]
-
-Miguel Filgueiras, ``Implementing a Symbolic Music Processing
-System''. LIACC, Universidade do Porto, 1996; submitted.
-
-Miguel Filgueiras, ``Some Music Typesetting Algorithms''. LIACC,
-Universidade do Porto, forthcoming.
-
-=head2 Engraving: further reading
-
-Herbert Chlapik. ``Die Praxis des Notengraphikers''. Doblinger, 1987.
-ISBN 3-9000 035-96-2.
-
-[An clearly written book for the casually interested reader. It shows
-some of the conventions and difficulties in printing music HWN]
-
-The University of Colorado Music Engraving page.
-http://obenamots.cc.colorado.edu/Musicpress/engraving.html
-
-Anthony Donato. Preparing Music Manuscript. Englewood Cliffs:
-Prentice-Hall, 1963.
-
-Donemus. ``Uitgeven van muziek''. Donemus Amsterdam, 1900
-
-George Heussenstamm. The Norton Manual of Music Notation. New York:
-Norton, 1987.
-
-Erdhard Karkoshka. ``Notation in New Music. Trans. Ruth
-Koenig''. Praeger Publishers, New York, 1972. Out of print.
-
-C. Roemer, The Art of Music Copying. Roerick music co., Sherman Oaks
-(CA), 1973.
-
-Glen Rosecrans. Music Notation Primer. New York: Passantino, 1979.
-
-Kurt Stone. Music Notation in the Twentieth Century. New York: Norton,
-1980.
-
-
-=head2 Other stuff
-
-
-More on GNU Music:
-http://dept-info.labri.u-bordeaux.fr/~strandh/Gsharp
-
-Peter S. Langston, ``Unix music tools at Bellcore''. Software ---
-Practice and Experience, Vol. 20(S1), S1/47--S1/61, 1990.
-
-[This paper deals with some command-line tools for music editing and
-playback. It doesn't mention notation issues, but does come with the
-grand idea (not) of using music to monitor complex systems. Imagine
-your nuclear plant supervisor to use AC/DC for checking the reactor HWN]
-
-
-=head2 File formats
-
-Tablature: http://wabakimi.carleton.ca/~phacket2/guitar/tabfaq.html
-
-Cindy Grande, NIFF6a Notation Interchange File Format. Grande
-Software Inc., 1995. ftp://blackbox.cartah.washington.edu/pub/,
-http://www.jtauber.com/music/encoding/niff/
-
-[Specs for NIFF, a comprehensive but binary (yuk) format for notation HWN]
-
-SMDL, Standard Musical Description Language
-ftp://ftp.ornl.gov/pub/sgml/wg8/smdl/10743.pdf
-
-MPDL,
-
-HMSL, Hierarchical Music Structured Language,
-
-DARMS,
-
-enigma,
-
-SCORE,
-
-
-=head1 AUTHORS
-
-References and comments contributed by Han-Wen Nienhuys (HWN), Miguel
-Filgueiras, Mark Basinski (MB), Dorothea Blostein, Stephen Page (SP),
-Jan Nieuwenhuizen, Peter Kerr.
-
-This should really be redone in BibTeX
-
projects / lilypond.git / commitdiff