1 @node Internals, , , Top
4 * Conversion stages:: Lilypond is a multi-pass program.
5 * Grobs:: Graphical object
9 * Molecules:: Molecules are stand-alone descriptions of output
12 @node Conversion stages
13 @section Conversion stages
15 When translating the input to notation, there are number of distinct
16 phases. We list them here:
22 The .ly file is read, and converted to a list of @code{Scores}, which
23 each contain @code{Music} and paper/midi-definitions.
25 @item Interpreting music
26 @cindex interpreting music
28 All music events are "read" in the same order as they would be played
29 (or read from paper). At every step of the interpretation, musical
30 events are delivered to
31 interpretation contexts,
33 which use them to build grobs (or MIDI objects, for MIDI output).
39 At places where line breaks may occur, clefs and bars are prepared for
40 a possible line break.
46 In this stage, all information that is needed to determine line breaking
49 @item Break calculation:
51 The lines and horizontal positions of the columns are determined.
55 Relations between all grobs are modified to reflect line breaks. See
56 also @ref{Pointer substitution}.
60 All vertical dimensions and spanning objects are computed, and all grobs
61 are output, line by line.
69 This section is about Grobs (short for Graphical Objects), which are
70 formatting objects used to create the final output. This material is
71 normally the domain of LilyPond gurus, but occasionally, a normal user
72 also has to deal with grobs.
74 The most simple interaction with Grobs are when you use
78 \property Voice.Stem \override #'direction = #1
81 This piece of lily input causes all stem objects to be stem-up
82 henceforth. In effect, you are telling lilypond to extend the defintion
83 of the "Stem" grob with the setting @code{direction := 1}. Of course
84 there are many more ways of customizing Lily output, and since most of
85 them involve Grobs in some form, this section explains some details of
91 * Setting grob properties::
92 * Items and Spanners::
93 * Pointer substitution::
97 @subsection What is a grob?
99 In music notation, lots of symbols are related in some way. You can
100 think of music notation as a graph where nodes are formed by the
101 symbols, and the arcs by their relations. A grob is node in that
102 graph. A grob stores references to other grobs, the directed edges in
105 The objective of this big graph of grobs, is to specify the notation
106 problem. The solution of this problem is a description of the printout
107 that is in closed form, i.e. but a list of values. These values are
108 Molecules. (see @ref{Molecules})
110 All grobs have an X and Y-position on the page. These X and Y positions
111 are stored in a relative format, so they can easily be combined by
112 stacking them, hanging one grob to the side of another, and coupling
113 them into a grouping-grob.
115 Each grob has a reference point, or parent: the position of a grob is
116 stored relative to that reference point. For example the X-reference
117 point of a staccato dot usually is the note head that it applies
118 to. Whenever the note head is moved, the staccato dot moves along
121 If you keep following offset reference points, you will always end up at
122 the root-object. This root object is called @code{Line_of_score}
123 @ref{(lilypond-internals)Element Line_of_score}, and it represents a
124 system (ie. a line of music).
126 All grobs carry a set of grob-properties. In the Stem example above,
127 the property @code{direction} is set to value @code{1}. The function
128 that draws the symbol (@code{Stem::brew_molecule}) uses the value of
129 @code{direction} to determine how to print the stem and the flag. The
130 appearance of a grob is determined solely by the values of its
133 Often, a grob also is associated with a symbol. On the other hand,
134 Some grobs do not print any symbols, but take care of grouping
135 objects. For example, there is a separate grob that stacks staffs
136 vertically, so they are not printed in overstrike. The NoteCollision
137 @ref{(lilypond-internals)Element NoteCollision} is another example of
138 an abstract grob. It only moves around chords, but doesn't print
141 A complete list of grob types is found in
142 @ref{(lilypond-internals)Elements}
144 Grobs are created in the "Interpreting music" phase, by things in
145 LilyPond called engravers. In this phase of the translation, a load of
146 grobs are created, and they are linked into a giant network of objects.
147 This network of grobs forms the "specification" of the print
148 problem. This problem is then solved: configurations, directions,
149 dimensions, line breaks, etc. are calculated. Finally, the printing
150 description in the form of Molecules (@ref{Molecules}) is extracted from
151 the network. These are then dumped into the output file
154 @subsection Callbacks
156 Offsets of grobs are relative to a parent reference point. Most
157 positions are not known when an object is created, so these are
158 calculated as needed. This is done by adding a callback for a specific
161 Suppose you have the following code in a .ly file.
163 #(define (my-callback gr axis)
164 (* 2.0 (get-gr-property grob 'direction))
169 \property Voice.Stem \override #'Y-offset-callbacks = #(list
173 When the Y-offset of a Stem object is needed, LilyPond will
174 automatically execute all callbacks for that object. In this case, it
175 will find @code{my-callback}, and execute that. The result is that the
176 stem is translated by two staff spaces in its direction.
178 (note: Y-offset-callbacks is also a property)
181 Offset callbacks can be stacked, ie.
184 \property .... \override #'Y-offset-callbacks = #(list
185 callback1 callback2 callback3)
189 The callbacks will be executed in the order callback3 callback2
190 callback1. This is used for quantized positioning: the staccato dot is
191 above or below a note head, and it must not be on a staff-line.
193 To achieve this, for the staccato there are two callbacks: one callback
194 that positions the grob above or below the note head, and one callback
195 that rounds the Y-position of the grob to the nearest open space.
197 Similarly, the size of a grob are determined through callbacks, settable
198 with grob properties @code{X-extent-callback} and @code{Y-extent-callback}.
199 There can be only one extent-callback for each axis. No callback (value #f)
200 means: "empty in this direction". If you fill in a pair, that pair
201 hard-codes the extent in that coordinate.
204 @node Setting grob properties
205 @subsection Setting grob properties
207 Grob properties are stored as GUILE association lists, with symbols as
208 keys. From C++, element properties can be accessed using the functions
211 SCM get_grob_property (SCM) const;
212 void set_grob_property (const char * , SCM val);
213 void set_immutable_grob_property (const char * , SCM val);
214 void set_immutable_grob_property (SCM key, SCM val);
215 void set_grob_property (SCM , SCM val);
216 void set_grob_pointer (const char*, SCM val);
217 SCM remove_grob_property (const char* nm);
220 In GUILE, LilyPond provides
223 ly-get-grob-property GROB SYMBOL
224 ly-set-grob-property GROB SYMBOL VALUE
227 All lookup functions identify undefined properties with
228 end-of-list (ie. @code{'()} in Scheme or @code{SCM_EOL} in C)
230 Properties are stored in two ways:
232 @item mutable properties:
233 element properties that change from object to object. The storage of
234 these are private to a grob. Typically this is used to store lists of
235 pointers to other grobs
237 @item immutable properties:
238 element properties that are shared across different grobs of the same
239 type. The storage is shared, and hence it is read-only. Typically, this
240 is used to store function callbacks, and values for shared element
241 properties are read from @file{scm/element-description.scm}.
244 There are two ways to manually set grob properties.
246 You can change immutable grob properties. This is done with the
250 \property Voice.Stem \override #'direction = #1
253 This will push the entry @code{'(direction . 1)} on the immutable
254 property list for stems, in effect overriding the setting from
255 @file{scm/element-description.scm}. This can be undone by
258 \property Voice.stem \revert #'direction
261 If you use this a lot, this gets old quickly. So we also have a
265 \property Context.GrobType \set #'prop = #VAL
268 this does a @code{\revert} followed by a @code{\override}
270 The second way is \outputproperty. This construct looks like
273 \context ContextName \outputproperty @var{pred} #@var{sym} = #@var{val}
276 In this case, in every grob that satisfies @var{pred}, the property
277 assignment @var{sym} = @var{val} is done. For example
281 #(lambda (gr) (string? (ly-get-grob-property gr
283 #'extra-offset = #'(-1.0 . 0.0)
286 This shifts all elements that have a @code{text} property one staff
287 space to the left. This mechanism is rather clumsy to use, but it allows
288 you tweak any setting of any grob.
290 @node Items and Spanners
291 @unnumberedsubsec Items and Spanners
293 Grobs can also be distinguished in their role in the horizontal spacing.
294 A lot of grobs define constraints on the spacing by their sizes. For
295 example, note heads, clefs, stems, and all other symbols with a fixed
296 shape. These grobs form a subtype called @code{Item}.
298 Other grobs have a shape that depends on the horizontal spacing. For
299 example, slur, beam, tie, etc. These grobs form a subtype called
300 @code{Spanner}. All spanners have two span-points (these must be
301 @code{Item}s), one on the left and one on the right. The left bound is
302 also the X-reference point.
304 Some items need special treatment for line breaking. For example, a
305 clef is normally only printed at the start of a line (ie. after a line
306 break). To model this, `breakable' items (clef, key signature, bar lines,
307 etc.) are copied twice. Then we have three versions of each breakable
308 item: one version if there is no line break, one version that is printed
309 before the line break (at the end of a system), one version that is
310 printed after the line break.
312 Whether these versions are visible and take up space, is determined by
313 the outcome of the visibility-lambda. This is a function taking a
314 direction (-1, 0 or 1) and returns a cons of booleans, signifying wether
315 this grob should be transparent and invisible.
317 @node Pointer substitution
318 @unnumberedsubsec Pointer substitution
321 Symbols that cross line-breaks (such as slurs) cause some more
322 complications. When a spanner crosses a line-break, then the spanner is
323 "broken into pieces", for every line that the spanner is in, a copy of
324 the grob is made. A substitution process redirects all grob-reference
325 so that spanner grob will only reference other grobs in the same line.
331 @section Music_iterator
341 @cindex Output description
343 The objective of any typesetting system is to put ink on paper in the
344 right places. For LilyPond, this final stage is left to the TeX and the
345 printer subsystem. For lily, the last stage in processing a score is
346 outputting a description of what to put where. This description roughly
355 you merely have to look at the tex output of lily to see this.
356 Internally these instructions are encoded in Molecules:@footnote{At some
357 point LilyPond also contained Atom-objects, but they have been replaced
358 by Scheme expressions.}. A molecule is an object that combines
359 dimension information (how large is this glyph ?) with
362 Conceptually, Molecules can be constructed from Scheme code, by
363 translating a Molecule and by combining two molecules. In BNF
367 Molecule = COMBINE Molecule Molecule
368 | TRANSLATE Offset Molecule
373 If you are interested in seeing how this information is stored, you
374 can run with the @code{-f scm} option. The scheme expressions are then
375 dumped onto the output file.
377 (refer to the C++ code for more details). All visible,
378 ie. non-transparant, grobs have a callback to create a Molecule. The
379 name of the property is @code{molecule-callback}, and its value should
380 be a Scheme function taking one argument (the grob) and returning a
385 @node Development, , , top
392 * Helping with development::
395 @node CodingStyle, , , Development
396 @section CodingStyle - standards while programming for GNU LilyPond
398 As a general rule, you should always try to continue computations, even
399 if there is some kind of error. When the program stops, it is often very
400 hard for a user to pinpoint what part of the input causes an
401 error. Finding the culprit is much easier if there is some viewable
404 So functions and methods do not return errorcodes, they never crash, but
405 report a programming_error and try to carry on.
407 @unnumberedsubsec Languages
409 C++ and Python are preferred. Python code should use an indent of 8,
410 using TAB characters.
412 @unnumberedsubsec Filenames
414 Definitions of classes that are only accessed via pointers
415 (*) or references (&) shall not be included as include files.
421 ".cc" Implementation files
422 ".icc" Inline definition files
423 ".tcc" non inline Template defs
429 (setq auto-mode-alist
430 (append '(("\\.make$" . makefile-mode)
431 ("\\.cc$" . c++-mode)
432 ("\\.icc$" . c++-mode)
433 ("\\.tcc$" . c++-mode)
434 ("\\.hh$" . c++-mode)
435 ("\\.pod$" . text-mode)
441 The class Class_name is coded in @file{class-name.*}
443 @unnumberedsubsec Indentation
445 Standard GNU coding style is used. In emacs:
448 (add-hook 'c++-mode-hook
449 '(lambda() (c-set-style "gnu")
454 If you like using font-lock, you can also add this to your @file{.emacs}:
457 (setq font-lock-maximum-decoration t)
458 (setq c++-font-lock-keywords-3
460 c++-font-lock-keywords-3
461 '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
462 ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
466 @unnumberedsubsec Classes and Types
472 @unnumberedsubsec Members
476 Type Class::member_type_
477 Type Class::member_type ()
480 the @code{type} is a Hungarian notation postfix for @code{Type}. See below
482 @unnumberedsubsec Macros
484 Macro names should be written in uppercase completely.
486 @unnumberedsubsec Broken code
488 Try not to write broken code. This includes hardwired dependencies,
489 hardwired constants, slow algorithms and obvious limitations. If you can
490 not avoid it, mark the place clearly, and add a comment explaining
491 shortcomings of the code.
493 @unnumberedsec Hungarian notation naming convention
495 The C++ part of LilyPond uses a naming convention derived from the
496 so-called @emph{Hungarian Notation}. Macros, @code{enum}s and
497 @code{const}s are all uppercase, with the parts of the names separated
500 The hungarian notation is to be used when variables are not declared
501 near usage (mostly in member variables and functions).
503 @unnumberedsubsec Types
507 unsigned char. (The postfix _by is ambiguous)
521 Zero terminated c string
526 @unnumberedsubsec User defined types
536 Slur* slur_p = new Slur;
540 @unnumberedsubsec Modifiers
542 The following types modify the meaning of the prefix.
543 These are preceded by the prefixes:
551 const. Note that the proper order is @code{Type const}
552 and not @code{const Type}
554 A const pointer. This would be equivalent to @code{_c_l}, but since any
555 "const" pointer has to be a link (you can't delete a const pointer),
558 temporary pointer to object (link)
560 pointer to newed object
565 @unnumberedsubsec Adjective
567 Adjectives such as global and static should be spelled out in full.
568 They come before the noun that they refer to, just as in normal english.
572 foo_global_i: a global variable of type int commonly called "foo".
576 static class members do not need the static_ prefix in the name (the
577 Class::var notation usually makes it clear that it is static)
581 Variable loop: an integer
583 Temporary variable: an unsigned integer
585 Variable test: a character
586 @item @code{first_name_str}
587 Variable first_name: a String class object
588 @item @code{last_name_ch_a}
589 Variable last_name: a @code{char} array
591 Variable foo: an @code{Int*} that you must delete
593 Variable bar: an @code{Int*} that you must not delete
596 Generally default arguments are taboo, except for nil pointers.
598 The naming convention can be quite conveniently memorised, by
599 expressing the type in english, and abbreviating it
603 static Array<int*> foo
607 @code{foo} can be described as "the static int-pointer user-array", so you get
616 @unnumberedsec Miscellaneous
618 For some tasks, some scripts are supplied, notably creating patches, a
619 mirror of the website, generating the header to put over cc and hh
620 files, doing a release.
624 @node Making patches, , , Development
625 @section Making patches
627 @unnumberedsec Track and distribute your code changes
629 This page documents how to distribute your changes to GNU lilypond
631 We would like to have unified context diffs with full pathnames. A
632 script automating supplied with Lily.
634 Distributing a change normally goes like this:
637 @item make your fix/add your code
638 @item Add changes to CHANGES, and add yourself to Documentation/topdocs/AUTHORS.texi
639 @item generate a patch,
640 @item e-mail your patch to one of the mailing lists
641 gnu-music-discuss@@gnu.org or bug-gnu-music@@gnu.org
644 Please do not send entire files, even if the patch is bigger than the
645 original. A patch makes it clear what is changed, and it won't
646 overwrite previous (not yet released) changes.
648 @unnumberedsec Generating a patch
653 make -C lilypond-x.y.z/ distclean
654 make -C lilypond-x.y.z.NEW/ distclean
655 diff -urN lilypond-x.y.z/ lilypond-x.y.z.NEW/
658 Complicated (but automated) version:
660 In @file{VERSION}, set MY_PATCH_LEVEL:
670 In @file{CHANGES}, enter a summary of changes:
676 * A concise, yet clearly readable description of what changed.
680 Then, from the top of Lily's source tree, type
686 These handy python scripts assume a directory structure which looks
691 lilypond -> lilypond-x.y.z # symlink to development directory
692 lilypond-x.y.z/ # current development
693 patches/ # patches between different releases
694 releases/ # .tar.gz releases
698 @unnumberedsec Applying patches
700 [outdated: please use xdeltas]
702 If you're following LilyPond development regularly, you probably want to
703 download just the patch for each subsequent release.
704 After downloading the patch (into the patches directory, of course), simply
709 gzip -dc ../patches/lilypond-0.1.74.diff.gz | patch -p1 -E
713 and don't forget to make automatically generated files:
717 autoconf footnote(patches don't include automatically generated files,
718 i.e. file(configure) and files generated by file(configure).)
724 @node Localisation, , , Development
725 @section Localisation - User messages in LilyPond
727 This document provides some guidelines for uniformising user messages.
728 In the absence of other standards, we'll be using these rules when coding
729 for LilyPond. Hopefully, this can be replaced by general GNU
730 guidelines in the future.
732 Not-preferred messages are marked with @code{+}. By convention,
733 agrammatical examples are marked with @code{*}.
735 @subsection Guidelines
740 Every message to the user should be localised (and thus be marked
741 for localisation). This includes warning and error messages.
744 Don't localise/gettextify:
747 @item @code{programming_error ()}s
748 @item @code{programming_warning ()}s
750 @item output strings (PostScript, TeX)
754 Messages to be localised must be encapsulated in @code{_ (STRING)}
755 or @code{_f (FORMAT, ...)}. Eg:
758 warning (_ ("Need music in a score"));
759 error (_f ("Can't open file: `%s'", file_name));
762 In some rare cases you may need to call @code{gettext ()} by hand.
763 This happens when you pre-define (a list of) string constants for later
764 use. In that case, you'll probably also need to mark these string
765 constants for translation, using @code{_i (STRING)}. The @code{_i}
766 macro is a no-op, it only serves as a marker for @file{xgettext}.
769 char const* messages[] = @{
770 _i ("enable debugging output"),
771 _i ("ignore lilypond version"),
778 puts (gettext (messages [i]));
783 @file{flower/getopt-long.cc} and @file{lily/main.cc}.
786 Don't use leading or trailing whitespace in messages.
789 Messages containing a final verb, or a gerund (@code{-ing}-form)
790 always start with a capital. Other (simpler) messages start with
794 The word `foo' is not declared.
796 Not declaring: `foo'.
800 To avoid having a number of different messages for the same situation,
801 we'll use quoting like this @code{"message: `%s'"} for all strings.
802 Numbers are not quoted:
805 _f ("Can't open file: `%s'", name_str)
806 _f ("Can't find charater number: %d", i)
810 Think about translation issues. In a lot of cases, it is better to
811 translate a whole message. The english grammar mustn't be imposed on
812 the translator. So, iso
815 _ ("Stem at ") + moment.str () + _(" doen't fit in beam")
822 _f ("Stem at %s doen't fit in beam", moment.str ())
826 Split up multi-sentence messages, whenever possible. Instead of
829 warning (_f ("out of tune! Can't find: `%s', "Key_engraver"));
831 warning (_f ("Can't find font `%s', loading default",
839 warning (_ ("out of tune:");
840 warning (_f ("Can't find: `%s', "Key_engraver"));
842 warning (_f ("Can't find font: `%s', font_name));
843 warning (_f ("Loading default font"));
847 If you must have multiple-sentence messages, use full punctuation.
848 Use two spaces after end of sentence punctuation.
849 No punctuation (esp. period) is used at the end of simple messages.
852 _f ("Non-matching braces in text `%s', adding braces", text)
853 _ ("Debug output disabled. Compiled with NPRINT.")
854 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
858 Don't modularise too much; a lot of words cannot be translated
860 It's probably safe to treat most occurences of words like
861 stem, beam, crescendo as separately translatable words.
864 When translating, it is preferrable to put interesting information
865 at the end of the message, rather than embedded in the middle.
866 This especially applies to frequently used messages, even if this
867 would mean sacrificing a bit of eloquency. This holds for original
868 messages too, of course.
871 en: can't open: `foo.ly'
872 + nl: kan `foo.ly' niet openen (1)
873 kan niet openen: `foo.ly'* (2)
874 niet te openen: `foo.ly'* (3)
877 The first nl message, although gramatically and stylishly correct,
878 is not friendly for parsing by humans (even if they speak dutch).
879 I guess we'd prefer something like (2) or (3).
882 Please don't run make po/po-update with GNU gettext < 0.10.35
886 @node Helping with development, , , Development
888 @chapter Getting involved
890 If you want to help developing LilyPond your efforts are appreciated.
891 You can help LilyPond in several ways. Not all tasks requiring
892 programming or understanding the full source code.
894 Please don't expect us to give you instructions on what you should
895 do. We're just a bunch of simple hackers, and we're absolutely
896 incompetent about management, design in advance, delegating work.
897 Some people write to us "I want to help, what should I do?", but we
898 never know what to answer them.
900 If you want to hack, just start hacking. You can send us the result as
901 a patch, and we'll gladly incorporate it.
903 If you need some hints on where to get started: there are a number of
904 specific areas where you could do work.
906 @unnumberedsubsec Users
908 Mutopia needs your help. The mutopia project is a collection of public
909 domain sheet music. You can help the project by entering music (either
910 by hand, or by converting from scans or MIDI) and submitting it. Point
911 your browser to the @uref{http://sca.uwaterloo.ca/Mutopia, Mutopia
914 @unnumberedsubsec Writers
916 The documentation of LilyPond and related utilities needs a lot of
917 work. The documentation is written in
918 @uref{http://www.gnu.org/software/texinfo,texinfo}. The documentation of
919 LilyPond is sorely lacking in terms of completeness, depth and
922 Write if you know how to write english documentation in texinfo, and
923 know about music and music notation. You must also know how to use
924 LilyPond (or be prepared to learn using it). The task is not especially
925 hard, but it is a lot of work, and you must be familiar with LilyPond.
927 @unnumberedsubsec Translators
929 LilyPond is completely ready for internationalized messages, but there
930 are only a few translations so far (dutch, italian, german, japanese,
931 french, russian). Translation involves writing a .po file, which is
932 relatively easy, and does not even require running LilyPond.
934 @unnumberedsubsec Hackers
936 There are lots of possibilities of improving the program itself. There
937 are both small projects and big ones. Most of them are listed in our
938 TODO file, listed on the homepage of Jan and
939 @uref{http://www.cs.uu.nl/~hanwen/lily-devel,Han-Wen}. Modifying
940 LilyPond almost always requires patches to the C++ part.
942 There are also numerous other interesting projects that are more or less
946 @item Writing convertors, eg. from NIFF and MIDI (we tried writing one with
947 limited success: midi2ly, included with lilypond.)
949 We found that writing them in Python is the easiest.
951 @item Writing a GUI frontend to
952 LilyPond. At the moment @uref{denemo,denemo.sourceforge.net} is the most
955 @item Helping write @uref{http://solfege.sourceforge.net/,solfege
958 @item Helping @uref{primrose.sourceforge.net,primrose}, a tool for
959 scanning sheet music.