1 \input texinfo @c -*-texinfo-*-
2 @setfilename internals.info
3 @settitle LilyPond internals
6 @node Top, LilyPond internals, (dir), (dir)
11 * LilyPond internals::
21 @node LilyPond internals, , Top, Top
26 * Request_engraver:: Request_engraver
30 @chapter Getting involved
32 Please help us make LilyPond a better program. You can help LilyPond in
33 several ways. Not all tasks requiring programming or understanding the
34 full source code. You can write to the mailing list
35 (@email{gnu-music-discuss@@gnu.org} for more information)
37 @unnumberedsubsec Users
39 Mutopia needs your help. The mutopia project is a collection of public
40 domain sheet music. You can help the project by entering music (either
41 by hand, or by converting from scans or MIDI) and submitting it. Point
42 your browser to the @uref{http://sca.uwaterloo.ca/Mutopia, Mutopia
45 @unnumberedsubsec Font designers
47 Our set of glyphs (the Feta font) is far from complete. We need the
48 following glyphs: segno, coda. The fonts have been coded in MetaFont,
49 so you will need to know MetaFont if you want to contribute a glyph.
51 @unnumberedsubsec Writers
53 The documentation of LilyPond and related utilities needs a lot of
54 work. The documentation is written in
55 @uref{http://www.gnu.org/software/texinfo,texinfo}. The documentation of
56 LilyPond is sorely lacking in terms of completeness, depth and
59 Write if you know how to write english documentation in texinfo, and
60 know about music and music notation. You must also know how to use
61 LilyPond (or be prepared to learn using it). The task is not especially
62 hard, but it is a lot of work, and you must be familiar with LilyPond.
64 @unnumberedsubsec Translators
66 LilyPond is completely ready for internationalized messages, but there
67 are only a few translations so far (dutch, italian, german, japanese,
68 french, russian). Translation involves writing a .po file, which is
69 relatively easy, and does not even require running LilyPond.
71 @unnumberedsubsec Hackers
73 There are lots of possibilities of improving the program itself. There
74 are both small projects and big ones. Most of them are listed in our
75 TODO file, listed on the homepage of Jan and
76 @uref{http://www.cs.uu.nl/~hanwen/lily-devel,Han-Wen}. Modifying
77 LilyPond almost always requires patches to the C++ part.
79 There are also numerous other interesting projects that are more or less
83 @item Writing convertors, eg. from NIFF and MIDI (we tried writing one with
84 limited success: midi2ly, included with lilypond.)
86 We found that writing them in Python is the easiest.
88 @item Writing a GUI frontend to
89 LilyPond. At the moment @uref{denemo,denemo.sourceforge.net} is the most
92 @item Helping write @uref{ http://solfege.sourceforge.net/,solfege
95 @item Helping @uref{primrose.sourceforge.net,primrose}, a tool for
100 @chapter LilyPond internals
103 This documents some aspects of the internals of GNU LilyPond. Some of
104 this stuff comes from e-mail I wrote, some from e-mail others wrote,
105 some are large comments taken away from the headers. This page may be a
106 little incoherent. Unfortunately, it is also quite outdated. A more
107 thorough and understandable document is in the works.
109 You should use @code{doc++} to take a peek at the sources.
111 @node Overview, mudela, Top, Top
114 GNU LilyPond is a "multi-pass" system. The different passes have been
115 created so that they do not depend on each other. In a later stage
116 some parts may be moved into libraries, or seperate programs, or they
117 might be integrated in larger systems.
123 No difficult algorithms. The .ly file is read, and converted to a list
124 of @code{Scores}, which each contain @code{Music} and paper/midi-definitions.
126 @item Interpreting music
128 The music is walked through in time-order. The iterators which do the
129 walking report Music to Translators which use this information to
130 create elements, either MIDI or "visual" elements. The translators
131 form a hierarchy; the ones for paper output are Engravers, for MIDI
134 The translators swallow Music (mostly atomic gobs called Requests),
135 create elements, broadcast them to other translators on higher or same
136 level in the hierarchy:
138 The stem of a voice A is broadcast to the staff which contains A, but
139 not to the stems, beams and noteheads of a different voice (say B) or
140 a different staff. The stem and noteheads of A are coupled, because
141 the the Note_heads_engraver broadcasts its heads, and the Stem_engraver catches
144 The engraver which agrees to handle a request decides whether to to
145 honor the request, ignore it, or merge it with other requests. Merging
146 of requests is preferably done with other requests done by members of
147 the same voicegroups (beams, brackets, stems). In this way you can put
148 the voices of 2 instruments in a conductor's score so they make chords
149 (the Beam requests of both instruments will be merged).
153 Breakable stuff (eg. clefs and bars) are copied into pre and
158 Some dependencies are resolved, such as the direction of stems, beams,
159 and "horizontal" placement issues (the order of clefs, keys etc,
160 placement of chords in multi-voice music),
162 @item Break calculation:
164 The lines and horizontal positions of the columns are determined.
168 Through some magical interactions with Line_of_score and Super_elem
169 (check out the source) the "lines" are produced.
171 All other spanners can figure across which lines they are spread. If
172 applicable, they break themselves into pieces. After this, each piece
173 (or, if there are no pieces, the original spanner itself) throws out
174 any dependencies which are in the wrong line.
178 Some items and all spanners need computation after the Paper_column
179 positions are determined. Examples: slurs, vertical positions of
186 @node mudela, Request_engraver, Overview, Top
189 [FIXME: implementation has been generalised, so this is out of date]
191 Most information is stored in the form of a request. In music
192 typesetting, the user might want to cram a lot more symbols on the
193 paper than actually fits. To reflect this idea (the user asks more
194 than we can do), the container for this data is called Request.
196 In a lot of other formats this would be called an 'Event'
199 @item @code{Barcheck_req}
200 Checks during music processing if start of this voice element
201 coincides with the start of a measure. Handy to check if you left out
203 @item @code{Note_req}
204 LilyPond has to decide if the ball should be hanging left or
205 right. This influences the horizontal dimensions of a column, and this
206 is why request processing should be done before horizontal spacing.
207 Other voices' frivolities may cause the need for accidentals, so this
208 is also for the to decide. The engraver can decide on positioning based on
209 ottava commands and the appropriate clef.
210 @item @code{Rest_req}
212 @item @code{Span_req}
213 This type of request typically results in the creation of a @code{Spanner}
214 @item @code{Beam_req}
216 Engraver has to combine this request with the stem_request, since the
217 number of flags that a stem wants to carry will determine the
220 Each dynamic is bound to one note (a crescendo spanning multiple
221 notes is thought to be made of two "dynamics": a start and a stop).
222 Dynamic changes can occur in a smaller time than the length of its
223 note, therefore each @code{Dynamic} request carries a time, measured
224 from the start of its note.
227 @node Request_engraver, , mudela, Top
228 @section Request_engraver
230 In the previous section the idea of Request has been explained, but
231 this only solves one half of the problem. The other half is deciding
232 which requests should be honored, which should merged with other
233 requests, and which should be ignored. Consider this input
237 \type Staff < % chord
238 @{ \meter 2/4; [c8 c8] @}
239 @{\meter 2/4; [e8 e8] @}
244 Both the cs and es are part of a staff (they are in the same
245 Voice_group), so they should share meters, but the two [ ] pairs
248 The judge in this "allocation" problem a set of brokers: the requests
249 are transmitted to so-called engravers which respond if they want to
250 accept a request eg, the @code{Notehead_engraver} will accept
251 @code{Note_req}s, and turn down @code{Slur_req}s. If the Music_iterator
252 cannot find a engraver that wants the request, it is junked (with a
255 After all requests have been either assigned, or junked, the Engraver
256 will process the requests (which usually means creating an @code{Item}
257 or @code{Spanner}). If a @code{Request_engraver} creates something, it
258 tells the enclosing context. If all items/spanners have been created,
259 then each Engraver is notified of any created Score_element, via a
262 @unnumberedsubsec example:
274 Note_request (duration 1/4)
275 Stem_request (duration 1/4)
279 Note_request will be taken by a @code{Notehead_engraver}, stem_request
280 will be taken by a @code{Stem_beam_engraver}. @code{Notehead_engraver}
281 creates a @code{Notehead}, @code{Stem_beam_engraver} creates a
282 @code{Stem}. Both announce this to the Staff_engraver. Staff_engraver
283 will tell @code{Stem_beam_engraver} about the @code{Notehead}, which
284 will add the @code{Notehead} to the @code{Stem} it just created.
286 To decide on merging, several engravers have been grouped. Please
287 check @file{init/engraver.ly}.
289 @node Backend, , , Top
293 @section The backend of LilyPond
300 * Graphic elements:: blah
301 * Position and width Callbacks:: blah
302 * Score_element properties:: blah
303 * Score elements:: blah
310 @node Graphic elements, , , Backend
312 Music notation is composed of a sets of interrelated glyphs. In
313 Lilypond every glyph usually is represented by one object, a so-called
314 Graphic Object. The primary relations between graphic objects involve
318 @item consecutive notes are printed left to right, grouped in a staff
319 @item simultaneous notes are horizontally aligned (internally grouped in
321 @item the staccato mark is horizontally centered on the note it applies
325 The abstract encoding of such relations is done with the concept
326 @dfn{reference point}. The reference point (in X direction) of the
327 staccato mark is the note it applies to. The (X) position of the
328 staccato mark is stored relative to the position of the note head. This
329 means that the staccato will always maintain a fixed offset wrt to the
330 note head, whereever the head is moved to.
332 In the same vein, all notes on a staff have their Y positions stored
333 relative to an object that groups the staff. If that object is moved,
334 the absolute Y positions of all objects in that spanner change along, in
335 effect causing the staff and all its contents to move as a whole.
337 Each graphic object stores a pointer and an relative offset for each
338 direction: one for the X-axis, one for the Y-axis. For example, the X
339 parent of a Note_head usually is a Note_column. The X parent of a
340 Note_column usually is either a Collision or a Paper_column. The X
341 parent of a Collision usually is a Paper_column. If the Collision
342 moves, all Note_heads that have that Collision as parent also move, but
343 the absolute position of the Paper_column does not change.
345 To build a graphical score with Graphic_elements, conceptually, one
346 needs to have one Root object (in Lilypond: Line_of_score), and
347 recursively attach objects to the Root. However, due to the nature
348 of the context selection mechanisms, it turns out to be more
349 advantageous to construct the tree the other way around: first small
350 trees (note heads, barlines etc.) are created, and these are
351 subsequently composed into larger trees, which are finally hung on a
352 Paper_column (in X direction) or Line_of_score (in Y direction).
354 The structure of the X,Y parent relations are determined by the
355 engravers and notation contexts:
357 The most important X-axis parent relation depends on the timing: notes
358 that come earlier are attached to Paper_column that will be positioned
361 The most important Y-axis relation depends on containment of contexts:
362 notes (created in a Thread or Voice context) are put in the staff where
363 the originating context lives in.
365 Graphical_axis_groups are special graphic objects, that are designed to
366 function as a parent. The size of a Graphical_axis_groups group is the
367 union of its children.
369 @node Position and width Callbacks, , , Backend
371 The positions are, as explained relative to a parent reference
372 point. Most positions are not known when an object is created, so these
373 are calculated as needed. This is done by adding a callback for a
374 specific direction, eg
378 my_translate (Score_element * ptr, Axis a)
384 my_element->add_offset_callback (my_translate, Y_AXIS)
387 When a call is made to @code{my_element->relative_position (obj,
388 Y_AXIS)}, @code{my_translate} will be called. The result is that
389 my_element will be translated up by 5 pt. There are numerous callbacks,
392 @item to offset element by staff-spaces (See class
393 @code{Staff_symbol_referencer}).
394 @item to align elements next to other groups of elements (See class
395 @code{Side_position_interface})
399 Offset callbacks can be stacked. The callbacks will be executed in the
400 order that they were added.
402 Width and height are similarly implemted using extent callbacks. There
403 can be only one callback for each axis. No callback (the 0 ptr) means:
404 "empty in this direction".
406 @node Score_element properties, , , Backend
408 Score elements can have other properties besides positioning, for
409 example, text strings (for text objects) style settings, glyphs, padding
410 settings (for scripts). These settings are stored in element properties.
412 Properties are stored as GUILE association lists, with symbols as keys.
413 Element properties can be accessed using the C++ functions
416 SCM get_elt_property (SCM) const;
417 void set_elt_property (const char * , SCM val);
418 void set_immutable_elt_property (const char * , SCM val);
419 void set_immutable_elt_property (SCM key, SCM val);
420 void set_elt_property (SCM , SCM val);
421 void set_elt_pointer (const char*, SCM val);
422 SCM remove_elt_property (const char* nm);
425 All lookup functions identify undefined properties with GUILE
426 end-of-list (ie. @code{'()} in Scheme or @code{SCM_EOL} in C)
428 Implementation wise, there are two kinds of properties:
431 @item mutable properties:
432 element properties that change from object to object. The storage of
433 these are private to a Score element. Typically this is used to store
434 lists of pointers to other objects
436 @item immutable properties:
437 element properties that are shared across objects. The storage is
438 shared, and hence is read-only. Typically, this is used to store
439 function callbacks, and values for shared element properties are read
440 from @file{ly/engraver.ly}.
444 The following is from lily 1.3.80, and it shows the settings for the bar
445 numbers: Bar numbers are breakable, and visible at the beginning of the
446 line. The setting for @code{molecule-callback} indicates that Bar_number
447 is implemented as a text.
449 basicBarNumberProperties = #`(
450 (molecule-callback . ,Text_item::brew_molecule)
452 (visibility-lambda . ,begin-of-line-visible)
458 In 1.3.81 an music expression was added to add to the immutable property
462 \pushproperty #'(basicBarNumberProperties)
463 #'visibility-lambda #end-of-line-visible
466 This will add the entry @code{`(visibility-lambda .
467 ,end-of-line-visible)} to the immutable property list for bar numbers,
468 in effect overriding the setting from @file{ly/engraver.ly}. This can be
472 \popproperty #'(basicBarNumberProperties)
476 Note that you must accompany these statements with a proper context
477 selection in most cases.
484 @node Score elements, , , Backend
486 [FIXME: we want to get rid of dependencies in the implementation.]
488 Besides relative positions there are lots of other relations between
489 elements. Lilypond does not contain other specialized relation
490 management (Like the relative positioning code). Instead, objects can
491 be connected through dependencies, which sets the order in which objects
494 Example: the direction of a beamed stem should equal the direction of
495 the beam. When the stem is a added to the beam, a dependency on the
496 beam is set in the stem: this means that @code{Beam::do_pre_processing
497 ()} (which does various direction related things) will be called before
498 @code{Stem::do_pre_processing ()}.
500 The code that manages dependencies resides in the class
501 @code{Score_element}, a derived class of @code{Graphical_element}. The
502 bulk of the code handles line breaking related issues.
504 To sketch the problems with line breaking: suppose a slur spans a line
508 c4( c'''' c | \break d d )d
511 In this case, the slur will appear as two parts, the first part spanning
512 the first three notes (the @code{c}s), the second spanning the last
513 three (the @code{d}s). Within Lilypond this is modeled as breaking the
514 slur in parts: from the Original slur, two new clones of the old slur
515 are made. Initially both clones depend on the six notes. After the
516 hairy code in Score_element, Spanner and Item which does substitutions
517 in sets of dependencies, the first clone depends on the first three
518 notes, the second on the last three.
520 The major derived classes of Score_element are Item and Spanner.
521 An item has one horizontal position. A spanner hangs on two items.
523 @node Items, , , Backend
528 An item is a score element that is associated with only one
529 Paper_column. Examples are note heads, clefs, super and superscripts, etc.
530 Item is a derived class of Score_element.
532 The shape of an item is known before the break calculations, and line
533 spacing depends on the size of items: very wide items need more space
534 than very small ones.
536 An additional complication is the behavior of items at linebreaks. For
537 example, when you do a time signature change, you get only one symbol.
538 If it occurs at a linebreak, the new time signature must be printed both
539 before and after the linebreak. Other `breakable symbols' such as
540 clefs, and bar lines also exhibit this behavior.
542 if a line of music is broken, the next line usually gets a clef. So in
543 TeX terms, the clef is a postbreak. The same thing happens with meter
544 signs: Normally the meter follows the bar. If a line is broken at that
545 bar, the bar along with the meter stays on the "last" line, but the next
546 line also gets a meter sign after the clef. To support this,
547 breakable items are generated in the three versions: original
548 (unbroken), left (before line break) and right (after line break).
549 During the line spacing, these versions are used to try how the spacing
552 Once the definitive spacing is determined, dependencies (and various
553 other pointers) are substituted such that all dependencies point at the
554 active items: either they point at the original, or they point at left
557 @node Spanners, , , Backend
560 Spanners are symbols that are of variable shape, eg. Slurs, beams, etc.
561 Spanners is a derived class of Score_element.
563 The final shape can only be determined after the line breaking process.
564 All spanners are spanned on two items, called the left and right
565 boundary item. The X reference point is the left boundary item.
568 @node Future work, , , Backend
571 There are plans to unify Spanner and Item, so there will no longer be
572 such a clear distinction between the two. Right now, Score_elements are
573 always either Item or either Spanner.
575 @node Coding standards, , , Top
577 @chapter CodingStyle - standards while programming for GNU LilyPond
579 Functions and methods do not return errorcodes: they never crash, but
580 report a programming_error and try to carry on.q
583 @unnumberedsubsec Languages
585 C++ and Python are preferred. Perl is forbidden. Python code should
586 use an indent of 8, using TAB characters.
588 @unnumberedsubsec Filenames
590 Definitions of classes that are only accessed via pointers
591 (*) or references (&) shall not be included as include files.
597 ".cc" Implementation files
598 ".icc" Inline definition files
599 ".tcc" non inline Template defs
605 (setq auto-mode-alist
606 (append '(("\\.make$" . makefile-mode)
607 ("\\.cc$" . c++-mode)
608 ("\\.icc$" . c++-mode)
609 ("\\.tcc$" . c++-mode)
610 ("\\.hh$" . c++-mode)
611 ("\\.pod$" . text-mode)
617 The class Class_name_abbreviation is coded in @file{class-name-abbr.*}
619 @unnumberedsubsec Indentation
621 Standard GNU coding style is used. In emacs:
624 (add-hook 'c++-mode-hook
625 '(lambda() (c-set-style "gnu")
630 If you like using font-lock, you can also add this to your @file{.emacs}:
633 (setq font-lock-maximum-decoration t)
634 (setq c++-font-lock-keywords-3
636 c++-font-lock-keywords-3
637 '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
638 ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
642 @unnumberedsubsec Classes and Types
648 @unnumberedsubsec Members
652 Type Class::member_type_
653 Type Class::member_type ()
656 the @code{type} is a Hungarian notation postfix for @code{Type}. See below
658 @unnumberedsubsec Macros
660 Macros should be written completely in uppercase
662 The code should not be compilable if proper macro declarations are not
665 Don't laugh. It took us a whole evening/night to figure out one of
666 these bugs, because we had a macro that looked like
667 @code{DECLARE_VIRTUAL_FUNCTIONS ()}.
669 @unnumberedsubsec Broken code
671 Broken code (hardwired dependencies, hardwired constants, slow
672 algorithms and obvious limitations) should be marked as such: either
673 with a verbose TODO, or with a short "ugh" comment.
675 @unnumberedsubsec Comments
677 The source is commented in the DOC++ style. Check out doc++ at
678 @uref{http://www.zib.de/Visual/software/doc++/index.html}
683 C style comments for multiline comments.
684 They come before the thing to document.
690 Long class documentation.
693 TODO Fix boring_member ()
704 short memo. long doco of member ()
705 @@param description of arguments
708 Rettype member (Argtype);
712 data_member_ = 121; // ugh
719 Unfortunately most of the code isn't really documented that good.
721 @unnumberedsec Hungarian notation naming convention
723 Proposed is a naming convention derived from the so-called
724 @emph{Hungarian Notation}. Macros, @code{enum}s and @code{const}s are all
725 uppercase, with the parts of the names separated by underscores.
727 The hungarian notation is to be used when variables are not declared
728 near usage (mostly in member variables and functions).
730 @unnumberedsubsec Types
734 unsigned char. (The postfix _by is ambiguous)
748 Zero terminated c string
753 @unnumberedsubsec User defined types
761 Slur* slur_p = new Slur;
765 @unnumberedsubsec Modifiers
767 The following types modify the meaning of the prefix.
768 These are preceded by the prefixes:
776 const. Note that the proper order is @code{Type const}
777 i.s.o. @code{const Type}
779 A const pointer. This would be equivalent to @code{_c_l}, but since any
780 "const" pointer has to be a link (you can't delete a const pointer),
783 temporary pointer to object (link)
785 pointer to newed object
790 @unnumberedsubsec Adjective
792 Adjectives such as global and static should be spelled out in full.
793 They come before the noun that they refer to, just as in normal english.
797 foo_global_i: a global variable of type int commonly called "foo".
801 static class members do not need the static_ prefix in the name (the
802 Class::var notation usually makes it clear that it is static)
806 Variable loop: an integer
808 Temporary variable: an unsigned integer
810 Variable test: a character
811 @item @code{first_name_str}
812 Variable first_name: a String class object
813 @item @code{last_name_ch_a}
814 Variable last_name: a @code{char} array
816 Variable foo: an @code{Int*} that you must delete
818 Variable bar: an @code{Int*} that you must not delete
821 Generally default arguments are taboo, except for nil pointers.
823 The naming convention can be quite conveniently memorised, by
824 expressing the type in english, and abbreviating it
828 static Array<int*> foo
832 @code{foo} can be described as "the static int-pointer user-array", so you get
841 @unnumberedsec Miscellaneous
843 For some tasks, some scripts are supplied, notably creating patches, a
844 mirror of the website, generating the header to put over cc and hh
845 files, doing a release.
849 @node Making patches, , , Top
852 @unnumberedsec Track and distribute your code changes
854 This page documents how to distribute your changes to GNU lilypond
856 We would like to have unified context diffs with full pathnames. A
857 script automating supplied with Lily.
859 Distributing a change normally goes like this:
862 @item make your fix/add your code
863 @item Add changes to CHANGES, and add yourself to Documentation/topdocs/AUTHORS.texi
864 @item generate a patch,
865 @item e-mail your patch to one of the mailing lists
866 gnu-music-discuss@@gnu.org or bug-gnu-music@@gnu.org
869 Please do not send entire files, even if the patch is bigger than the
870 original. A patch makes it clear what is changed, and it won't
871 overwrite previous (not yet released) changes.
873 @unnumberedsec Generating a patch
878 make -C lilypond-x.y.z/ distclean
879 make -C lilypond-x.y.z.NEW/ distclean
880 diff -urN lilypond-x.y.z/ lilypond-x.y.z.NEW/
883 Complicated (but automated) version:
885 In @file{VERSION}, set MY_PATCH_LEVEL:
895 In @file{CHANGES}, enter a summary of changes:
902 Then, from the top of Lily's source tree, type
908 These handy python scripts assume a directory structure which looks
913 lilypond -> lilypond-x.y.z # symlink to development directory
914 lilypond-x.y.z/ # current development
915 patches/ # patches between different releases
916 releases/ # .tar.gz releases
920 (Some scripts also assume this lives in @file{$HOME/usr/src}).
923 @unnumberedsec Applying patches
926 If you're following LilyPond development regularly, you probably want to
927 download just the patch for each subsequent release.
928 After downloading the patch (into the patches directory, of course), simply
933 gzip -dc ../patches/lilypond-0.1.74.diff.gz | patch -p1 -E
937 and don't forget to make automatically generated files:
941 autoconf footnote(patches don't include automatically generated files,
942 i.e. file(configure) and files generated by file(configure).)
948 @node Localisation, , , Top
950 @chapter Localisation - User messages in LilyPond
952 @section Introduction
954 This document provides some guidelines for uniformising user messages.
955 In the absence of other standards, we'll be using these rules when coding
956 for for LilyPond@footnote{
957 In addition to the C++ coding standards that come with Lily
958 }. Hopefully, this can be replaced by general GNU
959 guidelines in the future.
961 Not-preferred messages are marked with @code{+}.
962 By convention, agrammatical examples are marked with @code{*}.
970 Every message to the user should be localised (and thus be marked
971 for localisation). This includes warning and error messages.
974 Don't localise/gettextify:
977 @item @code{programming_error ()}s
978 @item @code{programming_warning ()}s
980 @item output strings (PostScript, TeX)@footnote{
981 This may seem ridiculously obvious, however, makeinfo-3.12s localises
982 output strings. Sending bug report now ---jcn
989 Messages to be localised must be encapsulated in @code{_ (STRING)}
990 or @code{_f (FORMAT, ...)}. Eg:
993 warning (_ ("Need music in a score"));
994 error (_f ("Can't open file: `%s'", file_name));
997 In some rare cases you may need to call @code{gettext ()} by hand.
998 This happens when you pre-define (a list of) string constants for later
999 use. In that case, you'll probably also need to mark these string
1000 constants for translation, using @code{_i (STRING)}. The @code{_i}
1001 macro is a no-op, it only serves as a marker for @file{xgettext}.
1004 char const* messages[] = @{
1005 _i ("enable debugging output"),
1006 _i ("ignore mudela version"),
1013 puts (gettext (messages [i]));
1018 @file{flower/getopt-long.cc} and @file{lily/main.cc}.
1021 Don't use leading or trailing whitespace in messages.
1024 Messages containing a final verb, or a gerund (@code{-ing}-form)
1025 always start with a capital. Other (simpler) messages start with
1029 The word `foo' is not declared.
1030 `foo': not declared.
1031 Not declaring: `foo'.
1035 To avoid having a number of different messages for the same situation,
1036 we'll use quoting like this @code{"message: `%s'"} for all strings.
1037 Numbers are not quoted:
1040 _f ("Can't open file: `%s'", name_str)
1041 _f ("Can't find charater number: %d", i)
1045 Think about translation issues.
1046 In a lot of cases,it's better to translate a whole message.
1047 The english grammar mustn't be imposed on the translator.
1051 _ ("Stem at ") + moment.str () + _(" doen't fit in beam")
1058 _f ("Stem at %s doen't fit in beam", moment.str ())
1062 Split up multi-sentence messages, whenever possible. Instead of
1065 warning (_f ("out of tune! Can't find: `%s', "Key_engraver"));
1067 warning (_f ("Can't find font `%s', loading default",
1075 warning (_ ("out of tune:");
1076 warning (_f ("Can't find: `%s', "Key_engraver"));
1078 warning (_f ("Can't find font: `%s', font_name));
1079 warning (_f ("Loading default font"));
1083 If you must have multiple-sentence messages, use full punctuation.
1084 Use two spaces after end of sentence punctuation.
1085 No punctuation (esp. period) is used at the end of simple messages.
1088 _f ("Non-matching braces in text `%s', adding braces", text)
1089 _ ("Debug output disabled. Compiled with NPRINT.")
1090 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
1094 Don't modularise too much; a lot of words cannot be translated
1096 It's probably safe to treat most occurences of words like
1097 stem, beam, crescendo as separately translatable words.
1100 When translating, it is preferrable to put interesting information
1101 at the end of the message, rather than embedded in the middle.
1102 This especially applies to frequently used messages, even if this
1103 would mean sacrificing a bit of eloquency. This holds for original
1104 messages too, of course.
1107 en: can't open: `foo.ly'
1108 + nl: kan `foo.ly' niet openen (1)
1109 kan niet openen: `foo.ly'* (2)
1110 niet te openen: `foo.ly'* (3)
1113 The first nl message, although gramatically and stylishly correct,
1114 is not friendly for parsing by humans (even if they speak dutch).
1115 I guess we'd prefer something like (2) or (3).
1118 Please don't run make po/po-update with GNU gettext < 0.10.35