-@c -*-texinfo-*-
-
-@c Move chapter
-
-@node Development
-@chapter Development
-
-@menu
-* CodingStyle::
-* Making patches::
-* Localisation::
-* Helping with development::
-* ETF format::
-@end menu
-
-@node CodingStyle
-@section CodingStyle - standards while programming for GNU LilyPond
-
-As a general rule, you should always try to continue computations, even
-if there is some kind of error. When the program stops, it is often very
-hard for a user to pinpoint what part of the input causes an
-error. Finding the culprit is much easier if there is some viewable
-output.
-
-So functions and methods do not return errorcodes, they never crash, but
-report a programming_error and try to carry on.
-
-@unnumberedsubsec Languages
-
-C++ and Python are preferred. Python code should use an indent of 8,
-using TAB characters.
-
-@unnumberedsubsec Filenames
-
-Definitions of classes that are only accessed via pointers
-(*) or references (&) shall not be included as include files.
-
-filenames
-
-@example
- ".hh" Include files
- ".cc" Implementation files
- ".icc" Inline definition files
- ".tcc" non inline Template defs
-@end example
-
-in emacs:
-
-@example
- (setq auto-mode-alist
- (append '(("\\.make$" . makefile-mode)
- ("\\.cc$" . c++-mode)
- ("\\.icc$" . c++-mode)
- ("\\.tcc$" . c++-mode)
- ("\\.hh$" . c++-mode)
- ("\\.pod$" . text-mode)
- )
- auto-mode-alist))
-@end example
-
-
-The class Class_name is coded in @file{class-name.*}
-
-@unnumberedsubsec Indentation
-
-Standard GNU coding style is used. In emacs:
-
-@example
- (add-hook 'c++-mode-hook
- '(lambda() (c-set-style "gnu")
- )
- )
-@end example
-
-If you like using font-lock, you can also add this to your @file{.emacs}:
-
-@example
- (setq font-lock-maximum-decoration t)
- (setq c++-font-lock-keywords-3
- (append
- c++-font-lock-keywords-3
- '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
- ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
- ))
-@end example
-
-@unnumberedsubsec Classes and Types
-
-@example
- This_is_a_class
-@end example
-
-@unnumberedsubsec Members
-
-@example
- Class::member ()
- Type Class::member_type_
- Type Class::member_type ()
-@end example
-
-the @code{type} is a Hungarian notation postfix for @code{Type}. See below
-
-@unnumberedsubsec Macros
-
-Macro names should be written in uppercase completely.
-
-@unnumberedsubsec Broken code
-
-Try not to write broken code. This includes hardwired dependencies,
-hardwired constants, slow algorithms and obvious limitations. If you can
-not avoid it, mark the place clearly, and add a comment explaining
-shortcomings of the code.
-
-@unnumberedsec Hungarian notation naming convention
-
-The C++ part of LilyPond uses a naming convention derived from the
-so-called @emph{Hungarian Notation}. Macros, @code{enum}s and
-@code{const}s are all uppercase, with the parts of the names separated
-by underscores.
-
-The hungarian notation is to be used when variables are not declared
-near usage (mostly in member variables and functions).
-
-@unnumberedsubsec Types
-
-@table @code
-@item @code{byte}
- unsigned char. (The postfix _by is ambiguous)
-@item @code{b}
- bool
-@item @code{bi}
- bit
-@item @code{ch}
- char
-@item @code{f}
- float
-@item @code{i}
- signed integer
-@item @code{str}
- string class
-@item @code{sz}
- Zero terminated c string
-@item @code{u}
- unsigned integer
-@end table
-
-@unnumberedsubsec User defined types
-
-@example
-
- /*
- Slur blah. blah.
- */
- class Slur @{
- ...
- @};
- Slur* slur_p = new Slur;
-
-@end example
-
-@unnumberedsubsec Modifiers
-
-The following types modify the meaning of the prefix.
-These are preceded by the prefixes:
-
-@table @code
-@item @code{a}
- array
-@item @code{arr}
- user built array.
-@item @code{c}
- const. Note that the proper order is @code{Type const}
- and not @code{const Type}
-@item @code{C}
- A const pointer. This would be equivalent to @code{_c_l}, but since any
- "const" pointer has to be a link (you can't delete a const pointer),
- it is superfluous.
-@item @code{l}
- temporary pointer to object (link)
-@item @code{p}
- pointer to newed object
-@item @code{r}
- reference
-@end table
-
-@unnumberedsubsec Adjective
-
-Adjectives such as global and static should be spelled out in full.
-They come before the noun that they refer to, just as in normal english.
-
-@example
-
-foo_global_i: a global variable of type int commonly called "foo".
-
-@end example
-
-static class members do not need the static_ prefix in the name (the
-Class::var notation usually makes it clear that it is static)
-
-@table @code
-@item @code{loop_i}
- Variable loop: an integer
-@item @code{u}
- Temporary variable: an unsigned integer
-@item @code{test_ch}
- Variable test: a character
-@item @code{first_name_str}
- Variable first_name: a String class object
-@item @code{last_name_ch_a}
- Variable last_name: a @code{char} array
-@item @code{foo_i_p}
- Variable foo: an @code{Int*} that you must delete
-@item @code{bar_i_l}
- Variable bar: an @code{Int*} that you must not delete
-@end table
-
-Generally default arguments are taboo, except for nil pointers.
-
-The naming convention can be quite conveniently memorised, by
-expressing the type in english, and abbreviating it
-
-@example
-
- static Array<int*> foo
-
-@end example
-
-@code{foo} can be described as "the static int-pointer user-array", so you get
-
-@example
-
- foo_static_l_arr
-
-@end example
-
-
-@unnumberedsec Miscellaneous
-
-For some tasks, some scripts are supplied, notably creating patches, a
-mirror of the website, generating the header to put over cc and hh
-files, doing a release.
-
-Use them.
-
-@node Making patches
-@section Making patches
-
-@unnumberedsec Track and distribute your code changes
-
-This page documents how to distribute your changes to GNU lilypond
-
-We would like to have unified context diffs with full pathnames. A
-script automating supplied with Lily.
-
-Distributing a change normally goes like this:
-
-@itemize @bullet
-@item make your fix/add your code
-@item Add changes to CHANGES, and add yourself to Documentation/topdocs/AUTHORS.texi
-@item generate a patch,
-@item e-mail your patch to one of the mailing lists
- gnu-music-discuss@@gnu.org or bug-gnu-music@@gnu.org
-@end itemize
-
-Please do not send entire files, even if the patch is bigger than the
-original. A patch makes it clear what is changed, and it won't
-overwrite previous (not yet released) changes.
-
-@unnumberedsec Generating a patch
-
-Simple version: run
-
-@example
- make -C lilypond-x.y.z/ distclean
- make -C lilypond-x.y.z.NEW/ distclean
- diff -urN lilypond-x.y.z/ lilypond-x.y.z.NEW/
-@end example
-
-Complicated (but automated) version:
-
-In @file{VERSION}, set MY_PATCH_LEVEL:
-
-@example
-
- VERSION:
- ...
- MY_PATCH_LEVEL=jcn1
-
-@end example
-
-In @file{CHANGES}, enter a summary of changes:
-
-@example
- 0.1.73.jcn1
- ===========
-
- * A concise, yet clearly readable description of what changed.
-
-@end example
-
-Then, from the top of Lily's source tree, type
-
-@example
- make release
-@end example
-
-These handy python scripts assume a directory structure which looks
-like:
-
-@example
-
- lilypond -> lilypond-x.y.z # symlink to development directory
- lilypond-x.y.z/ # current development
- patches/ # patches between different releases
- releases/ # .tar.gz releases
-
-@end example
-
-@unnumberedsec Applying patches
-
-[outdated: please use xdeltas]
-
-If you're following LilyPond development regularly, you probably want to
-download just the patch for each subsequent release.
-After downloading the patch (into the patches directory, of course), simply
-apply it:
-
-@example
-
- gzip -dc ../patches/lilypond-0.1.74.diff.gz | patch -p1 -E
-
-@end example
-
-and don't forget to make automatically generated files:
-
-@example
-
- autoconf footnote(patches don't include automatically generated files,
- i.e. file(configure) and files generated by file(configure).)
-
- configure
-
-@end example
-
-@node Localisation
-@section Localisation - User messages in LilyPond
-
-This document provides some guidelines for uniformising user messages.
-In the absence of other standards, we'll be using these rules when coding
- for LilyPond. Hopefully, this can be replaced by general GNU
-guidelines in the future.
-
-Not-preferred messages are marked with @code{+}. By convention,
-agrammatical examples are marked with @code{*}.
-
-@subsection Guidelines
-
-@itemize @bullet
-
-@item
-Every message to the user should be localised (and thus be marked
-for localisation). This includes warning and error messages.
-
-@item
-Don't localise/gettextify:
-
-@itemize @minus
-@item @code{programming_error ()}s
-@item @code{programming_warning ()}s
-@item debug strings
-@item output strings (PostScript, TeX)
-@end itemize
-
-@item
-Messages to be localised must be encapsulated in @code{_ (STRING)}
-or @code{_f (FORMAT, ...)}. Eg:
-
-@example
-warning (_ ("Need music in a score"));
-error (_f ("Can't open file: `%s'", file_name));
-@end example
-
-In some rare cases you may need to call @code{gettext ()} by hand.
-This happens when you pre-define (a list of) string constants for later
-use. In that case, you'll probably also need to mark these string
-constants for translation, using @code{_i (STRING)}. The @code{_i}
-macro is a no-op, it only serves as a marker for @file{xgettext}.
-
-@example
-char const* messages[] = @{
- _i ("enable debugging output"),
- _i ("ignore lilypond version"),
- 0
-@};
-
-void
-foo (int i)
-@{
- puts (gettext (messages [i]));
-@}
-@end example
-
-See also
-@file{flower/getopt-long.cc} and @file{lily/main.cc}.
-
-@item
-Don't use leading or trailing whitespace in messages.
-
-@item
-Messages containing a final verb, or a gerund (@code{-ing}-form)
-always start with a capital. Other (simpler) messages start with
-a lowercase letter:
-
-@example
-The word `foo' is not declared.
-`foo': not declared.
-Not declaring: `foo'.
-@end example
-
-@item
-To avoid having a number of different messages for the same situation,
-we'll use quoting like this @code{"message: `%s'"} for all strings.
-Numbers are not quoted:
-
-@example
-_f ("Can't open file: `%s'", name_str)
-_f ("Can't find charater number: %d", i)
-@end example
-
-@item
-Think about translation issues. In a lot of cases, it is better to
-translate a whole message. The english grammar mustn't be imposed on
-the translator. So, iso
-
-@example
-_ ("Stem at ") + moment.str () + _(" doen't fit in beam")
-@end example
-
-@noindent
-have
-
-@example
-_f ("Stem at %s doen't fit in beam", moment.str ())
-@end example
-
-@item
-Split up multi-sentence messages, whenever possible. Instead of
-
-@example
-warning (_f ("out of tune! Can't find: `%s', "Key_engraver"));
-
-warning (_f ("Can't find font `%s', loading default",
- font_name));
-@end example
-
-@noindent
-rather say:
-
-@example
-warning (_ ("out of tune:");
-warning (_f ("Can't find: `%s', "Key_engraver"));
-
-warning (_f ("Can't find font: `%s', font_name));
-warning (_f ("Loading default font"));
-@end example
-
-@item
-If you must have multiple-sentence messages, use full punctuation.
-Use two spaces after end of sentence punctuation.
-No punctuation (esp. period) is used at the end of simple messages.
-
-@example
- _f ("Non-matching braces in text `%s', adding braces", text)
- _ ("Debug output disabled. Compiled with NPRINT.")
- _f ("Huh? Not a Request: `%s'. Ignoring.", request)
-@end example
-
-@item
-Don't modularise too much; a lot of words cannot be translated
-without context.
-It's probably safe to treat most occurences of words like
-stem, beam, crescendo as separately translatable words.
-
-@item
-When translating, it is preferrable to put interesting information
-at the end of the message, rather than embedded in the middle.
-This especially applies to frequently used messages, even if this
-would mean sacrificing a bit of eloquency. This holds for original
-messages too, of course.
-
-@example
- en: can't open: `foo.ly'
-+ nl: kan `foo.ly' niet openen (1)
- kan niet openen: `foo.ly'* (2)
- niet te openen: `foo.ly'* (3)
-@end example
-
-The first nl message, although gramatically and stylishly correct,
-is not friendly for parsing by humans (even if they speak dutch).
-I guess we'd prefer something like (2) or (3).
-
-@item
-Please don't run make po/po-update with GNU gettext < 0.10.35
-
-@end itemize
-
-@node Helping with development
-@section Getting involved
-
-If you want to help developing LilyPond your efforts are appreciated.
-You can help LilyPond in several ways. Not all tasks requiring
-programming or understanding the full source code.
-
-Please don't expect us to give you instructions on what you should
-do. We're just a bunch of simple hackers, and we're absolutely
-incompetent about management, design in advance, delegating work.
-Some people write to us "I want to help, what should I do?", but we
-never know what to answer them.
-
-If you want to hack, just start hacking. You can send us the result as
-a patch, and we'll gladly incorporate it.
-
-If you need some hints on where to get started: there are a number of
-specific areas where you could do work.
-
-@unnumberedsubsec Users
-
-Mutopia needs your help. The mutopia project is a collection of public
-domain sheet music. You can help the project by entering music (either
-by hand, or by converting from scans or MIDI) and submitting it. Point
-your browser to the @uref{http://sca.uwaterloo.ca/Mutopia, Mutopia
-webpage}.
-
-@unnumberedsubsec Writers
-
-The documentation of LilyPond and related utilities needs a lot of
-work. The documentation is written in
-@uref{http://www.gnu.org/software/texinfo,texinfo}. The documentation of
-LilyPond is sorely lacking in terms of completeness, depth and
-organisation.
-
-Write if you know how to write english documentation in texinfo, and
-know about music and music notation. You must also know how to use
-LilyPond (or be prepared to learn using it). The task is not especially
-hard, but it is a lot of work, and you must be familiar with LilyPond.
-
-@unnumberedsubsec Translators
-
-LilyPond is completely ready for internationalized messages, but there
-are only a few translations so far (dutch, italian, german, japanese,
-french, russian). Translation involves writing a .po file, which is
-relatively easy, and does not even require running LilyPond.
-
-@unnumberedsubsec Hackers
-
-There are lots of possibilities of improving the program itself. There
-are both small projects and big ones. Most of them are listed in our
-TODO file, listed on the homepage of Jan and
-@uref{http://www.cs.uu.nl/~hanwen/lily-devel,Han-Wen}. Modifying
-LilyPond almost always requires patches to the C++ part.
-
-If you still don't have any idea what to do, you might want to browse
-the mailing lists; Users do lots of feature requests, and you could
-implement any of them.
-
-
-There are also numerous other interesting projects that are more or less
-related to LilyPond
-
-@itemize @bullet
-@item Writing converters, eg. from NIFF and MIDI (we tried writing one with
-limited success: midi2ly, included with lilypond.)
-
-We found that writing them in Python is the easiest.
-
-@item Writing a GUI frontend to
-LilyPond. At the moment @uref{denemo,denemo.sourceforge.net} is the most
-advanced.
-
-@item Helping write @uref{http://solfege.sourceforge.net/,solfege
-tools}
-
-@item Helping @uref{primrose.sourceforge.net,primrose}, a tool for
-scanning sheet music.
-@end itemize
-
-@node ETF format
-@section An incomplete description of the Enigma Transport Format
-
-Enigma Transport Format (ETF for short) is a format designed by Coda music
-technology, and it is used in the proprietary notation package
-Finale. Since it is very poorly documented, I'll attempt some
-documentation here.
-
-ETF is an memory dump where object pointers have been replaced by object
-numbers. The numbers are larger than 0 and the number 0 is used to
-denote the nil pointer. The dump is encoded in ASCII (where the mac
-version uses CR, and the PC CR/LF as line delimiters)
-
-A file is divided into sections like this
-
-@example
-^section-header
-DATA
-^section-header
-DATA
-
-(etc.)
-@end example
-
-@var{DATA} is stored in the form of tagged lines, where a tagged line looks
-like
-
-@example
-^TG(N1[,N2]) X1 X2 X3 (etc)
-@end example
-
-The caret is at the start of the line, @code{TG} is a two letter tag,
-and @var{N1} (and optionally @var{N2}) are numbers identifying the
-object to be described. @var{X3}, @var{X4} etc contain data in the form
-of either a signed 16 bit number, or a 32 bit number (in hex, with a $
-sign prepended). The number of Xs per line for a certain tag is
-constant.
-
-The numbers in @code{N1} need not be consecutive or ascending, mostly.
-
-
-If an object is too large to fit on a single line (which typically has
-only five X's), it is put on multiple lines and padded with zero's, eg.
-
-@example
-^GF(1,2) 3 0 1 2 3
-^GF(1,2) 4 0 0 0 0
-@end example
-
-(the GF object requires 6 16 bit words, hence the 4 padding zeroes).
-
-Note structure:
-
-Each staff can contain up to four layers, where a layer correspond to a
-horizontal `line' of notes. Each layer is broken up into frames, where
-each frame is one measure of a layer.
-
-@example
- ^GF(s,m) @var{c} @var{flags} @var{f1} @var{f2} @var{f3}
- ^GF(s,m) @var{f4} 0 0 0 0
-@end example
-
-Here @var{s} is the staff number, @var{m} the measure number,
-@var{flags} is a 16-bit bit-vector, and @var{f1} to @var{f4} are frame
-identifiers. @var{c} is a clef-identifier.
-
-There is a second variant of the @code{GF} tag, which has only one line;
-it looks like
-
-@example
- ^GF(s,m) @var{fr} @var{c} @var{x} @var{y} @var{z}
-@end example
-
-here, @code{fr} is a frame number, @code{c} the clef number. The
-function of x, y , z is unknown.
-
-A frame is described by the FR tag
-
-@example
- ^FR(@var{n}) @var{n1} @var{n2} 0 0
-@end example
-
-This means frame number @var{n} runs from note @var{n1} to note @var{n2}
-Where `running from' is interpreted as ``that part of a linked note list
-that starts with note @var{n1} and ends with note @var{n2}''. This is
-something different from the sequence of notes
-@var{n1}, @var{n1 + 1} , ... , @var{n2 - 1}, @var{n2}.
-
-Notes (or more accurately chord-notes/rests) are described as follows:
-
-@example
- ^eE(@var{n}) @var{l1 l2 dur pos $flags extflags pitchcount}
- pitchrecords
-@end example
-
-This is note number @var{n} (in list where @var{l1} and @var{l2} are
-previous and next).
-
-Durations are stored as a number where 1024 is the quarter note, 512 the
-eighth, etc. Dotted notes are stored by multiplying the dur field
-appropriately.
-
-pitchcount is the number of pitch records. Each pitchrecord looks like
-@example
- pitch $flags
-@end example
-(note that the line starts with spaces, and not with a caret)
-
-
-pitch is a 16 bit number, where the lower order 4-bits is a signed
-nybble which adds an alteration (0 = natural, 1 = sharp, etc.)
-The remaining 12 bits encodes the note-name (octave inclusive.)
-
-Both the alteration and the note-name are relative to the scale as
-defined by the key-signature in this measure. The person who invented
-this should have his head checked out.
-
-The key and time signature are defined in the MS field
-@example
- ^MS(n) space key beats beatlen y z
-@end example
-
-@var{n} is the measure number. @var{space} is the width of the
-measure (?), @var{key} the number of the keysignature (0 = C major, 1 G
-major, etc. 255 = F major, 254 = Bflat major). beats and beatlen
-determine time signature.
-
-Key and time are determined score wide. The mind boggles at how they
-plan to do polytonal and polymetric music. And how do they do
-mid-measure keychanges?
-
-Slurs are (among others) stored with an Sx tag
-
-@example
- ^Sx(@var{slurnumber}) @var{stuff}
-@end example
-
-The slur has many parameters. The 6th number on the first line is the
-starting note, the 3rd number on the 4th line the ending note.
-
-
-Some other information can be found in the Finale Plug-in Development
-(there is a vague manual, and some source files that are useful).
-
-You can download the PDK from Coda's website,
-@uref{http://www.codamusic.com/coda/Fin2000_pdk_download.asp}. You do
-need to register as a user (you can also do it if you have never bought
-an coda product).
-
-
-More tags:
-@example
-RU - repeat
-ES - end repeat
-ET - end repeat text
-BR - backw repeat
-mt - measure text
-pT - page text
-TX - text blocks
-SD - shape
-DY - score expr
-AC - tempo
-GF - clef
-IS - staff spec
-DO (shape expression),
-DT (text expression),
-IK (chord playback),
-IS (staff spec),
-IV (chord suffix),
-IX (articulation definition - documented in edata.h),
-Iu (instrument used - documented in edata.h),
-LA (layer preferences - documented in eprfdata.h),
-MN (measure number region),
-MS (measure spec),
-PS (page spec),
-RS (repeat style - documented in edata.h),
-RT (text repeat style text - documented in edata.h),
-SD (shape),
-SS (staff system spec),
-TX (text block),
-pT (page text)
-
-TP - tuplet
-
-sl - slur shapetag
-@end example
-
-
projects / lilypond.git / blobdiff