1 @node Internals, , , top
4 * Conversion stages:: Lilypond is a multi-pass program.
6 * Grobs:: Graphical object
10 * Molecules:: Molecules are stand-alone descriptions of output
14 @node Conversion stages, , , Internals
16 When translating the input to notation, there are number of distinct
17 phases. We list them here:
24 The .ly file is read, and converted to a list of @code{Scores}, which
25 each contain @code{Music} and paper/midi-definitions.
27 @item Interpreting music
29 All music events are "read" in the same order as they would be played
30 (or read from paper). At every step of the interpretation, musical
31 events are delivered to
32 interpretation contexts,
34 which use them to build grobs (or MIDI objects, for MIDI output).
38 At places where line breaks may occur, clefs and bars are prepared for
39 a possible line break.
43 In this stage, all information that is needed to determine line breaking
46 @item Break calculation:
48 The lines and horizontal positions of the columns are determined.
52 Relations between all grobs are modified to reflect line breaks. See
53 also @ref{Pointer substitution}.
57 All vertical dimensions and spanning objects are computed, and all grobs
58 are output, line by line.
63 @node Grobs, , , Internals
66 This section is about Grobs (short for Graphical Objects), which are
67 formatting objects used to create the final output. This material is
68 normally the domain of LilyPond gurus, but occasionally, a normal user
69 also has to deal with grobs.
71 The most simple interaction with Grobs are when you use
75 \property Voice.Stem \override #'direction = #1
78 This piece of lily input causes all stem objects to be stem-up
79 henceforth. In effect, you are telling lilypond to extend the defintion
80 of the "Stem" grob with the setting @code{direction := 1}. Of course
81 there are many more ways of customizing Lily output, and since most of
82 them involve Grobs in some form, this section explains some details of
88 * Setting grob properties::
89 * Items and Spanners::
90 * Pointer substitution::
93 @node What is a grob?, , , Grobs
95 In music notation, lots of symbols are related in some way. You can
96 think of music notation as a graph where nodes are formed by the
97 symbols, and the arcs by their relations. A grob is node in that
98 graph. A grob stores references to other grobs, the directed edges in
101 The objective of this big graph of grobs, is to specify the notation
102 problem. The solution of this problem is a description of the printout
103 that is in closed form, i.e. but a list of values. These values are
104 Molecules. (see @ref{Molecules})
106 All grobs have an X and Y-position on the page. These X and Y positions
107 are stored in a relative format, so they can easily be combined by
108 stacking them, hanging one grob to the side of another, and coupling
109 them into a grouping-grob.
111 Each grob has a reference point, or parent: the position of a grob is
112 stored relative to that reference point. For example the X-reference
113 point of a staccato dot usually is the note head that it applies
114 to. Whenever the note head is moved, the staccato dot moves along
117 If you keep following offset reference points, you will always end up at
118 the root-object. This root object is called @code{Line_of_score}
119 @ref{(lilypond-internals)Element Line_of_score}, and it represents a
120 system (ie. a line of music).
122 All grobs carry a set of grob-properties. In the Stem example above,
123 the property @code{direction} is set to value @code{1}. The function
124 that draws the symbol (@code{Stem::brew_molecule}) uses the value of
125 @code{direction} to determine how to print the stem and the flag. The
126 appearance of a grob is determined solely by the values of its
129 Often, a grob also is associated with a symbol. On the other hand,
130 Some grobs do not print any symbols, but take care of grouping
131 objects. For example, there is a separate grob that stacks staffs
132 vertically, so they are not printed in overstrike. The NoteCollision
133 @ref{(lilypond-internals)Element NoteCollision} is another example of
134 an abstract grob. It only moves around chords, but doesn't print
137 A complete list of grob types is found in
138 @ref{(lilypond-internals)Elements}
140 Grobs are created in the "Interpreting music" phase, by things in
141 LilyPond called engravers. In this phase of the translation, a load of
142 grobs are created, and they are linked into a giant network of objects.
143 This network of grobs forms the "specification" of the print
144 problem. This problem is then solved: configurations, directions,
145 dimensions, line breaks, etc. are calculated. Finally, the printing
146 description in the form of Molecules (@ref{Molecules}) is extracted from
147 the network. These are then dumped into the output file
149 @node Callbacks, , , Grobs
151 Offsets of grobs are relative to a parent reference point. Most
152 positions are not known when an object is created, so these are
153 calculated as needed. This is done by adding a callback for a specific
156 Suppose you have the following code in a .ly file.
158 #(define (my-callback gr axis)
159 (* 2.0 (get-gr-property grob 'direction))
164 \property Voice.Stem \override #'Y-offset-callbacks = #(list
168 When the Y-offset of a Stem object is needed, LilyPond will
169 automatically execute all callbacks for that object. In this case, it
170 will find @code{my-callback}, and execute that. The result is that the
171 stem is translated by two staff spaces in its direction.
173 (note: Y-offset-callbacks is also a property)
176 Offset callbacks can be stacked, ie.
179 \property .... \override #'Y-offset-callbacks = #(list
180 callback1 callback2 callback3)
184 The callbacks will be executed in the order callback3 callback2
185 callback1. This is used for quantized positioning: the staccato dot is
186 above or below a note head, and it must not be on a staff-line.
188 To achieve this, for the staccato there are two callbacks: one callback
189 that positions the grob above or below the note head, and one callback
190 that rounds the Y-position of the grob to the nearest open space.
192 Similarly, the size of a grob are determined through callbacks, settable
193 with grob properties @code{X-extent-callback} and @code{Y-extent-callback}.
194 There can be only one extent-callback for each axis. No callback (value #f)
195 means: "empty in this direction". If you fill in a pair, that pair
196 hard-codes the extent in that coordinate.
199 @node Setting grob properties, , , Grobs
201 Grob properties are stored as GUILE association lists, with symbols as
202 keys. From C++, element properties can be accessed using the functions
205 SCM get_grob_property (SCM) const;
206 void set_grob_property (const char * , SCM val);
207 void set_immutable_grob_property (const char * , SCM val);
208 void set_immutable_grob_property (SCM key, SCM val);
209 void set_grob_property (SCM , SCM val);
210 void set_grob_pointer (const char*, SCM val);
211 SCM remove_grob_property (const char* nm);
214 In GUILE, LilyPond provides
217 ly-get-grob-property GROB SYMBOL
218 ly-set-grob-property GROB SYMBOL VALUE
221 All lookup functions identify undefined properties with
222 end-of-list (ie. @code{'()} in Scheme or @code{SCM_EOL} in C)
224 Properties are stored in two ways:
226 @item mutable properties:
227 element properties that change from object to object. The storage of
228 these are private to a grob. Typically this is used to store lists of
229 pointers to other grobs
231 @item immutable properties:
232 element properties that are shared across different grobs of the same
233 type. The storage is shared, and hence it is read-only. Typically, this
234 is used to store function callbacks, and values for shared element
235 properties are read from @file{scm/element-description.scm}.
238 There are two ways to manually set grob properties.
240 You can change immutable grob properties. This is done with the
244 \property Voice.Stem \override #'direction = #1
247 This will push the entry @code{'(direction . 1)} on the immutable
248 property list for stems, in effect overriding the setting from
249 @file{scm/element-description.scm}. This can be undone by
252 \property Voice.stem \revert #'direction
255 If you use this a lot, this gets old quickly. So we also have a
259 \property Context.GrobType \set #'prop = #VAL
262 this does a @code{\revert} followed by a @code{\override}
264 The second way is \outputproperty. This construct looks like
267 \context ContextName \outputproperty @var{pred} #@var{sym} = #@var{val}
270 In this case, in every grob that satisfies @var{pred}, the property
271 assignment @var{sym} = @var{val} is done. For example
275 #(lambda (gr) (string? (ly-get-grob-property gr
277 #'extra-offset = #'(-1.0 . 0.0)
280 This shifts all elements that have a @code{text} property one staff
281 space to the left. This mechanism is rather clumsy to use, but it allows
282 you tweak any setting of any grob.
284 @node Items and Spanners, , , Grobs
285 @unnumberedsubsec Items and Spanners
287 Grobs can also be distinguished in their role in the horizontal spacing.
288 A lot of grobs define constraints on the spacing by their sizes. For
289 example, note heads, clefs, stems, and all other symbols with a fixed
290 shape. These grobs form a subtype called @code{Item}.
292 Other grobs have a shape that depends on the horizontal spacing. For
293 example, slur, beam, tie, etc. These grobs form a subtype called
294 @code{Spanner}. All spanners have two span-points (these must be
295 @code{Item}s), one on the left and one on the right. The left bound is
296 also the X-reference point.
298 Some items need special treatment for line breaking. For example, a
299 clef is normally only printed at the start of a line (ie. after a line
300 break). To model this, `breakable' items (clef, key signature, bar lines,
301 etc.) are copied twice. Then we have three versions of each breakable
302 item: one version if there is no line break, one version that is printed
303 before the line break (at the end of a system), one version that is
304 printed after the line break.
306 Whether these versions are visible and take up space, is determined by
307 the outcome of the visibility-lambda. This is a function taking a
308 direction (-1, 0 or 1) and returns a cons of booleans, signifying wether
309 this grob should be transparent and invisible.
311 @node Pointer substitution, , , Grobs
312 @unnumberedsubsec Pointer substitution
315 Symbols that cross line-breaks (such as slurs) cause some more
316 complications. When a spanner crosses a line-break, then the spanner is
317 "broken into pieces", for every line that the spanner is in, a copy of
318 the grob is made. A substitution process redirects all grob-reference
319 so that spanner grob will only reference other grobs in the same line.
321 @node Engraver, , , Internals
323 @node Music_iterator, , , Internals
325 @node Music, , , Internals
327 @node Molecules, , , Internals
329 The objective of any typesetting system is to put ink on paper in the
330 right places. For LilyPond, this final stage is left to the TeX and the
331 printer subsystem. For lily, the last stage in processing a score is
332 outputting a description of what to put where. This description roughly
341 you merely have to look at the tex output of lily to see this.
342 Internally these instructions are encoded in Molecules:@footnote{At some
343 point LilyPond also contained Atom-objects, but they have been replaced
344 by Scheme expressions.}. A molecule is an object that combines
345 dimension information (how large is this glyph ?) with
348 Conceptually, Molecules can be constructed from Scheme code, by
349 translating a Molecule and by combining two molecules. In BNF notation:
352 Molecule = COMBINE Molecule Molecule
353 | TRANSLATE Offset Molecule
358 (refer to the C++ code for more details). All visible,
359 ie. non-transparent, grobs have a callback to create a Molecule. The
360 name of the property is @code{molecule-callback}, and its value should
361 be a Scheme function taking one argument (the grob) and returning a
366 @node Development, , , top
375 @node CodingStyle, , , Development
376 @section CodingStyle - standards while programming for GNU LilyPond
378 As a general rule, you should always try to continue computations, even
379 if there is some kind of error. When the program stops, it is often very
380 hard for a user to pinpoint what part of the input causes an
381 error. Finding the culprit is much easier if there is some viewable
384 So functions and methods do not return errorcodes, they never crash, but
385 report a programming_error and try to carry on.
387 @unnumberedsubsec Languages
389 C++ and Python are preferred. Python code should use an indent of 8,
390 using TAB characters.
392 @unnumberedsubsec Filenames
394 Definitions of classes that are only accessed via pointers
395 (*) or references (&) shall not be included as include files.
401 ".cc" Implementation files
402 ".icc" Inline definition files
403 ".tcc" non inline Template defs
409 (setq auto-mode-alist
410 (append '(("\\.make$" . makefile-mode)
411 ("\\.cc$" . c++-mode)
412 ("\\.icc$" . c++-mode)
413 ("\\.tcc$" . c++-mode)
414 ("\\.hh$" . c++-mode)
415 ("\\.pod$" . text-mode)
421 The class Class_name is coded in @file{class-name.*}
423 @unnumberedsubsec Indentation
425 Standard GNU coding style is used. In emacs:
428 (add-hook 'c++-mode-hook
429 '(lambda() (c-set-style "gnu")
434 If you like using font-lock, you can also add this to your @file{.emacs}:
437 (setq font-lock-maximum-decoration t)
438 (setq c++-font-lock-keywords-3
440 c++-font-lock-keywords-3
441 '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
442 ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
446 @unnumberedsubsec Classes and Types
452 @unnumberedsubsec Members
456 Type Class::member_type_
457 Type Class::member_type ()
460 the @code{type} is a Hungarian notation postfix for @code{Type}. See below
462 @unnumberedsubsec Macros
464 Macro names should be written in uppercase completely.
466 @unnumberedsubsec Broken code
468 Try not to write broken code. This includes hardwired dependencies,
469 hardwired constants, slow algorithms and obvious limitations. If you can
470 not avoid it, mark the place clearly, and add a comment explaining
471 shortcomings of the code.
473 @unnumberedsec Hungarian notation naming convention
475 The C++ part of LilyPond uses a naming convention derived from the
476 so-called @emph{Hungarian Notation}. Macros, @code{enum}s and
477 @code{const}s are all uppercase, with the parts of the names separated
480 The hungarian notation is to be used when variables are not declared
481 near usage (mostly in member variables and functions).
483 @unnumberedsubsec Types
487 unsigned char. (The postfix _by is ambiguous)
501 Zero terminated c string
506 @unnumberedsubsec User defined types
516 Slur* slur_p = new Slur;
520 @unnumberedsubsec Modifiers
522 The following types modify the meaning of the prefix.
523 These are preceded by the prefixes:
531 const. Note that the proper order is @code{Type const}
532 and not @code{const Type}
534 A const pointer. This would be equivalent to @code{_c_l}, but since any
535 "const" pointer has to be a link (you can't delete a const pointer),
538 temporary pointer to object (link)
540 pointer to newed object
545 @unnumberedsubsec Adjective
547 Adjectives such as global and static should be spelled out in full.
548 They come before the noun that they refer to, just as in normal english.
552 foo_global_i: a global variable of type int commonly called "foo".
556 static class members do not need the static_ prefix in the name (the
557 Class::var notation usually makes it clear that it is static)
561 Variable loop: an integer
563 Temporary variable: an unsigned integer
565 Variable test: a character
566 @item @code{first_name_str}
567 Variable first_name: a String class object
568 @item @code{last_name_ch_a}
569 Variable last_name: a @code{char} array
571 Variable foo: an @code{Int*} that you must delete
573 Variable bar: an @code{Int*} that you must not delete
576 Generally default arguments are taboo, except for nil pointers.
578 The naming convention can be quite conveniently memorised, by
579 expressing the type in english, and abbreviating it
583 static Array<int*> foo
587 @code{foo} can be described as "the static int-pointer user-array", so you get
596 @unnumberedsec Miscellaneous
598 For some tasks, some scripts are supplied, notably creating patches, a
599 mirror of the website, generating the header to put over cc and hh
600 files, doing a release.
604 @node Making patches, , , Development
607 @unnumberedsec Track and distribute your code changes
609 This page documents how to distribute your changes to GNU lilypond
611 We would like to have unified context diffs with full pathnames. A
612 script automating supplied with Lily.
614 Distributing a change normally goes like this:
617 @item make your fix/add your code
618 @item Add changes to CHANGES, and add yourself to Documentation/topdocs/AUTHORS.texi
619 @item generate a patch,
620 @item e-mail your patch to one of the mailing lists
621 gnu-music-discuss@@gnu.org or bug-gnu-music@@gnu.org
624 Please do not send entire files, even if the patch is bigger than the
625 original. A patch makes it clear what is changed, and it won't
626 overwrite previous (not yet released) changes.
628 @unnumberedsec Generating a patch
633 make -C lilypond-x.y.z/ distclean
634 make -C lilypond-x.y.z.NEW/ distclean
635 diff -urN lilypond-x.y.z/ lilypond-x.y.z.NEW/
638 Complicated (but automated) version:
640 In @file{VERSION}, set MY_PATCH_LEVEL:
650 In @file{CHANGES}, enter a summary of changes:
656 * A concise, yet clearly readable description of what changed.
660 Then, from the top of Lily's source tree, type
666 These handy python scripts assume a directory structure which looks
671 lilypond -> lilypond-x.y.z # symlink to development directory
672 lilypond-x.y.z/ # current development
673 patches/ # patches between different releases
674 releases/ # .tar.gz releases
678 @unnumberedsec Applying patches
680 [outdated: please use xdeltas]
682 If you're following LilyPond development regularly, you probably want to
683 download just the patch for each subsequent release.
684 After downloading the patch (into the patches directory, of course), simply
689 gzip -dc ../patches/lilypond-0.1.74.diff.gz | patch -p1 -E
693 and don't forget to make automatically generated files:
697 autoconf footnote(patches don't include automatically generated files,
698 i.e. file(configure) and files generated by file(configure).)
704 @node Localisation, , , Development
706 @chapter Localisation - User messages in LilyPond
708 @section Introduction
710 This document provides some guidelines for uniformising user messages.
711 In the absence of other standards, we'll be using these rules when coding
712 for LilyPond. Hopefully, this can be replaced by general GNU
713 guidelines in the future.
715 Not-preferred messages are marked with @code{+}. By convention,
716 agrammatical examples are marked with @code{*}.
723 Every message to the user should be localised (and thus be marked
724 for localisation). This includes warning and error messages.
727 Don't localise/gettextify:
730 @item @code{programming_error ()}s
731 @item @code{programming_warning ()}s
733 @item output strings (PostScript, TeX)
737 Messages to be localised must be encapsulated in @code{_ (STRING)}
738 or @code{_f (FORMAT, ...)}. Eg:
741 warning (_ ("Need music in a score"));
742 error (_f ("Can't open file: `%s'", file_name));
745 In some rare cases you may need to call @code{gettext ()} by hand.
746 This happens when you pre-define (a list of) string constants for later
747 use. In that case, you'll probably also need to mark these string
748 constants for translation, using @code{_i (STRING)}. The @code{_i}
749 macro is a no-op, it only serves as a marker for @file{xgettext}.
752 char const* messages[] = @{
753 _i ("enable debugging output"),
754 _i ("ignore lilypond version"),
761 puts (gettext (messages [i]));
766 @file{flower/getopt-long.cc} and @file{lily/main.cc}.
769 Don't use leading or trailing whitespace in messages.
772 Messages containing a final verb, or a gerund (@code{-ing}-form)
773 always start with a capital. Other (simpler) messages start with
777 The word `foo' is not declared.
779 Not declaring: `foo'.
783 To avoid having a number of different messages for the same situation,
784 we'll use quoting like this @code{"message: `%s'"} for all strings.
785 Numbers are not quoted:
788 _f ("Can't open file: `%s'", name_str)
789 _f ("Can't find charater number: %d", i)
793 Think about translation issues. In a lot of cases, it is better to
794 translate a whole message. The english grammar mustn't be imposed on
795 the translator. So, iso
798 _ ("Stem at ") + moment.str () + _(" doen't fit in beam")
805 _f ("Stem at %s doen't fit in beam", moment.str ())
809 Split up multi-sentence messages, whenever possible. Instead of
812 warning (_f ("out of tune! Can't find: `%s', "Key_engraver"));
814 warning (_f ("Can't find font `%s', loading default",
822 warning (_ ("out of tune:");
823 warning (_f ("Can't find: `%s', "Key_engraver"));
825 warning (_f ("Can't find font: `%s', font_name));
826 warning (_f ("Loading default font"));
830 If you must have multiple-sentence messages, use full punctuation.
831 Use two spaces after end of sentence punctuation.
832 No punctuation (esp. period) is used at the end of simple messages.
835 _f ("Non-matching braces in text `%s', adding braces", text)
836 _ ("Debug output disabled. Compiled with NPRINT.")
837 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
841 Don't modularise too much; a lot of words cannot be translated
843 It's probably safe to treat most occurences of words like
844 stem, beam, crescendo as separately translatable words.
847 When translating, it is preferrable to put interesting information
848 at the end of the message, rather than embedded in the middle.
849 This especially applies to frequently used messages, even if this
850 would mean sacrificing a bit of eloquency. This holds for original
851 messages too, of course.
854 en: can't open: `foo.ly'
855 + nl: kan `foo.ly' niet openen (1)
856 kan niet openen: `foo.ly'* (2)
857 niet te openen: `foo.ly'* (3)
860 The first nl message, although gramatically and stylishly correct,
861 is not friendly for parsing by humans (even if they speak dutch).
862 I guess we'd prefer something like (2) or (3).
865 Please don't run make po/po-update with GNU gettext < 0.10.35