1 \input texinfo @c -*-texinfo-*-
2 @setfilename internals.info
3 @settitle LilyPond internals
6 @node Top, LilyPond internals, (dir), (dir)
11 * LilyPond internals::
19 @node LilyPond internals, , Top, Top
23 * Request_engraver:: Request_engraver
27 @chapter Getting involved
29 Please help us make LilyPond a better program. You can help LilyPond in
30 several ways. Not all tasks requiring programming or understanding the
31 full source code. You can write to the mailing list
32 (@email{gnu-music-discuss@@gnu.org} for more information)
34 @unnumberedsubsec Users
36 Mutopia needs your help. The mutopia project is a collection of public
37 domain sheet music. You can help the project by entering music (either
38 by hand, or by converting from scans or MIDI) and submitting it. Point
39 your browser to the @uref{http://sca.uwaterloo.ca/Mutopia, Mutopia
42 @unnumberedsubsec Font designers
44 Our set of glyphs (the Feta font) is far from complete. We need the
45 following glyphs: segno, coda. The fonts have been coded in MetaFont,
46 so you will need to know MetaFont if you want to contribute a glyph.
48 @unnumberedsubsec Writers
50 The documentation of LilyPond and related utilities needs a lot of
51 work. The documentation is written in
52 @uref{http://www.gnu.org/software/texinfo,texinfo}. The documentation of
53 LilyPond is sorely lacking in terms of completeness, depth and
56 Write if you know how to write english documentation in texinfo, and
57 know about music and music notation. You must also know how to use
58 LilyPond (or be prepared to learn using it). The task is not especially
59 hard, but it is a lot of work, and you must be familiar with LilyPond.
61 @unnumberedsubsec Translators
63 LilyPond is completely ready for internationalized messages, but there
64 are only a few translations so far (dutch, italian, german, japanese,
65 french, russian). Translation involves writing a .po file, which is
66 relatively easy, and does not even require running LilyPond.
68 @unnumberedsubsec Hackers
70 There are lots of possibilities of improving the program itself. There
71 are both small projects and big ones. Most of them are listed in our
72 TODO file, listed on the homepage of Jan and
73 @uref{http://www.cs.uu.nl/~hanwen/lily-devel,Han-Wen}. Modifying
74 LilyPond almost always requires patches to the C++ part.
76 There are also numerous other interesting projects that are more or less
80 @item Writing convertors, eg. from NIFF and MIDI (we tried writing one with
81 limited success: midi2ly, included with lilypond.)
83 We found that writing them in Python is the easiest.
85 @item Writing a GUI frontend to
86 LilyPond. At the moment @uref{denemo,denemo.sourceforge.net} is the most
89 @item Helping write @uref{ http://solfege.sourceforge.net/,solfege
92 @item Helping @uref{primrose.sourceforge.net,primrose}, a tool for
97 @chapter LilyPond internals
100 @node Overview, , , Top
103 GNU LilyPond is a "multi-pass" system.
109 No difficult algorithms. The .ly file is read, and converted to a list
110 of @code{Scores}, which each contain @code{Music} and paper/midi-definitions.
112 @item Interpreting music
114 The music is walked through in time-order. The iterators which do the
115 walking report Music to Translators which use this information to
116 create elements, either MIDI or "visual" elements. The translators
117 form a hierarchy; the ones for paper output are Engravers, for MIDI
120 The translators swallow Music (mostly atomic gobs called Requests),
121 create elements, broadcast them to other translators on higher or same
122 level in the hierarchy:
124 The stem of a voice A is broadcast to the staff which contains A, but
125 not to the stems, beams and noteheads of a different voice (say B) or
126 a different staff. The stem and noteheads of A are coupled, because
127 the the Note_heads_engraver broadcasts its heads, and the Stem_engraver catches
130 The engraver which agrees to handle a request decides whether to to
131 honor the request, ignore it, or merge it with other requests. Merging
132 of requests is preferably done with other requests done by members of
133 the same voicegroups (beams, brackets, stems). In this way you can put
134 the voices of 2 instruments in a conductor's score so they make chords
135 (the Beam requests of both instruments will be merged).
139 Breakable stuff (eg. clefs and bars) are copied into pre and
144 Some dependencies are resolved, such as the direction of stems, beams,
145 and "horizontal" placement issues (the order of clefs, keys etc,
146 placement of chords in multi-voice music),
148 @item Break calculation:
150 The lines and horizontal positions of the columns are determined.
154 Through some magical interactions with Line_of_score and Super_elem
155 (check out the source) the "lines" are produced.
157 All other spanners can figure across which lines they are spread. If
158 applicable, they break themselves into pieces. After this, each piece
159 (or, if there are no pieces, the original spanner itself) throws out
160 any dependencies which are in the wrong line.
164 Some items and all spanners need computation after the Paper_column
165 positions are determined. Examples: slurs, vertical positions of
173 @node Request_engraver, , , Top
174 @section Request_engraver
176 In the previous section the idea of Request has been explained, but
177 this only solves one half of the problem. The other half is deciding
178 which requests should be honored, which should merged with other
179 requests, and which should be ignored. Consider this input
183 \type Staff < % chord
184 @{ \meter 2/4; [c8 c8] @}
185 @{\meter 2/4; [e8 e8] @}
190 Both the cs and es are part of a staff (they are in the same
191 Voice_group), so they should share meters, but the two [ ] pairs
194 The judge in this "allocation" problem a set of brokers: the requests
195 are transmitted to so-called engravers which respond if they want to
196 accept a request eg, the @code{Notehead_engraver} will accept
197 @code{Note_req}s, and turn down @code{Slur_req}s. If the Music_iterator
198 cannot find a engraver that wants the request, it is junked (with a
201 After all requests have been either assigned, or junked, the Engraver
202 will process the requests (which usually means creating an @code{Item}
203 or @code{Spanner}). If a @code{Request_engraver} creates something, it
204 tells the enclosing context. If all items/spanners have been created,
205 then each Engraver is notified of any created Score_element, via a
208 @unnumberedsubsec example:
220 Note_request (duration 1/4)
221 Stem_request (duration 1/4)
225 Note_request will be taken by a @code{Notehead_engraver}, stem_request
226 will be taken by a @code{Stem_beam_engraver}. @code{Notehead_engraver}
227 creates a @code{Notehead}, @code{Stem_beam_engraver} creates a
228 @code{Stem}. Both announce this to the Staff_engraver. Staff_engraver
229 will tell @code{Stem_beam_engraver} about the @code{Notehead}, which
230 will add the @code{Notehead} to the @code{Stem} it just created.
232 To decide on merging, several engravers have been grouped. Please
233 check @file{init/engraver.ly}.
235 @node Coding standards, , , Top
237 @chapter CodingStyle - standards while programming for GNU LilyPond
239 Functions and methods do not return errorcodes: they never crash, but
240 report a programming_error and try to carry on.q
243 @unnumberedsubsec Languages
245 C++ and Python are preferred. Perl is forbidden. Python code should
246 use an indent of 8, using TAB characters.
248 @unnumberedsubsec Filenames
250 Definitions of classes that are only accessed via pointers
251 (*) or references (&) shall not be included as include files.
257 ".cc" Implementation files
258 ".icc" Inline definition files
259 ".tcc" non inline Template defs
265 (setq auto-mode-alist
266 (append '(("\\.make$" . makefile-mode)
267 ("\\.cc$" . c++-mode)
268 ("\\.icc$" . c++-mode)
269 ("\\.tcc$" . c++-mode)
270 ("\\.hh$" . c++-mode)
271 ("\\.pod$" . text-mode)
277 The class Class_name_abbreviation is coded in @file{class-name-abbr.*}
279 @unnumberedsubsec Indentation
281 Standard GNU coding style is used. In emacs:
284 (add-hook 'c++-mode-hook
285 '(lambda() (c-set-style "gnu")
290 If you like using font-lock, you can also add this to your @file{.emacs}:
293 (setq font-lock-maximum-decoration t)
294 (setq c++-font-lock-keywords-3
296 c++-font-lock-keywords-3
297 '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
298 ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
302 @unnumberedsubsec Classes and Types
308 @unnumberedsubsec Members
312 Type Class::member_type_
313 Type Class::member_type ()
316 the @code{type} is a Hungarian notation postfix for @code{Type}. See below
318 @unnumberedsubsec Macros
320 Macros should be written completely in uppercase
322 @unnumberedsubsec Broken code
324 Broken code (hardwired dependencies, hardwired constants, slow
325 algorithms and obvious limitations) should be marked as such: either
326 with a verbose TODO, or with a short "ugh" comment.
328 @unnumberedsec Hungarian notation naming convention
330 Proposed is a naming convention derived from the so-called
331 @emph{Hungarian Notation}. Macros, @code{enum}s and @code{const}s are all
332 uppercase, with the parts of the names separated by underscores.
334 The hungarian notation is to be used when variables are not declared
335 near usage (mostly in member variables and functions).
337 @unnumberedsubsec Types
341 unsigned char. (The postfix _by is ambiguous)
355 Zero terminated c string
360 @unnumberedsubsec User defined types
368 Slur* slur_p = new Slur;
372 @unnumberedsubsec Modifiers
374 The following types modify the meaning of the prefix.
375 These are preceded by the prefixes:
383 const. Note that the proper order is @code{Type const}
384 i.s.o. @code{const Type}
386 A const pointer. This would be equivalent to @code{_c_l}, but since any
387 "const" pointer has to be a link (you can't delete a const pointer),
390 temporary pointer to object (link)
392 pointer to newed object
397 @unnumberedsubsec Adjective
399 Adjectives such as global and static should be spelled out in full.
400 They come before the noun that they refer to, just as in normal english.
404 foo_global_i: a global variable of type int commonly called "foo".
408 static class members do not need the static_ prefix in the name (the
409 Class::var notation usually makes it clear that it is static)
413 Variable loop: an integer
415 Temporary variable: an unsigned integer
417 Variable test: a character
418 @item @code{first_name_str}
419 Variable first_name: a String class object
420 @item @code{last_name_ch_a}
421 Variable last_name: a @code{char} array
423 Variable foo: an @code{Int*} that you must delete
425 Variable bar: an @code{Int*} that you must not delete
428 Generally default arguments are taboo, except for nil pointers.
430 The naming convention can be quite conveniently memorised, by
431 expressing the type in english, and abbreviating it
435 static Array<int*> foo
439 @code{foo} can be described as "the static int-pointer user-array", so you get
448 @unnumberedsec Miscellaneous
450 For some tasks, some scripts are supplied, notably creating patches, a
451 mirror of the website, generating the header to put over cc and hh
452 files, doing a release.
456 @node Making patches, , , Top
459 @unnumberedsec Track and distribute your code changes
461 This page documents how to distribute your changes to GNU lilypond
463 We would like to have unified context diffs with full pathnames. A
464 script automating supplied with Lily.
466 Distributing a change normally goes like this:
469 @item make your fix/add your code
470 @item Add changes to CHANGES, and add yourself to Documentation/topdocs/AUTHORS.texi
471 @item generate a patch,
472 @item e-mail your patch to one of the mailing lists
473 gnu-music-discuss@@gnu.org or bug-gnu-music@@gnu.org
476 Please do not send entire files, even if the patch is bigger than the
477 original. A patch makes it clear what is changed, and it won't
478 overwrite previous (not yet released) changes.
480 @unnumberedsec Generating a patch
485 make -C lilypond-x.y.z/ distclean
486 make -C lilypond-x.y.z.NEW/ distclean
487 diff -urN lilypond-x.y.z/ lilypond-x.y.z.NEW/
490 Complicated (but automated) version:
492 In @file{VERSION}, set MY_PATCH_LEVEL:
502 In @file{CHANGES}, enter a summary of changes:
509 Then, from the top of Lily's source tree, type
515 These handy python scripts assume a directory structure which looks
520 lilypond -> lilypond-x.y.z # symlink to development directory
521 lilypond-x.y.z/ # current development
522 patches/ # patches between different releases
523 releases/ # .tar.gz releases
527 (Some scripts also assume this lives in @file{$HOME/usr/src}).
530 @unnumberedsec Applying patches
533 If you're following LilyPond development regularly, you probably want to
534 download just the patch for each subsequent release.
535 After downloading the patch (into the patches directory, of course), simply
540 gzip -dc ../patches/lilypond-0.1.74.diff.gz | patch -p1 -E
544 and don't forget to make automatically generated files:
548 autoconf footnote(patches don't include automatically generated files,
549 i.e. file(configure) and files generated by file(configure).)
555 @node Localisation, , , Top
557 @chapter Localisation - User messages in LilyPond
559 @section Introduction
561 This document provides some guidelines for uniformising user messages.
562 In the absence of other standards, we'll be using these rules when coding
563 for for LilyPond@footnote{
564 In addition to the C++ coding standards that come with Lily
565 }. Hopefully, this can be replaced by general GNU
566 guidelines in the future.
568 Not-preferred messages are marked with @code{+}.
569 By convention, agrammatical examples are marked with @code{*}.
577 Every message to the user should be localised (and thus be marked
578 for localisation). This includes warning and error messages.
581 Don't localise/gettextify:
584 @item @code{programming_error ()}s
585 @item @code{programming_warning ()}s
587 @item output strings (PostScript, TeX)@footnote{
588 This may seem ridiculously obvious, however, makeinfo-3.12s localises
589 output strings. Sending bug report now ---jcn
596 Messages to be localised must be encapsulated in @code{_ (STRING)}
597 or @code{_f (FORMAT, ...)}. Eg:
600 warning (_ ("Need music in a score"));
601 error (_f ("Can't open file: `%s'", file_name));
604 In some rare cases you may need to call @code{gettext ()} by hand.
605 This happens when you pre-define (a list of) string constants for later
606 use. In that case, you'll probably also need to mark these string
607 constants for translation, using @code{_i (STRING)}. The @code{_i}
608 macro is a no-op, it only serves as a marker for @file{xgettext}.
611 char const* messages[] = @{
612 _i ("enable debugging output"),
613 _i ("ignore lilypond version"),
620 puts (gettext (messages [i]));
625 @file{flower/getopt-long.cc} and @file{lily/main.cc}.
628 Don't use leading or trailing whitespace in messages.
631 Messages containing a final verb, or a gerund (@code{-ing}-form)
632 always start with a capital. Other (simpler) messages start with
636 The word `foo' is not declared.
638 Not declaring: `foo'.
642 To avoid having a number of different messages for the same situation,
643 we'll use quoting like this @code{"message: `%s'"} for all strings.
644 Numbers are not quoted:
647 _f ("Can't open file: `%s'", name_str)
648 _f ("Can't find charater number: %d", i)
652 Think about translation issues.
653 In a lot of cases,it's better to translate a whole message.
654 The english grammar mustn't be imposed on the translator.
658 _ ("Stem at ") + moment.str () + _(" doen't fit in beam")
665 _f ("Stem at %s doen't fit in beam", moment.str ())
669 Split up multi-sentence messages, whenever possible. Instead of
672 warning (_f ("out of tune! Can't find: `%s', "Key_engraver"));
674 warning (_f ("Can't find font `%s', loading default",
682 warning (_ ("out of tune:");
683 warning (_f ("Can't find: `%s', "Key_engraver"));
685 warning (_f ("Can't find font: `%s', font_name));
686 warning (_f ("Loading default font"));
690 If you must have multiple-sentence messages, use full punctuation.
691 Use two spaces after end of sentence punctuation.
692 No punctuation (esp. period) is used at the end of simple messages.
695 _f ("Non-matching braces in text `%s', adding braces", text)
696 _ ("Debug output disabled. Compiled with NPRINT.")
697 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
701 Don't modularise too much; a lot of words cannot be translated
703 It's probably safe to treat most occurences of words like
704 stem, beam, crescendo as separately translatable words.
707 When translating, it is preferrable to put interesting information
708 at the end of the message, rather than embedded in the middle.
709 This especially applies to frequently used messages, even if this
710 would mean sacrificing a bit of eloquency. This holds for original
711 messages too, of course.
714 en: can't open: `foo.ly'
715 + nl: kan `foo.ly' niet openen (1)
716 kan niet openen: `foo.ly'* (2)
717 niet te openen: `foo.ly'* (3)
720 The first nl message, although gramatically and stylishly correct,
721 is not friendly for parsing by humans (even if they speak dutch).
722 I guess we'd prefer something like (2) or (3).
725 Please don't run make po/po-update with GNU gettext < 0.10.35