1 @node Internals, , , top
4 * Conversion stages:: Lilypond is a multi-pass program.
6 * Grobs:: Graphical object
10 * Molecule:: Molecule 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{Molecule}) 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 Molecule, , , 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 @section CodingStyle - standards while programming for GNU LilyPond
377 As a general rule, you should always try to continue computations, even
378 if there is some kind of error. When the program stops, it is often very
379 hard for a user to pinpoint what part of the input causes an
380 error. Finding the culprit is much easier if there is some viewable
383 So functions and methods do not return errorcodes, they never crash, but
384 report a programming_error and try to carry on.
386 @unnumberedsubsec Languages
388 C++ and Python are preferred. Python code should use an indent of 8,
389 using TAB characters.
391 @unnumberedsubsec Filenames
393 Definitions of classes that are only accessed via pointers
394 (*) or references (&) shall not be included as include files.
400 ".cc" Implementation files
401 ".icc" Inline definition files
402 ".tcc" non inline Template defs
408 (setq auto-mode-alist
409 (append '(("\\.make$" . makefile-mode)
410 ("\\.cc$" . c++-mode)
411 ("\\.icc$" . c++-mode)
412 ("\\.tcc$" . c++-mode)
413 ("\\.hh$" . c++-mode)
414 ("\\.pod$" . text-mode)
420 The class Class_name is coded in @file{class-name.*}
422 @unnumberedsubsec Indentation
424 Standard GNU coding style is used. In emacs:
427 (add-hook 'c++-mode-hook
428 '(lambda() (c-set-style "gnu")
433 If you like using font-lock, you can also add this to your @file{.emacs}:
436 (setq font-lock-maximum-decoration t)
437 (setq c++-font-lock-keywords-3
439 c++-font-lock-keywords-3
440 '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
441 ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
445 @unnumberedsubsec Classes and Types
451 @unnumberedsubsec Members
455 Type Class::member_type_
456 Type Class::member_type ()
459 the @code{type} is a Hungarian notation postfix for @code{Type}. See below
461 @unnumberedsubsec Macros
463 Macro names should be written in uppercase completely.
465 @unnumberedsubsec Broken code
467 Try not to write broken code. This includes hardwired dependencies,
468 hardwired constants, slow algorithms and obvious limitations. If you can
469 not avoid it, mark the place clearly, and add a comment explaining
470 shortcomings of the code.
472 @unnumberedsec Hungarian notation naming convention
474 The C++ part of LilyPond uses a naming convention derived from the
475 so-called @emph{Hungarian Notation}. Macros, @code{enum}s and
476 @code{const}s are all uppercase, with the parts of the names separated
479 The hungarian notation is to be used when variables are not declared
480 near usage (mostly in member variables and functions).
482 @unnumberedsubsec Types
486 unsigned char. (The postfix _by is ambiguous)
500 Zero terminated c string
505 @unnumberedsubsec User defined types
515 Slur* slur_p = new Slur;
519 @unnumberedsubsec Modifiers
521 The following types modify the meaning of the prefix.
522 These are preceded by the prefixes:
530 const. Note that the proper order is @code{Type const}
531 and not @code{const Type}
533 A const pointer. This would be equivalent to @code{_c_l}, but since any
534 "const" pointer has to be a link (you can't delete a const pointer),
537 temporary pointer to object (link)
539 pointer to newed object
544 @unnumberedsubsec Adjective
546 Adjectives such as global and static should be spelled out in full.
547 They come before the noun that they refer to, just as in normal english.
551 foo_global_i: a global variable of type int commonly called "foo".
555 static class members do not need the static_ prefix in the name (the
556 Class::var notation usually makes it clear that it is static)
560 Variable loop: an integer
562 Temporary variable: an unsigned integer
564 Variable test: a character
565 @item @code{first_name_str}
566 Variable first_name: a String class object
567 @item @code{last_name_ch_a}
568 Variable last_name: a @code{char} array
570 Variable foo: an @code{Int*} that you must delete
572 Variable bar: an @code{Int*} that you must not delete
575 Generally default arguments are taboo, except for nil pointers.
577 The naming convention can be quite conveniently memorised, by
578 expressing the type in english, and abbreviating it
582 static Array<int*> foo
586 @code{foo} can be described as "the static int-pointer user-array", so you get
595 @unnumberedsec Miscellaneous
597 For some tasks, some scripts are supplied, notably creating patches, a
598 mirror of the website, generating the header to put over cc and hh
599 files, doing a release.
603 @node Making patches, , , Top
606 @unnumberedsec Track and distribute your code changes
608 This page documents how to distribute your changes to GNU lilypond
610 We would like to have unified context diffs with full pathnames. A
611 script automating supplied with Lily.
613 Distributing a change normally goes like this:
616 @item make your fix/add your code
617 @item Add changes to CHANGES, and add yourself to Documentation/topdocs/AUTHORS.texi
618 @item generate a patch,
619 @item e-mail your patch to one of the mailing lists
620 gnu-music-discuss@@gnu.org or bug-gnu-music@@gnu.org
623 Please do not send entire files, even if the patch is bigger than the
624 original. A patch makes it clear what is changed, and it won't
625 overwrite previous (not yet released) changes.
627 @unnumberedsec Generating a patch
632 make -C lilypond-x.y.z/ distclean
633 make -C lilypond-x.y.z.NEW/ distclean
634 diff -urN lilypond-x.y.z/ lilypond-x.y.z.NEW/
637 Complicated (but automated) version:
639 In @file{VERSION}, set MY_PATCH_LEVEL:
649 In @file{CHANGES}, enter a summary of changes:
655 * A concise, yet clearly readable description of what changed.
659 Then, from the top of Lily's source tree, type
665 These handy python scripts assume a directory structure which looks
670 lilypond -> lilypond-x.y.z # symlink to development directory
671 lilypond-x.y.z/ # current development
672 patches/ # patches between different releases
673 releases/ # .tar.gz releases
677 @unnumberedsec Applying patches
679 [outdated: please use xdeltas]
681 If you're following LilyPond development regularly, you probably want to
682 download just the patch for each subsequent release.
683 After downloading the patch (into the patches directory, of course), simply
688 gzip -dc ../patches/lilypond-0.1.74.diff.gz | patch -p1 -E
692 and don't forget to make automatically generated files:
696 autoconf footnote(patches don't include automatically generated files,
697 i.e. file(configure) and files generated by file(configure).)
703 @node Localisation, , , Top
705 @chapter Localisation - User messages in LilyPond
707 @section Introduction
709 This document provides some guidelines for uniformising user messages.
710 In the absence of other standards, we'll be using these rules when coding
711 for LilyPond. Hopefully, this can be replaced by general GNU
712 guidelines in the future.
714 Not-preferred messages are marked with @code{+}. By convention,
715 agrammatical examples are marked with @code{*}.
722 Every message to the user should be localised (and thus be marked
723 for localisation). This includes warning and error messages.
726 Don't localise/gettextify:
729 @item @code{programming_error ()}s
730 @item @code{programming_warning ()}s
732 @item output strings (PostScript, TeX)
736 Messages to be localised must be encapsulated in @code{_ (STRING)}
737 or @code{_f (FORMAT, ...)}. Eg:
740 warning (_ ("Need music in a score"));
741 error (_f ("Can't open file: `%s'", file_name));
744 In some rare cases you may need to call @code{gettext ()} by hand.
745 This happens when you pre-define (a list of) string constants for later
746 use. In that case, you'll probably also need to mark these string
747 constants for translation, using @code{_i (STRING)}. The @code{_i}
748 macro is a no-op, it only serves as a marker for @file{xgettext}.
751 char const* messages[] = @{
752 _i ("enable debugging output"),
753 _i ("ignore lilypond version"),
760 puts (gettext (messages [i]));
765 @file{flower/getopt-long.cc} and @file{lily/main.cc}.
768 Don't use leading or trailing whitespace in messages.
771 Messages containing a final verb, or a gerund (@code{-ing}-form)
772 always start with a capital. Other (simpler) messages start with
776 The word `foo' is not declared.
778 Not declaring: `foo'.
782 To avoid having a number of different messages for the same situation,
783 we'll use quoting like this @code{"message: `%s'"} for all strings.
784 Numbers are not quoted:
787 _f ("Can't open file: `%s'", name_str)
788 _f ("Can't find charater number: %d", i)
792 Think about translation issues. In a lot of cases, it is better to
793 translate a whole message. The english grammar mustn't be imposed on
794 the translator. So, iso
797 _ ("Stem at ") + moment.str () + _(" doen't fit in beam")
804 _f ("Stem at %s doen't fit in beam", moment.str ())
808 Split up multi-sentence messages, whenever possible. Instead of
811 warning (_f ("out of tune! Can't find: `%s', "Key_engraver"));
813 warning (_f ("Can't find font `%s', loading default",
821 warning (_ ("out of tune:");
822 warning (_f ("Can't find: `%s', "Key_engraver"));
824 warning (_f ("Can't find font: `%s', font_name));
825 warning (_f ("Loading default font"));
829 If you must have multiple-sentence messages, use full punctuation.
830 Use two spaces after end of sentence punctuation.
831 No punctuation (esp. period) is used at the end of simple messages.
834 _f ("Non-matching braces in text `%s', adding braces", text)
835 _ ("Debug output disabled. Compiled with NPRINT.")
836 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
840 Don't modularise too much; a lot of words cannot be translated
842 It's probably safe to treat most occurences of words like
843 stem, beam, crescendo as separately translatable words.
846 When translating, it is preferrable to put interesting information
847 at the end of the message, rather than embedded in the middle.
848 This especially applies to frequently used messages, even if this
849 would mean sacrificing a bit of eloquency. This holds for original
850 messages too, of course.
853 en: can't open: `foo.ly'
854 + nl: kan `foo.ly' niet openen (1)
855 kan niet openen: `foo.ly'* (2)
856 niet te openen: `foo.ly'* (3)
859 The first nl message, although gramatically and stylishly correct,
860 is not friendly for parsing by humans (even if they speak dutch).
861 I guess we'd prefer something like (2) or (3).
864 Please don't run make po/po-update with GNU gettext < 0.10.35