[lilypond.git] / Documentation / contributor / programming-work.itexi

@c -*- coding: us-ascii; mode: texinfo; -*-
@node Programming work
@chapter Programming work

@menu
* Overview of LilyPond architecture::
* LilyPond programming languages::
* Programming without compiling::
* Finding functions::
* Code style::
* Debugging LilyPond::
* Adding or modifying features::
* Iterator tutorial::
* Engraver tutorial::
* Callback tutorial::
* LilyPond scoping::
@end menu

@node Overview of LilyPond architecture
@section Overview of LilyPond architecture

LilyPond processes the input file into graphical and musical output in a
number of stages.  This process, along with the types of routines that
accomplish the various stages of the process, is described in this section.  A
more complete description of the LilyPond architecture and internal program
execution is found in Erik Sandberg's
@uref{http://lilypond.org/web/images/thesis-erik-sandberg.pdf, master's
thesis}.


The first stage of LilyPond processing is @emph{parsing}.  In the parsing
process, music expressions in LilyPond input format are converted to music
expressions in Scheme format.  In Scheme format, a music expression is a list
in tree form, with nodes that indicate the relationships between various music
events.  The LilyPond parser is written in Bison.

The second stage of LilyPond processing is @emph{iterating}.  Iterating
assigns each music event to a context, which is the environment in which the
music will be finally engraved.  The context is responsible for all further
processing of the music.  It is during the iteration stage that contexts are
created as necessary to ensure that every note has a Voice type context (e.g.
Voice, TabVoice, DrumVoice, CueVoice, MensuralVoice, VaticanaVoice,
GregorianTranscriptionVoice), that the Voice type contexts exist in
appropriate Staff type contexts, and that parallel Staff type contexts exist
in StaffGroup type contexts.  In addition, during the iteration stage each
music event is assigned a moment, or a time in the music when the event
begins.

Each type of music event has an associated iterator.  Iterators are defined in
*-iterator.cc. During iteration, an
event's iterator is called to deliver that music event to the appropriate
context(s).

The final stage of LilyPond processing is @emph{translation}.  During
translation, music events are prepared for graphical or midi output.  The
translation step is accomplished by the polymorphic base class Translator
through its two derived classes: Engraver (for graphical output) and
Performer (for midi output).

Translators are defined in C++ files named *-engraver.cc and *-performer.cc.
Much of the work of translating is handled by Scheme functions,
which is one of the keys to LilyPond's exceptional flexibility.

@sourceimage{architecture-diagram,,,png}


@node LilyPond programming languages
@section LilyPond programming languages

Programming in LilyPond is done in a variety of programming languages.  Each
language is used for a specific purpose or purposes.  This section describes
the languages used and provides links to reference manuals and tutorials for
the relevant language.

@subsection C++

The core functionality of LilyPond is implemented in C++.

C++ is so ubiquitous that it is difficult to identify either a reference
manual or a tutorial.  Programmers unfamiliar with C++ will need to spend some
time to learn the language before attempting to modify the C++ code.

The C++ code calls Scheme/GUILE through the GUILE interface, which is
documented in the
@uref{http://www.gnu.org/software/guile/manual/html_node/index.html, GUILE
  Reference Manual}.

@subsection Flex

The LilyPond lexer is implemented in Flex, an implementation of the Unix lex
lexical analyser generator.  Resources for Flex can be found
@uref{http://flex.sourceforge.net/, here}.

@subsection GNU Bison

The LilyPond parser is implemented in Bison, a GNU parser generator.  The
Bison homepage is found at @uref{http://www.gnu.org/software/bison/,
gnu.org}.  The manual (which includes both a reference and tutorial) is
@uref{http://www.gnu.org/software/bison/manual/index.html, available} in a
variety of formats.

@subsection GNU Make

GNU Make is used to control the compiling process and to build the
documentation and the website.  GNU Make documentation is available at
@uref{http://www.gnu.org/software/make/manual/, the GNU website}.

@subsection GUILE or Scheme

GUILE is the dialect of Scheme that is used as LilyPond's extension language.
Many extensions to LilyPond are written entirely in GUILE.  The
@uref{http://www.gnu.org/software/guile/manual/html_node/index.html,
GUILE Reference Manual} is available online.

@uref{http://mitpress.mit.edu/sicp/full-text/book/book.html, Structure and
Interpretation of Computer Programs}, a popular textbook used to teach
programming in Scheme is available in its entirety online.

An introduction to Guile/Scheme as used in LilyPond can be found in the
Learning Manual, see @rlearning{Scheme tutorial}.

@subsection MetaFont

MetaFont is used to create the music fonts used by LilyPond.  A MetaFont
tutorial is available at @uref{http://metafont.tutorial.free.fr/, the
METAFONT tutorial page}.

@subsection PostScript

PostScript is used to generate graphical output.  A brief PostScript tutorial
is @uref{http://local.wasp.uwa.edu.au/~pbourke/dataformats/postscript/,
available online}.  The
@uref{http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf, PostScript Lanugage
Reference} is available online in PDF format.

@subsection Python

Python is used for XML2ly and is used for buillding the documentation and the
website.

Python documentation is available at @uref{http://www.python.org/doc/,
python.org}.

@node Programming without compiling
@section Programming without compiling

Much of the development work in LilyPond takes place by changing *.ly or
*.scm files.  These changes can be made without compiling LilyPond.  Such
changes are described in this section.


@subsection Modifying distribution files

Much of LilyPond is written in Scheme or LilyPond input files.  These
files are interpreted when the program is run, rather than being compiled
when the program is built, and are present in all LilyPond distributions.
You will find .ly files in the ly/ directory and the Scheme files in the
scm/ directory.  Both Scheme files and .ly files can be modified and
saved with any text editor.  It's probably wise to make a backup copy of
your files before you modify them, although you can reinstall if the
files become corrupted.

Once you've modified the files, you can test the changes just by running
LilyPond on some input file.  It's a good idea to create a file that
demonstrates the feature you're trying to add.  This file will eventually
become a regression test and will be part of the LilyPond distribution.

@subsection Desired file formatting

Files that are part of the LilyPond distribution have Unix-style line
endings (LF), rather than DOS (CR+LF) or MacOS 9 and earlier (CR).  Make
sure you use the necessary tools to ensure that Unix-style line endings are
preserved in the patches you create.

Tab characters should not be included in files for distribution.  All
indentation should be done with spaces.  Most editors have settings to
allow the setting of tab stops and ensuring that no tab characters are
included in the file.

Scheme files and LilyPond files should be written according to standard
style guidelines.  Scheme file guidelines can be found at
@uref{http://community.schemewiki.org/?scheme-style}.  Following these
guidelines will make your code easier to read.  Both you and others that
work on your code will be glad you followed these guidelines.

For LilyPond files, you should follow the guidelines for LilyPond snippets
in the documentation.  You can find these guidelines at
@ref{Texinfo introduction and usage policy}.

@node Finding functions
@section Finding functions

When making changes or fixing bugs in LilyPond, one of the initial
challenges is finding out where in the code tree the functions to
be modified live.  With nearly 3000 files in the source tree,
trial-and-error searching is generally ineffective. This section
describes a process for finding interesting code.

@subsection Using the ROADMAP

The file ROADMAP is located in the main directory of the lilypond source.
ROADMAP lists all of the directories in the LilPond source tree, along
with a brief description of the kind of files found in each directory.
This can be a very helpful tool for deciding which directories to search
when looking for a function.


@subsection Using grep to search

Having identified a likely subdirectory to search, the grep utility can
be used to search for a function name.  The format of the grep command is

@example
grep -i functionName subdirectory/*
@end example

This command will search all the contents of the directory subdirectory/
and display every line in any of the files that contains
functionName.  The @code{-i} option makes @command{grep} ignore
case -- this can be very useful if you are not yet familiar with
our capitalization conventions.

The most likely directories to grep for function names are scm/ for
scheme files, ly/ for lilypond input (*.ly) files, and lily/ for C++
files.


@subsection Using git grep to search

If you have used git to obtain the source, you have access to a
powerful tool to search for functions.  The command:

@example
git grep functionName
@end example

will search through all of the files that are present in the git
repository looking for functionName.  It also presents the results
of the search using @code{less}, so the results are displayed one page
at a time.

@subsection Searching on the git repository at Savannah

You can also use the equivalent of git grep on the Savannah server.

@itemize

@item
Go to http://git.sv.gnu.org/gitweb/?p=lilypond.git

@item
In the pulldown box that says commit, select grep.

@item
Type functionName in the search box, and hit enter/return

@end itemize

This will initiate a search of the remote git repository.


@node Code style
@section Code style

@menu
@end menu

@subsection Handling errors

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.

@subsection Languages

C++ and Python are preferred.  Python code should use PEP 8.

@subsection Filenames

Definitions of classes that are only accessed via pointers (*) or
references (&) shall not be included as include files.

@verbatim
   filenames

        ".hh"   Include files
             ".cc"      Implementation files
             ".icc"     Inline definition files
             ".tcc"     non inline Template defs

   in emacs:

             (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 verbatim

The class Class_name is coded in @q{class-name.*}

@subsection Indentation

Standard GNU coding style is used. In emacs:

@verbatim
             (add-hook 'c++-mode-hook
                  '(lambda() (c-set-style "gnu")
                     ))
@end verbatim

If you like using font-lock, you can also add this to your
@q{.emacs}:

@verbatim
             (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 verbatim

Some source files may not currently have proper indenting.  If this
is the case, it is desirable to fix the improper indenting when the
file is modified, with the hope of continually improving the code.

@subsection Indenting files with emacs in script mode

@c email to wl@gnu.org when I get here.

@warning{this is pending some confirmation on -devel.  July 2009 -gp}

Command-line script to format stuff with emacs:

@example
#!/bin/sh
emacs $1 -batch --eval '(indent-region (point-min) (point-max) nil)' -f save-buffer
@end example

(that's all on one line)

Save it as a shell script, then run on the file(s) you modified.

@subsection Indenting with vim

Although emacs indentation is the LilyPond standard, acceptable
indentation can usually be accomplished with vim.  Some hints for
vim are as follows:

A workable .vimrc:

@verbatim
set cindent
set smartindent
set autoindent
set expandtab
set softtabstop=2
set shiftwidth=2
filetype plugin indent on
set incsearch
set ignorecase smartcase
set hlsearch
set confirm
set statusline=%F%m%r%h%w\ %{&ff}\ %Y\ [ASCII=\%03.3b]\ [HEX=\%02.2B]\ %04l,%04v\ %p%%\ [LEN=%L]
set laststatus=2
set number
" Remove trailing whitespace on write
autocmd BufWritePre * :%s/\s\+$//e
@end verbatim

With this .vimrc, files can be reindented automatically by highlihting
the lines to be indented in visual mode (use V to enter visual mode)
and pressing =.

A scheme.vim file will help improve the indentation.  This one
was suggested by Patrick McCarty.  It should be saved in
~/.vim/after/syntax/scheme.vim.

@verbatim
" Additional Guile-specific 'forms'
syn keyword schemeSyntax define-public define* define-safe-public
syn keyword schemeSyntax use-modules define-module
syn keyword schemeSyntax defmacro-public define-macro
syn keyword schemeSyntax define-builtin-markup-command
syn keyword schemeSyntax define-markup-command
syn keyword schemeSyntax define-builtin-markup-list-command
syn keyword schemeSyntax let-keywords* lambda* define*-public
syn keyword schemeSyntax defmacro* defmacro*-public

" All of the above should influence indenting too
set lw+=define-public,define*,define-safe-public,use-modules,define-module
set lw+=defmacro-public,define-macro,define-builtin-markup-command
set lw+=define-markup-command,define-builtin-markup-list-command
set lw+=let-keywords*,lambda*,define*-public,defmacro*,defmacro*-public

" These forms should not influence indenting
set lw-=if
set lw-=set!

" Try to highlight all ly: procedures
syn match schemeFunc "ly:[^) ]\+"
@end verbatim

@subsection Classes and Types

@verbatim
This_is_a_class
@end verbatim


@subsection Members

Member variable names end with an underscore:

@verbatim
Type Class::member_
@end verbatim


@subsection Macros

Macro names should be written in uppercase completely.


@subsection Broken code

Do not 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.

We reject broken-in-advance on principle.

@subsection Naming

Variable names should be complete words, rather than abbreviations.
For example, it is preferred to use @code{thickness} rather than
@code{th} or @code{t}.

Multi-word variable names in C++ should have the words separated
by the underscore character (@q{_}).

Multi-word variable names in Scheme should have the words separated
by a hyphen (@q{-}).

@subsection Comments

Comments may not be needed if descriptive variable names are used
in the code and the logic is straightforward.  However, if the
logic is difficult to follow, and particularly if non-obvious
code has been included to resolve a bug, a comment describing
the logic and/or the need for the non-obvious code should be included.

There are instances where the current code could be commented better.
If significant time is required to understand the code as part of
preparing a patch, it would be wise to add comments reflecting your
understanding to make future work easier.

@subsection Messages

Messages need to follow Localization.


@subsection Localization

This document provides some guidelines for programmers write user
messages.  To help translations, user messages must follow
uniform conventions.  Follow these rules when coding for LilyPond.
Hopefully, this can be replaced by general GNU guidelines in the
future.  Even better would be to have an English (en_BR, en_AM)
guide helping programmers writing consistent messages for all GNU
programs.

Non-preferred messages are marked with `+'. By convention,
ungrammatical examples are marked with `*'.  However, such ungrammatical
examples may still be preferred.

@itemize

@item
Every message to the user should be localized (and thus be marked
for localization). This includes warning and error messages.

@item
Do not localize/gettextify:

@itemize
@item
`programming_error ()'s

@item
`programming_warning ()'s

@item
debug strings

@item
output strings (PostScript, TeX, etc.)

@end itemize

@item
Messages to be localized must be encapsulated in `_ (STRING)' or
`_f (FORMAT, ...)'. E.g.:

@example
warning (_ ("need music in a score"));
error (_f ("cannot open file: `%s'", file_name));
@end example

In some rare cases you may need to call `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 `_i (STRING)'. The `_i' macro is
a no-op, it only serves as a marker for `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 `flower/getopt-long.cc' and `lily/main.cc'.

@item
Do not use leading or trailing whitespace in messages. If you need
whitespace to be printed, prepend or append it to the translated
message

@example
message ("Calculating line breaks..." + " ");
@end example

@item
Error or warning messages displayed with a file name and line
number never start with a capital, eg,

@example
foo.ly: 12: not a duration: 3
@end example

Messages containing a final verb, or a gerund (`-ing'-form) always
start with a capital. Other (simpler) messages start with a
lowercase letter

@example
Processing foo.ly...
`foo': not declared.
Not declaring: `foo'.
@end example

@item
Avoid abbreviations or short forms, use `cannot' and `do not'
rather than `can't' or `don't'
To avoid having a number of different messages for the same
situation, well will use quoting like this `"message: `%s'"' for all
strings. Numbers are not quoted:

@example
_f ("cannot open file: `%s'", name_str)
_f ("cannot find character 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 must not be imposed
on the translator. So, instead of

@example
stem at  + moment.str () +  does not fit in beam
@end example

have

@example
_f ("stem at %s does not 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 ("cannot find font `%s', loading default", font_name));
@end example

rather say:

@example
warning (_ ("out of tune:"));
warning (_f ("cannot find: `%s', "Key_engraver"));
warning (_f ("cannot 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
Do not modularize too much; words frequently cannot be translated
without context. It is probably safe to treat most occurences of
words like stem, beam, crescendo as separately translatable words.

@item
When translating, it is preferable 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: cannot 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 grammatically and stylistically
correct, is not friendly for parsing by humans (even if they speak
dutch). I guess we would prefer something like (2) or (3).

@item
Do not run make po/po-update with GNU gettext < 0.10.35

@end itemize



@node Debugging LilyPond
@section Debugging LilyPond

The most commonly used tool for debugging LilyPond is the GNU debugger
gdb.  Use of gdb is described in this section.

@subsection Debugging overview

Using a debugger simplifies troubleshooting in at least two ways.

First, breakpoints can be set to pause execution at any desired point.
Then, when execution has paused, debugger commands can be issued to
explore the values of various variables or to execute functions.

Second, the debugger allows the display of a stack trace, which shows
the sequence in which functions are called and the arguments to the
various function calls.


@subsection Compiling with debugging information

In order to use a debugger with LilyPond, it is necessary to compile
LilyPond with debugging information.  This is accomplished by running
the following commands in the main LilyPond source directory.

@example
./configure  --disable-optimising

make
@end example

This will create a version of LilyPond that contains the debugging
information that will allow the debugger to tie the source code
to the compiled code.

You should not do @var{make install} if you want to use a debugger
with LilyPond.  @var{make install} will strip the debugging information
from the LilyPond binary.

To set breakpoints in Scheme functions, put

@example
\include "guile-debugger.ly"
@end example

in your input file after any scheme procedures you have defined in
that file.  When your input file is processed, a guile prompt
will be displayed.  At the guile prompt, you can set breakpoints with
the @code{break!} procedure:

@example
guile> (break! my-scheme-procedure)
@end example

Once you have set the desired breakpoints, you exit the guile repl frame
by typing:

@example
guile> (quit)
@end example

When one of the scheme routines for which you have set breakpoints is
entered, guile will interrupt execution in a debug frame.  At this point,
you will have access to guile debugging commands.  For a listing of these
commands, type:

@example
debug> help
@end example

@subsection Typical gdb usage

@subsection Typical .gdbinit files

The behavior of gdb can be readily customized through the use of
@var{.gdbinit} files.  A @var{.gdbinit} file is a file named
@var{.gdbinit} (notice the @qq{.} at the beginning of the file name)
that is placed in a user's home directory.

The @var{.gdbinit} file below is from Han-Wen.  It sets breakpoints
for all errors and defines functions for displaying scheme objects
(ps), grobs (pgrob), and parsed music expressions (pmusic).

@example
file lily/out/lilypond
b programming_error
b Grob::programming_error

define ps
   print ly_display_scm($arg0)
end
define pgrob
  print ly_display_scm($arg0->self_scm_)
  print ly_display_scm($arg0->mutable_property_alist_)
  print ly_display_scm($arg0->immutable_property_alist_)
  print ly_display_scm($arg0->object_alist_)
end
define pmusic
  print ly_display_scm($arg0->self_scm_)
  print ly_display_scm($arg0->mutable_property_alist_)
  print ly_display_scm($arg0->immutable_property_alist_)
end
@end example

@subsection Using Guile interactively with LilyPond

In order to experiment with Scheme programming in the LilyPond
environment, it is convenient to have a Guile interpreter that
has all the LilyPond modules loaded.  This requires the following
steps.

First, define a Scheme symbol for the active module
in the .ly file:

@example
#(module-define! (resolve-module '(guile-user))
                 'lilypond-module (current-module))
@end example

Second, place a Scheme function in the .ly file that gives an interactive Guile
prompt:

@example
#(top-repl)
@end example

When the .ly file is compiled, this causes the compilation to be interrupted
and an interactive guile prompt to appear.  When the guile prompt appears,
the LilyPond active module must be set as the current guile module:

@example
guile> (set-current-module lilypond-module)
@end example

Proper operation of these commands can be demonstrated by typing the name
of a LilyPond public scheme function to see if it's properly defined:

@example
guile> fret-diagram-verbose-markup
#<procedure fret-diagram-verbose-markup (layout props marking-list)>
@end example

If the LilyPond module has not been correctly loaded, an error
message will be generated:

@example
guile> fret-diagram-verbose-markup
ERROR: Unbound variable: fret-diagram-verbose-markup
ABORT: (unbound-variable)
@end example

Once the module is properly loaded, any valid LilyPond Scheme expression
can be entered at the interactive prompt.

After the investigation is complete, the interactive guile interpreter
can be exited:

@example
guile> (quit)
@end example

The compilation of the .ly file will then continue.

@node Adding or modifying features
@section Adding or modifying features

When a new feature is to be added to LilyPond, it is necessary to
ensure that the feature is properly integrated to maintain
its long-term support.  This section describes the steps necessary
for feature addition and modification.

@subsection Write the code

You should probably create a new git branch for writing the code, as that
will separate it from the master branch and allow you to continue
to work on small projects related to master.

Please be sure to follow the rules for programming style discussed
earlier in this chapter.

@subsection Write regression tests

In order to demonstrate that the code works properly, you will
need to write one or more regression tests.  These tests are
typically .ly files that are found in input/regression.

Regression tests should be as brief as possible to demonstrate the
functionality of the code.

Regression tests should generally cover one issue per test.  Several
short, single-issue regression tests are preferred to a single, long,
multiple-issue regression test.

Use existing regression tests as templates to demonstrate the type of
header information that should be included in a regression test.

@subsection Write convert-ly rule

If the modification changes the input syntax, a convert-ly rule
should be written to automatically update input files from older
versions.

convert-ly rules are found in python/convertrules.py

If possible, the convert-ly rule should allow automatic updating
of the file.  In some cases, this will not be possible, so the
rule will simply point out to the user that the feature needs
manual correction.

@subsection Automatically update documentation, snippets, and regtests

convert-ly should be used to update the documentation, the snippets,
and the regression tests.  This not only makes the necessary syntax
changes, it also tests the convert-ly rules.

The automatic updating is a three step process.  First, be sure you
are in the top-level source directory.  Then, for the
documentation, do:

@example
find Documentation/ -name '*.itely' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
@end example

@noindent
where @var{X.Y.Z} is the version number of the last released development
version.

Next, for the snippets, do:

@example
find Documentation/snippets/ -name '*.ly' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
@end example

Finally, for the regression tests, do:

@example
find input/regression/ -name '*.ly' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}

@end example

@subsection Manually update documentation, snippets, and regtests

Where the convert-ly rule is not able to automatically update the inline
lilypond code in the documentation (i.e. if a NOT_SMART rule is used), the
documentation must be manually updated.  The inline snippets that require
changing must be changed in the English version of the docs and all
translated versions.  If the inline code is not changed in the
translated documentation, the old snippets will show up in the
English version of the documentation.

Where the convert-ly rule is not able to automatically update snippets
in Documentation/snippets/, those snippets must be manually updated.
Those snippets should be copied to Documentation/snippets/new.  The
comments at the top of the snippet describing its automatice generation
should be removed.  All translated texidoc strings should be removed.
The comment @qq{% begin verbatim} should be removed.  The syntax of
the snippet should then be manually edited.

Where snippets in Documentation/snippets are made obsolete, the snippet
should be copied to Documentation/snippets/new.  The comments and
texidoc strings should be removed as described above.  Then the body
of the snippet should be changed to:

@example
\markup @{
  This snippet is deprecated as of version X.Y.Z and
  will be removed from the documentation.
@}
@end example

@noindent
where X.Y.Z is the version number for which the convert-ly rule was
written.

Update the snippet files by running:

@example
scripts/auxiliar/makelsr.py
@end example

Where the convert-ly rule is not able to automatically update regression
tests, the regression tests in input/regression should be manually
edited.

Although it is not required, it is helpful if the developer
can write relevant material for inclusion in the Notation
Reference.  If the developer does not feel qualified to write
the documentation, a documentation editor will be able to
write it from the regression tests.  The text that is added to
or removed from the documentation should be changed only in
the English version.

@subsection Edit changes.tely

An entry should be added to Documentation/changes.tely to describe
the feature changes to be implemented.  This is especially important
for changes that change input file syntax.

Hints for changes.tely entries are given at the top of the file.

New entries in changes.tely go at the top of the file.

The changes.tely entry should be written to show how the new change
improves LilyPond, if possible.

@subsection Verify successful build

When the changes have been made, successful completion must be
verified by doing

@example
make all
make doc
@end example

When these commands complete without error, the patch is
considered to function successfully.

Developers on Windows who are unable to build LilyPond should
get help from a Linux or OSX developer to do the make tests.

@subsection Verify regression test

In order to avoid breaking LilyPond, it is important to verify that
the regression tests all succeed.  This process is described in
@ref{Regression tests}.

@subsection Post patch for comments

For any change other than a minor change, a patch set should be
posted on @uref{http://codereview.appspot.com/, Rietveld} for comment.
This requires the use of an external package, git-cl, and an email
account on Google.

git-cl is installed by:

@example
git clone git://neugierig.org/git-cl.git
@end example

Then, add the git-cl directory to your PATH, or create a
symbolic link to the git-cl and upload.py in one of your
PATH directories (like usr/bin).  git-cl is then
configured by entering the command

@example
git cl config
@end example

@noindent
in the LilyPond git directory and answering the questions that
are asked.  If you do not understand the question answer with just
a newline (CR).

The patch set is posted to Rietveld as follows.  Ensure your changes
are committed in a separate branch, which should differ from the
reference branch to be used by just the changes to be uploaded.
If the reference branch is to be origin/master, ensure this is
up-to-date.  If necessary, use git rebase to rebase the branch
containing the changes to the head of origin/master.  Finally,
check out branch with the changes and enter the command:

@example
git cl upload <reference SHA1 ID>
@end example

@noindent
where <reference SHA1 ID> is the SHA1 ID of the commit to be used
as a reference source for the patch.  Generally, this will be the
SHA1 ID of origin/master, and in that case the command

@example
git cl upload origin/master
@end example

@noindent
can be used.

After prompting for your Google email address and password, the
patch set will be posted to Rietveld.

You should then announce the patch by sending
an email to lilypond-devel, with a subject line
starting with PATCH:, asking for comments on the patch.

As revisions are made in response to comments, successive patch sets
for the same issue can be uploaded by reissuing the git-cl command
with the modified branch checked out.

@subsection Push patch

Once all the comments have been addressed, the patch can be pushed.

If the author has push privileges, the author will push the patch.
Otherwise, a developer with push privileges will push the patch.

@subsection Closing the issues

Once the patch has been pushed, all the relevant issues should be
closed.

On Rietveld, the author should log in an close the issue either by
using the @q{Edit Issue} link, or by clicking the circled x icon
to the left of the issue name.

If the changes were in response to a feature request on the Google
issue tracker for LilyPond, the author should change the status to
@q{Fixed_x_y_z} where the patch was fixed in version x.y.z.  If
the author does not have privileges to change the status, an email
should be sent to bug-lilypond requesting the BugMeister to change
the status.

@node Iterator tutorial
@section Iterator tutorial

FIXME -- this is a placeholder for a tutorial on iterators

Iterators are routines written in C++ that process music expressions
and sent the music events to the appropriate engravers and/or
performers.

@node Engraver tutorial
@section Engraver tutorial

FIXME -- This is a placeholder for a tutorial on how engravers work.

Engravers are C++ classes that catch music events and
create the appropriate grobs for display on the page.  Though the
majority of engravers are responsible for the creation of a single grob,
in some cases (e.g. @code{New_fingering_engraver}), several different grobs
may be created.

@subsection Useful methods for information processing

An engraver inherits the following public methods from the Translator
base class, which can be used to process listened events and acknowledged
grobs:

@itemize
@item @code{virtual void initialize ()}
@item @code{void start_translation_timestep ()}
@item @code{void process_music ()}
@item @code{void process_acknowledged ()}
@item @code{void stop_translation_timestep ()}
@item @code{virtual void finalize ()}
@end itemize

These methods are listed in order of translation time, with
@code{initialize ()} and @code{finalize ()} bookending the whole
process.  @code{initialize ()} can be used for one-time initialization
of context properties before translation starts, whereas
@code{finalize ()} is often used to tie up loose ends at the end of
translation: for example, an unterminated spanner might be completed
automatically or reported with a warning message.

@subsection Translation process

At each timestep in the music, translation proceeds by calling the
following methods in turn:

@code{start_translation_timestep ()} is called before any user information enters
the translators, i.e., no property operations (\set, \override, etc.) or events
have been processed yet.

@code{process_music ()} and @code{process_acknowledged ()} are called after events
have been heard, or grobs have been acknowledged.  The latter tends to be used
exclusively with engravers which only acknowledge grobs, whereas the former is
the default method for main processing within engravers.

@code{stop_translation_timestep ()} is called after all user information has been
processed prior to beginning the translation for the next timestep.

@subsection Preventing garbage collection for SCM member variables

In certain cases, an engraver might need to ensure private Scheme variables
(with type SCM) do not get swept away by Guile's garbage collector: for example,
a cache of the previous key signature which must persist persist between timesteps.
The method @code{virtual derived_mark () const} can be used in such cases to mark
such objects as follows:

@example
Engraver_name::derived_mark ()
@{
  scm_gc_mark (private_scm_member_)
@}
@end example


@subsection Listening to music events

External interfaces to to the engraver are implemented by protected
macros including one or more of the following:

@itemize
@item @code{DECLARE_TRANSLATOR_LISTENER (event_name)}
@item @code{IMPLEMENT_TRANSLATOR_LISTENER (Engraver_name, event_name)}
@end itemize

@noindent
where @var{event_name} is the type of event required to provide the
input the engraver needs and @var{Engraver_name} is the name of the
engraver.

Following declaration of a listener, the method is implemented as follows:

@example
IMPLEMENT_TRANSLATOR_LISTENER (Engraver_name, event_name)
void
Engraver_name::listen_event_name (Stream event *event)
@{
  ...body of listener method...
@}
@end example

@subsection Acknowledging grobs

Some engravers also need information from grobs as they are created
and as they terminate.  The mechanism and methods to obtain this
information are set up by the macros:

@itemize
@item @code{DECLARE_ACKNOWLEDGER (grob_interface)}
@item @code{DECLARE_END_ACKNOWLEDGER (grob_interface)}
@end itemize

where @var{grob_interface} is an interface supported by the
grob(s) which should be acknowledged.  For example, the following
code would declare acknowledgers for a @code{NoteHead} grob (via the
@code{note-head-interface}) and any grobs which support the
@code{side-position-interface}:

@example
@code{DECLARE_ACKNOWLEDGER (note_head)}
@code{DECLARE_ACKNOWLEDGER (side_position)}
@end example

The @code{DECLARE_END_ACKNOWLEDGER ()} macro sets up a spanner-specific
acknowledger which will be called whenever a spanner ends.

Following declaration of an acknowledger, the method is coded as follows:

@example
void
Engraver_name::acknowledge_interface_name (Grob_info info)
@{
  ...body of acknowledger method...
@}
@end example

@subsection Engraver declaration/documentation

An engraver must have a public macro

@itemize
@item @code{TRANSLATOR_DECLARATIONS (Engraver_name)}
@end itemize

@noindent
where @code{Engraver_name} is the name of the engraver.  This
defines the common variables and methods used by every engraver.

At the end of the engraver file, one or both of the following
macros are generally called to document the engraver in the
Internals Reference:

@itemize
@item @code{ADD_ACKNOWLEDGER (Engraver_name, grob_interface)}
@item @code{ADD_TRANSLATOR (Engraver_name, Engraver_doc,
    Engraver_creates, Engraver_reads, Engraver_writes)}
@end itemize

@noindent
where @code{Engraver_name} is the name of the engraver, @code{grob_interface}
is the name of the interface that will be acknowledged,
@code{Engraver_doc} is a docstring for the engraver,
@code{Engraver_creates} is the set of grobs created by the engraver,
@code{Engraver_reads} is the set of properties read by the engraver,
and @code{Engraver_writes} is the set of properties written by
the engraver.

@node Callback tutorial
@section Callback tutorial

FIXME -- This is a placeholder for a tutorial on callback functions.

@node LilyPond scoping
@section LilyPond scoping

The Lilypond language has a concept of scoping, ie you can do

@example
foo = 1

#(begin
   (display (+ foo 2)))
@end example

@noindent with @code{\paper}, @code{\midi} and @code{\header} being
nested scope inside the .ly file-level scope.  @w{@code{foo = 1}} is
translated in to a scheme variable definition.

This implemented using modules, with each scope being an anonymous
module that imports its enclosing scope's module.

The reason to put some functions (@qq{builtin}) outside the .ly level,
is that in case of

@example
lilypond a.ly b.ly
@end example

@noindent
we want to reuse the built-in definitions, without changes
effected in a.ly leaking into the processing of b.ly.

Maintaining this scoping when one .ly file can be included in another
.ly file can be challenging.  A @code{define-public-toplevel} macro
has been created in order to handle a difficulty caused by the modules
being not the same when a .ly file is included into another.
This provided a way to define all markup commands in the same module.
At this time, we have found no easier way to define a function in a given
module (not the current one) than to define this macro.

With this architecture, the guile module system is not bypassed:
module-define!, module-export!  and module-ref are all guile module
primitives.

A second reason for using this current architecture is to avoid memory
leaks that could occur when running multiple files if toplevel
functions were registered permanently.