@menu
* LilyPond internals::
* Overview::
-* mudela::
* Request_engraver::
-* Backend::
* Coding standards::
* Making patches::
* Localisation::
@menu
* Overview:: Overview
-* mudela:: mudela
* Request_engraver:: Request_engraver
@end menu
@unnumberedsubsec Users
Mutopia needs your help. The mutopia project is a collection of public
-domain sheet music. You can help the project by entering music and
-submitting. Point your browser to the
-@uref{http://sca.uwaterloo.ca/Mutopia, Mutopia webpage}
+domain sheet music. You can help the project by entering music (either
+by hand, or by converting from scans or MIDI) and submitting it. Point
+your browser to the @uref{http://sca.uwaterloo.ca/Mutopia, Mutopia
+webpage}.
@unnumberedsubsec Font designers
-Our set of glyphs (the Feta font) is far from complete. If you know a
-little MetaFont you can contribute a glyph
+Our set of glyphs (the Feta font) is far from complete. We need the
+following glyphs: segno, coda. The fonts have been coded in MetaFont,
+so you will need to know MetaFont if you want to contribute a glyph.
@unnumberedsubsec Writers
-The documentation of LilyPond and related utilities needs a lot of work.
+The documentation of LilyPond and related utilities needs a lot of
+work. The documentation is written in
+@uref{http://www.gnu.org/software/texinfo,texinfo}. The documentation of
+LilyPond is sorely lacking in terms of completeness, depth and
+organisation.
+
+Write if you know how to write english documentation in texinfo, and
+know about music and music notation. You must also know how to use
+LilyPond (or be prepared to learn using it). The task is not especially
+hard, but it is a lot of work, and you must be familiar with LilyPond.
@unnumberedsubsec Translators
LilyPond is completely ready for internationalized messages, but there
-are only three translations so far.
+are only a few translations so far (dutch, italian, german, japanese,
+french, russian). Translation involves writing a .po file, which is
+relatively easy, and does not even require running LilyPond.
@unnumberedsubsec Hackers
-There are lots of possibilities of improving the program itself. There are
-both small projects and big ones. Most of them are listed in the TODO
-file. A interesting and very big project is writing a GUI frontend to
-LilyPond.
+There are lots of possibilities of improving the program itself. There
+are both small projects and big ones. Most of them are listed in our
+TODO file, listed on the homepage of Jan and
+@uref{http://www.cs.uu.nl/~hanwen/lily-devel,Han-Wen}. Modifying
+LilyPond almost always requires patches to the C++ part.
+There are also numerous other interesting projects that are more or less
+related to LilyPond
-@chapter LilyPond internals
+@itemize @bullet
+@item Writing convertors, eg. from NIFF and MIDI (we tried writing one with
+limited success: midi2ly, included with lilypond.)
+
+We found that writing them in Python is the easiest.
+
+@item Writing a GUI frontend to
+LilyPond. At the moment @uref{denemo,denemo.sourceforge.net} is the most
+advanced.
+
+@item Helping write @uref{ http://solfege.sourceforge.net/,solfege
+tools}
+
+@item Helping @uref{primrose.sourceforge.net,primrose}, a tool for
+scanning sheet music.
+@end itemize
-This 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 page may be
-a little incoherent. Unfortunately, it is also quite outdated. A
-more thorough and understandable document is in the works.
+@chapter LilyPond internals
-You should use @code{doc++} to take a peek at the sources.
-@node Overview, mudela, Top, Top
+@node Overview, , , Top
@section 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.
+GNU LilyPond is a "multi-pass" system.
@table @samp
@end table
-@node mudela, Request_engraver, Overview, Top
-@section mudela
-
-[FIXME: implementation has been generalised, so this is out of date]
-
-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'
-
-@table @samp
-@item @code{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 @code{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 @code{Rest_req}
- Typeset a rest.
-@item @code{Span_req}
- This type of request typically results in the creation of a @code{Spanner}
-@item @code{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 @code{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 each @code{Dynamic} request carries a time, measured
- from the start of its note.
-@end table
-@node Request_engraver, , mudela, Top
+@node Request_engraver, , , Top
@section Request_engraver
In the previous section the idea of Request has been explained, but
To decide on merging, several engravers have been grouped. Please
check @file{init/engraver.ly}.
-@node Backend, , , Top
-
-
-
-@section The backend of LilyPond
-
-
-
-blah blah blah
-
-@menu
-* Graphic elements:: blah
-* Position and width Callbacks:: blah
-* Score_element properties:: blah
-* Score elements:: blah
-* Items:: blah
-* Spanners:: blah
-* Future work:: blah
-@end menu
-
-
-@node Graphic elements, , , Backend
-
-Music notation is composed of a sets of interrelated glyphs. In
-Lilypond every glyph usually is represented by one object, a so-called
-Graphic Object. The primary relations between graphic objects involve
-positions:
-
-@itemize @asis
-@item consecutive notes are printed left to right, grouped in a staff
-@item simultaneous notes are horizontally aligned (internally grouped in
-a paper column).
-@item the staccato mark is horizontally centered on the note it applies
-to.
-@end itemize
-
-The abstract encoding of such relations is done with the concept
-@dfn{reference point}. The reference point (in X direction) of the
-staccato mark is the note it applies to. The (X) position of the
-staccato mark is stored relative to the position of the note head. This
-means that the staccato will always maintain a fixed offset wrt to the
-note head, whereever the head is moved to.
-
-In the same vein, all notes on a staff have their Y positions stored
-relative to an object that groups the staff. If that object is moved,
-the absolute Y positions of all objects in that spanner change along, in
-effect causing the staff and all its contents to move as a whole.
-
-Each graphic object stores a pointer and an relative offset for each
-direction: one for the X-axis, one for the Y-axis. For example, the X
-parent of a Note_head usually is a Note_column. The X parent of a
-Note_column usually is either a Collision or a Paper_column. The X
-parent of a Collision usually is a Paper_column. If the Collision
-moves, all Note_heads that have that Collision as parent also move, but
-the absolute position of the Paper_column does not change.
-
-To build a graphical score with Graphic_elements, conceptually, one
-needs to have one Root object (in Lilypond: Line_of_score), and
-recursively attach objects to the Root. However, due to the nature
-of the context selection mechanisms, it turns out to be more
-advantageous to construct the tree the other way around: first small
-trees (note heads, barlines etc.) are created, and these are
-subsequently composed into larger trees, which are finally hung on a
-Paper_column (in X direction) or Line_of_score (in Y direction).
-
-The structure of the X,Y parent relations are determined by the
-engravers and notation contexts:
-
-The most important X-axis parent relation depends on the timing: notes
-that come earlier are attached to Paper_column that will be positioned
-more to the left.
-
-The most important Y-axis relation depends on containment of contexts:
-notes (created in a Thread or Voice context) are put in the staff where
-the originating context lives in.
-
-Graphical_axis_groups are special graphic objects, that are designed to
-function as a parent. The size of a Graphical_axis_groups group is the
-union of its children.
-
-@node Position and width Callbacks, , , Backend
-
-The positions are, as explained relative to a parent reference
-point. Most positions are not known when an object is created, so these
-are calculated as needed. This is done by adding a callback for a
-specific direction, eg
-
-@example
- Real
- my_translate (Score_element * ptr, Axis a)
- @{
- return 5.0 PT;
- @}
-
- [..]
- my_element->add_offset_callback (my_translate, Y_AXIS)
-@end example
-
-When a call is made to @code{my_element->relative_position (obj,
-Y_AXIS)}, @code{my_translate} will be called. The result is that
-my_element will be translated up by 5 pt. There are numerous callbacks,
-for example
-@itemize @bullet
-@item to offset element by staff-spaces (See class
-@code{Staff_symbol_referencer}).
-@item to align elements next to other groups of elements (See class
-@code{Side_position_interface})
-@item to
-@end itemize
-
-Offset callbacks can be stacked. The callbacks will be executed in the
-order that they were added.
-
-Width and height are similarly implemted using extent callbacks. There
-can be only one callback for each axis. No callback (the 0 ptr) means:
-"empty in this direction".
-
-@node Score_element properties, , , Backend
-
-Score elements can have other properties besides positioning, for
-example, text strings (for text objects) style settings, glyphs, padding
-settings (for scripts). These settings are stored in element properties.
-
-Properties are stored as GUILE association lists, with symbols as keys.
-Element properties can be accessed using the C++ functions
-
-@example
- SCM get_elt_property (SCM) const;
- void set_elt_property (const char * , SCM val);
- void set_immutable_elt_property (const char * , SCM val);
- void set_immutable_elt_property (SCM key, SCM val);
- void set_elt_property (SCM , SCM val);
- void set_elt_pointer (const char*, SCM val);
- SCM remove_elt_property (const char* nm);
-@end example
-
-All lookup functions identify undefined properties with GUILE
-end-of-list (ie. @code{'()} in Scheme or @code{SCM_EOL} in C)
-
-Implementation wise, there are two kinds of properties:
-
-@itemize @bullet
-@item mutable properties:
-element properties that change from object to object. The storage of
-these are private to a Score element. Typically this is used to store
-lists of pointers to other objects
-
-@item immutable properties:
-element properties that are shared across objects. The storage is
-shared, and hence is read-only. Typically, this is used to store
-function callbacks, and values for shared element properties are read
-from @file{ly/engraver.ly}.
-
-
-
-The following is from lily 1.3.80, and it shows the settings for the bar
-numbers: Bar numbers are breakable, and visible at the beginning of the
-line. The setting for @code{molecule-callback} indicates that Bar_number
-is implemented as a text.
-@example
- basicBarNumberProperties = #`(
- (molecule-callback . ,Text_item::brew_molecule)
- (breakable . #t)
- (visibility-lambda . ,begin-of-line-visible)
- )
-@end example
-@end itemize
-
-
-In 1.3.81 an music expression was added to add to the immutable property
-list, eg. like this:
-
-@example
- \pushproperty #'(basicBarNumberProperties)
- #'visibility-lambda #end-of-line-visible
-@end example
-
-This will add the entry @code{`(visibility-lambda .
-,end-of-line-visible)} to the immutable property list for bar numbers,
-in effect overriding the setting from @file{ly/engraver.ly}. This can be
-undone as follows
-
-@example
- \popproperty #'(basicBarNumberProperties)
- #'visibility-lambda
-@end example
-
-Note that you must accompany these statements with a proper context
-selection in most cases.
-
-
-
-
-
-
-@node Score elements, , , Backend
-
-[FIXME: we want to get rid of dependencies in the implementation.]
-
-Besides relative positions there are lots of other relations between
-elements. Lilypond does not contain other specialized relation
-management (Like the relative positioning code). Instead, objects can
-be connected through dependencies, which sets the order in which objects
-are to be processed.
-
-Example: the direction of a beamed stem should equal the direction of
-the beam. When the stem is a added to the beam, a dependency on the
-beam is set in the stem: this means that @code{Beam::do_pre_processing
-()} (which does various direction related things) will be called before
-@code{Stem::do_pre_processing ()}.
-
-The code that manages dependencies resides in the class
-@code{Score_element}, a derived class of @code{Graphical_element}. The
-bulk of the code handles line breaking related issues.
-
-To sketch the problems with line breaking: suppose a slur spans a line
-break,
-@example
-
-c4( c'''' c | \break d d )d
-
-@end example
-In this case, the slur will appear as two parts, the first part spanning
-the first three notes (the @code{c}s), the second spanning the last
-three (the @code{d}s). Within Lilypond this is modeled as breaking the
-slur in parts: from the Original slur, two new clones of the old slur
-are made. Initially both clones depend on the six notes. After the
-hairy code in Score_element, Spanner and Item which does substitutions
-in sets of dependencies, the first clone depends on the first three
-notes, the second on the last three.
-
-The major derived classes of Score_element are Item and Spanner.
-An item has one horizontal position. A spanner hangs on two items.
-
-@node Items, , , Backend
-@section Items
-
-
-
-An item is a score element that is associated with only one
-Paper_column. Examples are note heads, clefs, super and superscripts, etc.
-Item is a derived class of Score_element.
-
-The shape of an item is known before the break calculations, and line
-spacing depends on the size of items: very wide items need more space
-than very small ones.
-
-An additional complication is the behavior of items at linebreaks. For
-example, when you do a time signature change, you get only one symbol.
-If it occurs at a linebreak, the new time signature must be printed both
-before and after the linebreak. Other `breakable symbols' such as
-clefs, and bar lines also exhibit this behavior.
-
-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. To support this,
-breakable items are generated in the three versions: original
-(unbroken), left (before line break) and right (after line break).
-During the line spacing, these versions are used to try how the spacing
-of a line works out.
-
-Once the definitive spacing is determined, dependencies (and various
-other pointers) are substituted such that all dependencies point at the
-active items: either they point at the original, or they point at left
-and right.
-
-@node Spanners, , , Backend
-@section Spanners
-
-Spanners are symbols that are of variable shape, eg. Slurs, beams, etc.
-Spanners is a derived class of Score_element.
-
-The final shape can only be determined after the line breaking process.
-All spanners are spanned on two items, called the left and right
-boundary item. The X reference point is the left boundary item.
-
-
-@node Future work, , , Backend
-@section Future work
-
-There are plans to unify Spanner and Item, so there will no longer be
-such a clear distinction between the two. Right now, Score_elements are
-always either Item or either Spanner.
-
-@node Coding standards, , , Top
+@node Coding standards, , , Top
@chapter CodingStyle - standards while programming for GNU LilyPond
@unnumberedsubsec Languages
-C++ and Python are preferred. Perl is forbidden. Python code should
-use an indent of 8, using TAB characters.
+C++ and Python are preferred. Python code should use an indent of 8,
+using TAB characters.
@unnumberedsubsec Filenames
Macros should be written completely in uppercase
-The code should not be compilable if proper macro declarations are not
-included.
-
-Don't laugh. It took us a whole evening/night to figure out one of
-these bugs, because we had a macro that looked like
-@code{DECLARE_VIRTUAL_FUNCTIONS ()}.
-
@unnumberedsubsec Broken code
Broken code (hardwired dependencies, hardwired constants, slow
algorithms and obvious limitations) should be marked as such: either
with a verbose TODO, or with a short "ugh" comment.
-@unnumberedsubsec Comments
-
-The source is commented in the DOC++ style. Check out doc++ at
-@uref{http://www.zib.de/Visual/software/doc++/index.html}
-
-@example
-
- /*
- C style comments for multiline comments.
- They come before the thing to document.
- [...]
- */
-
- /**
- short description.
- Long class documentation.
- (Hungarian postfix)
-
- TODO Fix boring_member ()
- */
- class Class @{
- /**
- short description.
- long description
- */
-
- Data data_member_;
-
- /**
- short memo. long doco of member ()
- @@param description of arguments
- @@return Rettype
- */
- Rettype member (Argtype);
-
- /// memo only
- boring_member () @{
- data_member_ = 121; // ugh
- @}
- @};
-
-@end example
-
-
-Unfortunately most of the code isn't really documented that good.
-
@unnumberedsec Hungarian notation naming convention
Proposed is a naming convention derived from the so-called
Use them.
-@node Making patches, , , Top
+@node Making patches, , , Top
@unnumberedsec Track and distribute your code changes
@end example
-@node Localisation, , , Top
+@node Localisation, , , Top
@chapter Localisation - User messages in LilyPond
@example
char const* messages[] = @{
_i ("enable debugging output"),
- _i ("ignore mudela version"),
+ _i ("ignore lilypond version"),
0
@};
projects / lilypond.git / blobdiff