12 * Helping with development::
16 @section CodingStyle - standards while programming for GNU LilyPond
18 As a general rule, you should always try to continue computations, even
19 if there is some kind of error. When the program stops, it is often very
20 hard for a user to pinpoint what part of the input causes an
21 error. Finding the culprit is much easier if there is some viewable
24 So functions and methods do not return errorcodes, they never crash, but
25 report a programming_error and try to carry on.
27 @unnumberedsubsec Languages
29 C++ and Python are preferred. Python code should use an indent of 8,
32 @unnumberedsubsec Filenames
34 Definitions of classes that are only accessed via pointers
35 (*) or references (&) shall not be included as include files.
41 ".cc" Implementation files
42 ".icc" Inline definition files
43 ".tcc" non inline Template defs
50 (append '(("\\.make$" . makefile-mode)
52 ("\\.icc$" . c++-mode)
53 ("\\.tcc$" . c++-mode)
55 ("\\.pod$" . text-mode)
61 The class Class_name is coded in @file{class-name.*}
63 @unnumberedsubsec Indentation
65 Standard GNU coding style is used. In emacs:
68 (add-hook 'c++-mode-hook
69 '(lambda() (c-set-style "gnu")
74 If you like using font-lock, you can also add this to your @file{.emacs}:
77 (setq font-lock-maximum-decoration t)
78 (setq c++-font-lock-keywords-3
80 c++-font-lock-keywords-3
81 '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
82 ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
86 @unnumberedsubsec Classes and Types
92 @unnumberedsubsec Members
96 Type Class::member_type_
97 Type Class::member_type ()
100 the @code{type} is a Hungarian notation postfix for @code{Type}. See below
102 @unnumberedsubsec Macros
104 Macro names should be written in uppercase completely.
106 @unnumberedsubsec Broken code
108 Try not to write broken code. This includes hardwired dependencies,
109 hardwired constants, slow algorithms and obvious limitations. If you can
110 not avoid it, mark the place clearly, and add a comment explaining
111 shortcomings of the code.
113 @unnumberedsec Hungarian notation naming convention
115 The C++ part of LilyPond uses a naming convention derived from the
116 so-called @emph{Hungarian Notation}. Macros, @code{enum}s and
117 @code{const}s are all uppercase, with the parts of the names separated
120 The hungarian notation is to be used when variables are not declared
121 near usage (mostly in member variables and functions).
123 @unnumberedsubsec Types
127 unsigned char. (The postfix _by is ambiguous)
141 Zero terminated c string
146 @unnumberedsubsec User defined types
156 Slur* slur_p = new Slur;
160 @unnumberedsubsec Modifiers
162 The following types modify the meaning of the prefix.
163 These are preceded by the prefixes:
171 const. Note that the proper order is @code{Type const}
172 and not @code{const Type}
174 A const pointer. This would be equivalent to @code{_c_l}, but since any
175 "const" pointer has to be a link (you can't delete a const pointer),
178 temporary pointer to object (link)
180 pointer to newed object
185 @unnumberedsubsec Adjective
187 Adjectives such as global and static should be spelled out in full.
188 They come before the noun that they refer to, just as in normal english.
192 foo_global_i: a global variable of type int commonly called "foo".
196 static class members do not need the static_ prefix in the name (the
197 Class::var notation usually makes it clear that it is static)
201 Variable loop: an integer
203 Temporary variable: an unsigned integer
205 Variable test: a character
206 @item @code{first_name_str}
207 Variable first_name: a String class object
208 @item @code{last_name_ch_a}
209 Variable last_name: a @code{char} array
211 Variable foo: an @code{Int*} that you must delete
213 Variable bar: an @code{Int*} that you must not delete
216 Generally default arguments are taboo, except for nil pointers.
218 The naming convention can be quite conveniently memorised, by
219 expressing the type in english, and abbreviating it
223 static Array<int*> foo
227 @code{foo} can be described as "the static int-pointer user-array", so you get
236 @unnumberedsec Miscellaneous
238 For some tasks, some scripts are supplied, notably creating patches, a
239 mirror of the website, generating the header to put over cc and hh
240 files, doing a release.
245 @section Making patches
247 @unnumberedsec Track and distribute your code changes
249 This page documents how to distribute your changes to GNU lilypond
251 We would like to have unified context diffs with full pathnames. A
252 script automating supplied with Lily.
254 Distributing a change normally goes like this:
257 @item make your fix/add your code
258 @item Add changes to CHANGES, and add yourself to Documentation/topdocs/AUTHORS.texi
259 @item generate a patch,
260 @item e-mail your patch to one of the mailing lists
261 gnu-music-discuss@@gnu.org or bug-gnu-music@@gnu.org
264 Please do not send entire files, even if the patch is bigger than the
265 original. A patch makes it clear what is changed, and it won't
266 overwrite previous (not yet released) changes.
268 @unnumberedsec Generating a patch
273 make -C lilypond-x.y.z/ distclean
274 make -C lilypond-x.y.z.NEW/ distclean
275 diff -urN lilypond-x.y.z/ lilypond-x.y.z.NEW/
278 Complicated (but automated) version:
280 In @file{VERSION}, set MY_PATCH_LEVEL:
290 In @file{CHANGES}, enter a summary of changes:
296 * A concise, yet clearly readable description of what changed.
300 Then, from the top of Lily's source tree, type
306 These handy python scripts assume a directory structure which looks
311 lilypond -> lilypond-x.y.z # symlink to development directory
312 lilypond-x.y.z/ # current development
313 patches/ # patches between different releases
314 releases/ # .tar.gz releases
318 @unnumberedsec Applying patches
320 [outdated: please use xdeltas]
322 If you're following LilyPond development regularly, you probably want to
323 download just the patch for each subsequent release.
324 After downloading the patch (into the patches directory, of course), simply
329 gzip -dc ../patches/lilypond-0.1.74.diff.gz | patch -p1 -E
333 and don't forget to make automatically generated files:
337 autoconf footnote(patches don't include automatically generated files,
338 i.e. file(configure) and files generated by file(configure).)
345 @section Localisation - User messages in LilyPond
347 This document provides some guidelines for uniformising user messages.
348 In the absence of other standards, we'll be using these rules when coding
349 for LilyPond. Hopefully, this can be replaced by general GNU
350 guidelines in the future.
352 Not-preferred messages are marked with @code{+}. By convention,
353 agrammatical examples are marked with @code{*}.
355 @subsection Guidelines
360 Every message to the user should be localised (and thus be marked
361 for localisation). This includes warning and error messages.
364 Don't localise/gettextify:
367 @item @code{programming_error ()}s
368 @item @code{programming_warning ()}s
370 @item output strings (PostScript, TeX)
374 Messages to be localised must be encapsulated in @code{_ (STRING)}
375 or @code{_f (FORMAT, ...)}. Eg:
378 warning (_ ("Need music in a score"));
379 error (_f ("Can't open file: `%s'", file_name));
382 In some rare cases you may need to call @code{gettext ()} by hand.
383 This happens when you pre-define (a list of) string constants for later
384 use. In that case, you'll probably also need to mark these string
385 constants for translation, using @code{_i (STRING)}. The @code{_i}
386 macro is a no-op, it only serves as a marker for @file{xgettext}.
389 char const* messages[] = @{
390 _i ("enable debugging output"),
391 _i ("ignore lilypond version"),
398 puts (gettext (messages [i]));
403 @file{flower/getopt-long.cc} and @file{lily/main.cc}.
406 Don't use leading or trailing whitespace in messages.
409 Messages containing a final verb, or a gerund (@code{-ing}-form)
410 always start with a capital. Other (simpler) messages start with
414 The word `foo' is not declared.
416 Not declaring: `foo'.
420 To avoid having a number of different messages for the same situation,
421 we'll use quoting like this @code{"message: `%s'"} for all strings.
422 Numbers are not quoted:
425 _f ("Can't open file: `%s'", name_str)
426 _f ("Can't find charater number: %d", i)
430 Think about translation issues. In a lot of cases, it is better to
431 translate a whole message. The english grammar mustn't be imposed on
432 the translator. So, iso
435 _ ("Stem at ") + moment.str () + _(" doen't fit in beam")
442 _f ("Stem at %s doen't fit in beam", moment.str ())
446 Split up multi-sentence messages, whenever possible. Instead of
449 warning (_f ("out of tune! Can't find: `%s', "Key_engraver"));
451 warning (_f ("Can't find font `%s', loading default",
459 warning (_ ("out of tune:");
460 warning (_f ("Can't find: `%s', "Key_engraver"));
462 warning (_f ("Can't find font: `%s', font_name));
463 warning (_f ("Loading default font"));
467 If you must have multiple-sentence messages, use full punctuation.
468 Use two spaces after end of sentence punctuation.
469 No punctuation (esp. period) is used at the end of simple messages.
472 _f ("Non-matching braces in text `%s', adding braces", text)
473 _ ("Debug output disabled. Compiled with NPRINT.")
474 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
478 Don't modularise too much; a lot of words cannot be translated
480 It's probably safe to treat most occurences of words like
481 stem, beam, crescendo as separately translatable words.
484 When translating, it is preferrable to put interesting information
485 at the end of the message, rather than embedded in the middle.
486 This especially applies to frequently used messages, even if this
487 would mean sacrificing a bit of eloquency. This holds for original
488 messages too, of course.
491 en: can't open: `foo.ly'
492 + nl: kan `foo.ly' niet openen (1)
493 kan niet openen: `foo.ly'* (2)
494 niet te openen: `foo.ly'* (3)
497 The first nl message, although gramatically and stylishly correct,
498 is not friendly for parsing by humans (even if they speak dutch).
499 I guess we'd prefer something like (2) or (3).
502 Please don't run make po/po-update with GNU gettext < 0.10.35
506 @node Helping with development
507 @section Getting involved
509 If you want to help developing LilyPond your efforts are appreciated.
510 You can help LilyPond in several ways. Not all tasks requiring
511 programming or understanding the full source code.
513 Please don't expect us to give you instructions on what you should
514 do. We're just a bunch of simple hackers, and we're absolutely
515 incompetent about management, design in advance, delegating work.
516 Some people write to us "I want to help, what should I do?", but we
517 never know what to answer them.
519 If you want to hack, just start hacking. You can send us the result as
520 a patch, and we'll gladly incorporate it.
522 If you need some hints on where to get started: there are a number of
523 specific areas where you could do work.
525 @unnumberedsubsec Users
527 Mutopia needs your help. The mutopia project is a collection of public
528 domain sheet music. You can help the project by entering music (either
529 by hand, or by converting from scans or MIDI) and submitting it. Point
530 your browser to the @uref{http://sca.uwaterloo.ca/Mutopia, Mutopia
533 @unnumberedsubsec Writers
535 The documentation of LilyPond and related utilities needs a lot of
536 work. The documentation is written in
537 @uref{http://www.gnu.org/software/texinfo,texinfo}. The documentation of
538 LilyPond is sorely lacking in terms of completeness, depth and
541 Write if you know how to write english documentation in texinfo, and
542 know about music and music notation. You must also know how to use
543 LilyPond (or be prepared to learn using it). The task is not especially
544 hard, but it is a lot of work, and you must be familiar with LilyPond.
546 @unnumberedsubsec Translators
548 LilyPond is completely ready for internationalized messages, but there
549 are only a few translations so far (dutch, italian, german, japanese,
550 french, russian). Translation involves writing a .po file, which is
551 relatively easy, and does not even require running LilyPond.
553 @unnumberedsubsec Hackers
555 There are lots of possibilities of improving the program itself. There
556 are both small projects and big ones. Most of them are listed in our
557 TODO file, listed on the homepage of Jan and
558 @uref{http://www.cs.uu.nl/~hanwen/lily-devel,Han-Wen}. Modifying
559 LilyPond almost always requires patches to the C++ part.
561 If you still don't have any idea what to do, you might want to browse
562 the mailing lists; Users do lots of feature requests, and you could
563 implement any of them.
566 There are also numerous other interesting projects that are more or less
570 @item Writing convertors, eg. from NIFF and MIDI (we tried writing one with
571 limited success: midi2ly, included with lilypond.)
573 We found that writing them in Python is the easiest.
575 @item Writing a GUI frontend to
576 LilyPond. At the moment @uref{denemo,denemo.sourceforge.net} is the most
579 @item Helping write @uref{http://solfege.sourceforge.net/,solfege
582 @item Helping @uref{primrose.sourceforge.net,primrose}, a tool for
583 scanning sheet music.
587 @section An incomplete description of the Enigma Transport Format
589 Enigma Transport Format (ETF for short) is a format designed by Coda music
590 technology, and it is used in the proprietary notation package
591 Finale. Since it is very poorly documented, I'll attempt some
594 ETF is an memory dump where object pointers have been replaced by object
595 numbers. The numbers are larger than 0 and the number 0 is used to
596 denote the nil pointer. The dump is encoded in ASCII (where the mac
597 version uses CR, and the PC CR/LF as line delimiters)
599 A file is divided into sections like this
610 @var{DATA} is stored in the form of tagged lines, where a tagged line looks
614 ^TG(N1[,N2]) X1 X2 X3 (etc)
617 The caret is at the start of the line, @code{TG} is a two letter tag,
618 and @var{N1} (and optionally @var{N2}) are numbers identifying the
619 object to be described. @var{X3}, @var{X4} etc contain data in the form
620 of either a signed 16 bit number, or a 32 bit number (in hex, with a $
621 sign prepended). The number of Xs per line for a certain tag is
624 The numbers in @code{N1} need not be consecutive or ascending, mostly.
627 If an object is too large to fit on a single line (which typically has
628 only five X's), it is put on multiple lines and padded with zero's, eg.
635 (the GF object requires 6 16 bit words, hence the 4 padding zeroes).
639 Each staff can contain up to four layers, where a layer correspond to a
640 horizontal `line' of notes. Each layer is broken up into frames, where
641 each frame is one measure of a layer.
644 ^GF(s,m) @var{c} @var{flags} @var{f1} @var{f2} @var{f3}
645 ^GF(s,m) @var{f4} 0 0 0 0
648 Here @var{s} is the staff number, @var{m} the measure number,
649 @var{flags} is a 16-bit bit-vector, and @var{f1} to @var{f4} are frame
650 identifiers. @var{c} is a clef-identifier.
652 There is a second variant of the @code{GF} tag, which has only one line;
656 ^GF(s,m) @var{fr} @var{c} @var{x} @var{y} @var{z}
659 here, @code{fr} is a frame number, @code{c} the clef number. The
660 function of x, y , z is unknown.
662 A frame is described by the FR tag
665 ^FR(@var{n}) @var{n1} @var{n2} 0 0
668 This means frame number @var{n} runs from note @var{n1} to note @var{n2}
669 Where `running from' is interpreted as ``that part of a linked note list
670 that starts with note @var{n1} and ends with note @var{n2}''. This is
671 something different from the sequence of notes
672 @var{n1}, @var{n1 + 1} , ... , @var{n2 - 1}, @var{n2}.
674 Notes (or more accurately chord-notes/rests) are described as follows:
677 ^eE(@var{n}) @var{l1 l2 dur pos $flags extflags pitchcount}
681 This is note number @var{n} (in list where @var{l1} and @var{l2} are
684 Durations are stored as a number where 1024 is the quarter note, 512 the
685 eighth, etc. Dotted notes are stored by multiplying the dur field
688 pitchcount is the number of pitch records. Each pitchrecord looks like
692 (note that the line starts with spaces, and not with a caret)
695 pitch is a 16 bit number, where the lower order 4-bits is a signed
696 nybble which adds an alteration (0 = natural, 1 = sharp, etc.)
697 The remaining 12 bits encodes the note-name (octave inclusive.)
699 Both the alteration and the note-name are relative to the scale as
700 defined by the key-signature in this measure. The person who invented
701 this should have his head checked out.
703 The key and time signature are defined in the MS field
705 ^MS(n) space key beats beatlen y z
708 @var{n} is the measure number. @var{space} is the width of the
709 measure (?), @var{key} the number of the keysignature (0 = C major, 1 G
710 major, etc. 255 = F major, 254 = Bflat major). beats and beatlen
711 determine time signature.
713 Key and time are determined score wide. The mind boggles at how they
714 plan to do polytonal and polymetric music. And how do they do
715 mid-measure keychanges?
717 Slurs are (among others) stored with an Sx tag
720 ^Sx(@var{slurnumber}) @var{stuff}
723 The slur has many parameters. The 6th number on the first line is the
724 starting note, the 3rd number on the 4th line the ending note.
727 Some other information can be found in the Finale Plug-in Development
728 (there is a vague manual, and some source files that are useful).
730 You can download the PDK from Coda's website,
731 @uref{http://www.codamusic.com/coda/Fin2000_pdk_download.asp}. You do
732 need to register as a user (you can also do it if you have never bought
750 DO (shape expression),
751 DT (text expression),
755 IX (articulation definition - documented in edata.h),
756 Iu (instrument used - documented in edata.h),
757 LA (layer preferences - documented in eprfdata.h),
758 MN (measure number region),
761 RS (repeat style - documented in edata.h),
762 RT (text repeat style text - documented in edata.h),
764 SS (staff system spec),