=head1 NAME
-LilyGuts - doco to the internals of LilyPond
+LilyGuts - doco to the internals of GNU LilyPond
=head1 DESCRIPTION
-This page documents some aspects of the internals of LilyPond. Some of
+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
+You should use doc++ to take a peek at the sources.
+
+[have to do more doco; see TODO]
+
=head1 OVERVIEW
-LilyPond is a "5-pass" system:
+GNU LilyPond is a "5-pass" system:
-=over 5
+=over 4
=item 1. Parsing:
=item 2. Processing:
-Requests are processed and granted. In this step data-structures for
-3. are created and filled with data: PScore, PCol, PStaff
+Requests are processed and granted. This is done by three cooperating
+structeres: Staff, Staff_walker and Staff_column. In this step
+data-structures for 3. are created and filled with data: PScore, PCol,
+PStaff
=item 3. Calculation:
=back
-=head1 REQUESTS
-
-[see F<request.hh>]
+Some of the important requests are:
-Any Voice_element can do a number of requests. A request is done
-to the C<Staff> which contains the C<Voice_element>. The staff 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)
-
-Please refer to the documentation of the Child classes of
-C<Request> for explanation of each request type.
-
-The result of a request will be an C<Item> or a C<Spanner>, which
-will be put on a C<PStaff>. Note that the C<PStaff> and the original
-C<Staff> need not have anything in common. For example, the
-``double'' piano Staff could interpret commands which juggle
-melodies across the left and right hand, and may put the result in
-two five-line PStaffs (maybe with extra PStaffs to carry the dynamic
-signs and any lyric.
-
-The class C<Staff> should be thought as a container for the
-C<Voice>s, and an interpreter for C<Request>s and C<Command>s.
-Different staffs can produce different outputs; a melodious voice
-which is put into a percussion-Staff, will be typeset as the rythm of
-that voice.
-
-After C<Staff> made up her mind, the resultant items and
-spanners are put on the PScore.
-
-=over 5
+=over 4
=item C<Barcheck_req>
=item C<Rest_req>
-Why a request? It might be a good idea to not typeset the rest, if the
-paper is too crowded.
+Typeset a rest.
=item C<Span_req>
=item C<Beam_req>
+Start/stop a beam.
+
Staff 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.
note, therefore fore each C<Dynamic> request carries a time, measured
from the start of its note.
-This subfield would come in handy, if LilyPond was adapted for midi
-support.
+=head2 Voice
-=back
+=head2 Voice_element
-=head1 COMMANDS
+=head2 Voice groups
+=head1 Requests
-This table decribes the proper order for the different commands:
+inc
+The result of a request will be an C<Item> or a C<Spanner>, which
+will be put on a C<PStaff>. Note that the C<PStaff> and the original
+C<Staff> need not have anything in common. For example, the
+``double'' piano Staff could interpret commands which juggle
+melodies across the left and right hand, and may put the result in
+two five-line PStaffs (maybe with extra PStaffs to carry the dynamic
+signs and any lyric.
+
+The class C<Staff> should be thought as a container for the
+C<Voice>s, and an interpreter for C<Request>s.
+Different staffs can produce different outputs; a melodious voice
+which is put into a percussion-Staff, will be typeset as the rythm of
+that voice.
+
+After C<Staff> made up her mind, the resultant items and
+spanners are put on the PScore.
-=head2 interpret
+=head1 Request_register
- which priority
- ========================
-
- key 200
- clef 190
- meter 180
- bar 170
+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 is Staff (actually, it's child
+C<Complex_staff>). It uses the C<Request_register> to do most of the
+work. For each request C<Complex_staff> queries so-called
+C<Request_register>s if they want to accept a request eg, the
+C<Notehead_register> will accept C<Note_req>s, and turn down
+C<Slur_req>s. If C<Complex_staff> cannot find a register that wants
+the request, it is junked (with a warning message).
+
+After all requests have been either assigned, or junked, the Register
+will process the requests (which usually means creating an C<Item> or
+C<Spanner>). If a C<Request_register> creates something, it tells
+C<Complex_staff>. If all requests have been processed, then each
+Register is notified of any created Staff_element.
+
+=head2 example:
+
+ c4
-=head2 typeset
+produces:
- which priority
- ========================
+ note_request (duration 1/4)
+ stem_request (duration 1/4)
- bar 100
- clef 90
- currentclef 80
- key 70
- currentkey 60
- meter 40
+note_request will be taken by a C<Notehead_register>, stem_request
+will be taken by a C<Stem_beam_register>. C<Notehead_register> creates
+a C<Notehead>, C<Stem_beam_register> creates a C<Stem>. Both announce
+this to the Staff. Staff will tell C<Stem_beam_register> about the
+C<Notehead>, which will add the C<Notehead> to the C<Stem> it just
+created.
+To decide on merging, C<Complex_staff> has grouped several
+registers. There are a few groups:
+
+=item *
+
+Staff wide, contains
+
+ Local_key_register
+ Bar_register
+ Key_register
+ Meter_register
+ Clef_register
+
+=item *
+
+Voice group, contains
+
+ Stem_beam_register
+ Script_register
+ Text_register
+
+=item *
+
+Voice, contains
+
+ Slur_register
+ Notehead_register
+
+
+=item 1
=head1 BREAKING
\discretionary{bar meter}{clef meter}{ bar meter }
-In Lilypond, we have the same concepts (and the same
+In GNU Lilypond, we have the same concepts (and the same
terminology). Each (nonrhythmic) symbol is typeset using a Command
(code: TYPESET). At a breakpoint, TYPESET commands can be grouped
using separators (in lower case):
as you can see, these distance are conflicting. So instead of
satisfying all those ideals simultaneously, a compromise is sought.
-This is Columbus' egg: LilyPond attaches "springs" to each
+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
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. LilyPond also uses the
-concept of pre- and post-breaks.
+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 POINTERS
-
-This describes the ownership of certain classes in LilyPond. +
-signifies a "list of". (This is not complete)
-
- Score:
- Paperdef
- Staff+
- Score_commands
- Score_columns+
- PScore
-
- Staff:
- Voice
- Staff_column+
- Command+
-
-
- Voice:
- Voice_element
-
- Voice_element:
- Request+
-
-
- PScore:
- PStaff+
- PCol+
- Idealspacing+
- Item+
- Spanner+
- Spanner+ (broken)
-
=head1 SEE ALSO
=head2 References
[partly by Mark Basinski <basinski@arizona.edu>]
-Herbert Chlapik,
+Herbert Chlapik, Die Praxis des Notengraphikers. Doblinger, 1987.
+
+Helene Wanske, ?, Schott-Verlag Mainz.
+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.
+
W.A. Hegazy and J. S. Gourlay. Optimal line breaking in music. In
``Document Manipulation and Typography'', J.C. van Vliet (ed) 1988.
Miami, FL 33139
(305) 532-5461
-[This is about *engraving* i.e. professional music typesetting, and includes
+[This is about I<engraving> i.e. professional music typesetting, and includes
some good spacing tables]
Read, Gardner. ``Modern Rhythmic Notation.'' Indiana University Press, 1978.
universiteit Rotterdam, 1991. (``An automated system for printing
music'' Master's Thesis Management and Computer Science.)
-C. Roemer, The Art of Music Copying. Roerick music co., Sherman Oaks (CA), 1973.
+C. Roemer, The Art of Music Copying. Roerick music co., Sherman Oaks
+(CA), 1973.
Rosecrans, Glen. Music Notation Primer. New York: Passantino, 1979.
Stone, Kurt. Music Notation in the Twentieth Century. New York: Norton, 1980.
+=head2 On typesettig programs
+
+From: Miguel Filgueiras <mig@ncc.up.pt>
+
+... as well as other systems. I contribute with some references:
+
+
+D. Blostein, L. Haken, The Lime Music Editor: a Diagram Editor
+Involving Complex Translations. {\em
+Software --- Practice and Experience}, Vol. 24(3), 289--306, 1994.
+
+Alexander Brinkman, {\em PASCAL Programming for Music Research}.
+The University of Chicago Press, 1990.
+
+Miguel Filgueiras, Implementing a Symbolic Music Processing
+System. LIACC, Universidade do Porto, 1996; submitted.
+
+Miguel Filgueiras, Some Music Typesetting Algorithms. LIACC,
+Universidade do Porto, {\em forthcoming}.
+
+ Miguel Filgueiras and Jos\'e Paulo Leal, A First Formulation of
+\SceX, a Music Typesetting System. Centro de Inform\'atica da
+Universidade do Porto, 1993.
+
+Miguel Filgueiras and Jos\'e Paulo Leal. Representation and
+manipulation of music documents in \SceX. {\em Electronic Publishing},
+vol. 6 (4), 507--518, 1993.
+
+Eric Foxley, Music --- A language for typesetting music scores. {\em
+Software --- Practice and Experience}, Vol. 17(8), 485--502, 1987.
+
+John S. Gourlay, A language for music printing. {\em Communications of
+the ACM}, Vol. 29(5), 388--401, 1986.
+
+Cindy Grande, NIFF6a Notation Interchange File Format.
+Grande Software Inc., 1995. {\tt ftp:blackbox.cartah.washington.edu}
+
+Fran\c{c}ois Jalbert, Mu\TeX\ User's Guide (Version $1.1$). Computer
+Science Department, University of British Columbia, 1989.
+
+Peter S. Langston, Unix music tools at Bellcore. {\em
+Software --- Practice and Experience}, Vol. 20(S1), S1/47--S1/61, 1990.
+
+Andreas Mahling, J. Herczeg, M. Herczeg and S<H.-D.> B\"ocker, Beyond
+visualization: knowing and understanding. In P.~Gorny, M.~J. Tauber
+(eds.), {\em Visualization in Human-Computer Interaction}, Lecture
+Notes in Computer Science, 439, 16--26, Springer-Verlag, 1990.
+
+Jan Nieuwenhuizen, Using \TeX\ and the MusiX\TeX\ macro package to
+write parts and scores of music. Department of Physics, Eindhoven
+University of Technology, 1995.
+
+Don Simons, PMX, A Preprocessor for MusiX\TeX\ (Version 1.04).
+dsimons@logicon.com.
+
+Daniel Taupin. Music\TeX: Using \TeX\ to Write Polyphonic or
+Instrumental Music (Version 5.17). Laboratoire de Physique des
+Solides, Centre Universitaire, Orsay, 1996.
+
+Daniel Taupin, Ross Mitchell and Andreas Egler, Musix\TeX: Using \TeX\
+to Write Polyphonic or Instrumental Music (Version T.64). Laboratoire
+de Physique des Solides, Centre Universitaire, Orsay, 1993.
+
+Barry Vercoe, Csound --- A Manual for the Audio Processing System and
+Supporting Programs with Tutorials. Media Lab, M.I.T., Cambridge,
+Massachusetts, 1986 (rev. 1992).
+
+Chris Walshaw, {\tt ABC2M\TeX} --- An easy way of transcribing folk
+and traditional music. School of Maths, University of Greenwich, 1993.
+
+
projects / lilypond.git / blobdiff