LilyPond -- Contributor's Guide
*******************************

This manual documents contributing to LilyPond version 2.13.7.  It
discusses technical issues and policies that contributors should follow.

   For more information about how this manual fits with the other
documentation, or to read this manual in other formats, see *note
Manuals: (lilypond-general)Manuals.

   If you are missing any manuals, the complete documentation can be
found at `http://www.lilypond.org/'.

Table of Contents
*****************

Toplevel README
2 Toplevel README
  2.1 Versioning
  2.2 Downloading
  2.3 Compilation
  2.4 Documentation
  2.5 Comments
  2.6 Bugs


Table of Contents
*****************

LilyPond -- Contributor's Guide
1 Starting with git
  1.1 Getting the source code
    1.1.1 Git introduction
    1.1.2 Git user configuration
    1.1.3 Main source code
    1.1.4 Documentation translations source code
    1.1.5 Other branches
    1.1.6 Other locations for git
  1.2 Updating the source code
    1.2.1 Importance of updating
    1.2.2 Updating command
    1.2.3 Resolving conflicts
  1.3 Sharing your changes
    1.3.1 Producing a patch
    1.3.2 Committing directly
  1.4 Advanced git stuff
    1.4.1 Introduction to Git concepts
    1.4.2 Git commands for managing several branches
    1.4.3 Working on LilyPond sources with several branches
    1.4.4 Git log
    1.4.5 Applying git patches
    1.4.6 Reverting all local changes
  1.5 Git on Windows
    1.5.1 Background to nomenclature
    1.5.2 Installing git
    1.5.3 Initialising Git
    1.5.4 Git GUI
    1.5.5 Personalising your local git repository
    1.5.6 Checking out a branch
    1.5.7 Updating files from `remote/origin/master'
    1.5.8 Editing files
    1.5.9 Sending changes to `remotes/origin/master'
    1.5.10 Resolving merge conflicts
    1.5.11 Other actions
  1.6 Other git documentation
2 Compiling LilyPond
  2.1 Compiling from source
    2.1.1 Downloading source code
    2.1.2 Requirements
      Compilation
      Running requirements
      Requirements for building documentation
    2.1.3 Building LilyPond
      Compiling
      Compiling for multiple platforms
      Compiling outside the source tree
      Useful `make' variables
    2.1.4 Building documentation
      Commands for building documentation
      Building documentation without compiling LilyPond
    2.1.5 Testing LilyPond
    2.1.6 Problems
      Bison 1.875
      Compiling on MacOS X
      Solaris
      FreeBSD
      International fonts
  2.2 Concurrent Stable and Development Versions
  2.3 Using a Virtual Machine to Compile Lilypond
3 Documentation work
  3.1 Introduction to documentation work
  3.2 Documentation suggestions
  3.3 Texinfo introduction and usage policy
    3.3.1 Texinfo introduction
    3.3.2 Documentation files
    3.3.3 Sectioning commands
    3.3.4 LilyPond formatting
    3.3.5 Text formatting
    3.3.6 Syntax survey
    3.3.7 Other text concerns
  3.4 Documentation policy
    3.4.1 Books
    3.4.2 Section organization
    3.4.3 Checking cross-references
    3.4.4 General writing
    3.4.5 Technical writing style
  3.5 Tips for writing docs
  3.6 Updating doc with `convert-ly'
  3.7 Translating the documentation
    3.7.1 Getting started with documentation translation
      Translation requirements
      Which documentation can be translated
      Starting translation in a new language
    3.7.2 Documentation translation details
      Files to be translated
      Translating the Learning Manual and other Texinfo documentation
      Translating the Notation Reference and Application Usage
      Translating the Documentation index `index.html.in'
    3.7.3 Documentation translation maintenance
      Check state of translation
      Updating documentation translation
    3.7.4 Translations management policies
      Maintaining without updating translations
      Managing documentation translation with Git
    3.7.5 Technical background
4 Website work
  4.1 Introduction to website work
  4.2 Translating the website
5 LSR work
  5.1 Introduction to LSR
  5.2 Adding and editing snippets
  5.3 Approving snippets
  5.4 LSR to Git
  5.5 Fixing snippets in LilyPond sources
  5.6 Updating LSR to a new version
6 Issues
  6.1 Introduction to issues
  6.2 Issue classification
  6.3 Adding issues to the tracker
7 Regression tests
  7.1 Introduction to regression tests
  7.2 Current regtest output
  7.3 Comparison regtest output
  7.4 MusicXML tests
8 Programming work
  8.1 Overview of LilyPond architecture
  8.2 LilyPond programming languages
    8.2.1 C++
    8.2.2 GNU Bison
    8.2.3 GNU Make
    8.2.4 GUILE or Scheme
    8.2.5 MetaFont
    8.2.6 PostScript
    8.2.7 Python
  8.3 Programming without compiling
    8.3.1 Modifying distribution files
    8.3.2 Desired file formatting
  8.4 Finding functions
    8.4.1 Using the ROADMAP
    8.4.2 Using grep to search
    8.4.3 Using git grep to search
    8.4.4 Searching on the git repository at Savannah
  8.5 Code style
    8.5.1 Handling errors
    8.5.2 Languages
    8.5.3 Filenames
    8.5.4 Indentation
    8.5.5 Classes and Types
    8.5.6 Members
    8.5.7 Macros
    8.5.8 Broken code
    8.5.9 Naming
    8.5.10 Messages
    8.5.11 Localization
  8.6 Debugging LilyPond
    8.6.1 Debugging overview
    8.6.2 Compiling with debugging information
    8.6.3 Typical gdb usage
    8.6.4 Typical .gdbinit files
    8.6.5 Using Guile interactively with LilyPond
  8.7 Adding or modifying features
    8.7.1 Write the code
    8.7.2 Write regression tests
    8.7.3 Write convert-ly rule
    8.7.4 Automatically update documentation, snippets, and regtests
    8.7.5 Manually update documentation, snippets, and regtests
    8.7.6 Write NEWS entry
    8.7.7 Verify successful build
    8.7.8 Verify regression test
    8.7.9 Post patch for comments
    8.7.10 Push patch
    8.7.11 Closing the issues
9 Release work
  9.1 Development phases
  9.2 Minor release checklist
  9.3 Major release checklist
  9.4 Making a release
Appendix A GNU Free Documentation License


1 Starting with git
*******************

The goal of this chapter is to provide all the git commands that
contributors should know for basic lilypond development.  However, to
complete or present in another form the introduction to Git usage in
this chapter, it may be a good idea to look at the other Git
documentation listed in *note Other git documentation::.

1.1 Getting the source code
===========================

1.1.1 Git introduction
----------------------

The source code is kept in a Git respository.  This allows us to track
changes to files, and for multiple people to work on the same set of
files efficiently.

   After downloading the source code, it is important to update the
repository by *note Updating the source code::.

          Note: These instructions assume that you are using the
          command-line version of Git 1.5 or higher.  Windows users
          should skip to *note Git on Windows::.

1.1.2 Git user configuration
----------------------------

Some useful cofiguration can be performed automatically; cut and paste
the following section:

     git config --global color.ui auto

   To configure git to automatically use your name and email address
for commits and patches, edit the below lines by changing all the
`MY...' entries:

     git config --global user.name "MYNAME"
     git config --global user.email MYEMAIL@EXAMPLE.NET

1.1.3 Main source code
----------------------

To get the main source code and documentation,

     mkdir lilypond; cd lilypond
     git init
     git remote add -f -t master -m master origin git://git.sv.gnu.org/lilypond.git/
     git checkout -b master origin/master

1.1.4 Documentation translations source code
--------------------------------------------

To translate the documentation,

     mkdir lilypond-translation; cd lilypond-translation
     git init
     git remote add -f -t lilypond/translation -m lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
     git checkout -b lilypond/translation origin/lilypond/translation

1.1.5 Other branches
--------------------

Most contributors will never need to touch the other branches.  If you
wish to do so, you will need more familiarity with git; please see
*note Other git documentation::.

   * `dev/XYZ': These branches are for individual developers.  They
     store code which is not yet stable enough to be added to the
     `master' branch.

   * `stable/XYZ': The branches are kept for archival reasons.


   Another item of interest might be the Grand Unified Builder, our
cross-platform building tool.  Since it is used by projects as well, it
is not stored in our gub repository.  For more info, see
`http://lilypond.org/gub'.  The git location is:

     http://github.com/janneke/gub

1.1.6 Other locations for git
-----------------------------

If you have difficulty connecting to most of the repositories listed in
earlier sections, try:

     http://git.sv.gnu.org/r/lilypond.git
     git://git.sv.gnu.org/lilypond.git
     ssh://git.sv.gnu.org/srv/git/lilypond.git

   Using HTTP protocol is slowest, so it is not recommended unless both
SSH and Git protocols fail, which happens e.g. if you connect to
internet through a router that filters out Git and/or SSH connections.

1.2 Updating the source code
============================

1.2.1 Importance of updating
----------------------------

In a large project like LilyPond, contributors sometimes edit the same
file at the same time.  As long as everybody updates their version of
the file with the most recent changes (_pulling_), there are generally
no problems with this multiple-person editing.  However, big problems
can arise if you do not pull before attempting to commit.  If this
occurs, see *note Resolving conflicts::.

1.2.2 Updating command
----------------------

Whenever you are asked to pull, it means you should update your local
copy of the repository with the changes made by others on the remote
`git.sv.gnu.org' repository:

     git pull -r

The `-r' option is short for `--rebase'.  If you don't edit translated
documentation and don't want to type `-r' every time, add `rebase =
true' to the master branch in your `.git/config', like so:

     [branch "master"]
             remote = origin
             merge = refs/heads/master
             rebase = true

          Note: translators and documentation editors, if you have
          changed committishes in the head of translated files using
          commits you have not yet pushed to `git.sv.gnu.org', please
          do not rebase.  If you want to avoid wondering whether you
          should rebase each time you pull, please always use
          committishes from master and/or lilypond/translation branch
          on `git.sv.gnu.org', which in particular implies that you
          must push your changes to documentation except committishes
          updates (possibly after having rebased), then update the
          committishes and push them.

1.2.3 Resolving conflicts
-------------------------

Occasionally an update may result in conflicts - this happens when you
and somebody else have modified the same part of the same file and git
cannot figure out how to merge the two versions together.  When this
happens, you must manually merge the two versions.

   If you need some documentation to understand and resolve conflicts,
see paragraphs _How conflicts are presented_ and _How to resolve
conflicts_ in `git merge' man page.

   If all else fails, you can follow the instructions in *note
Reverting all local changes::.  Be aware that this eliminates any
changes you have made!

1.3 Sharing your changes
========================

1.3.1 Producing a patch
-----------------------

Once you have finished editing your files, checked that your changes
meet the *note Code style::, and/or *note Documentation policy::,
properly set up your name and email in *note Git user configuration::,
and checked that the entire thing compiles, you may:

     git commit -a
     git format-patch origin

   The commit should include a brief message describing the change.
This consists of a one-line summary describing the change, and if
necessary a blank line followed by several lines giving the details:

     Did household chores.

     I hung up the wet laundry and then washed the car.  I also
     vacuumed the floors, rinsed the dirty dishes, fed the cat, and
     recalibrated the temporal flux machine.

   If the change is to the documentation only then the one-line summary
should be prefixed with "Docs: ".

   If you added a file to the source code, you must add it to git with:

     git add FILENAME

(and possibly modify the `GNUmakefile')

   These commands will produce one or more files named `0001-xyz',
`0002-abc', etc. in the top directory of the git tree.  Send an email
to <lilypond-devel@gnu.org> with these files attached, and a developer
will review and apply the patches to the main repository.  If your
patch is some translation work, you may send it to
<translations@lilynet.net> instead.

   To check if you have correctly added any new files, use:

     git status

If this command lists any _Changed but not updated_ files, you should
do a `git commit'.  If it lists any _Untracked files_, then you should
do a `git add'.

1.3.2 Committing directly
-------------------------

Most contributors do not have permission to commit directly.  If you do,
make sure you have set up your name and email in *note Git user
configuration::, then edit `.git/config': change the line

     url = git://git.sv.gnu.org/lilypond.git/

into

     url = ssh://USER@git.sv.gnu.org/srv/git/lilypond.git

where USER is your login name on Savannah.

   If you have not already done so, you should generate and upload a
SSH key: open `https://savannah.gnu.org/my/' in your browser, go to
`Account Configuration', then to something like `Edit SSH Keys', and
follow the instructions on that page.

   You may then:

     git push origin

   Note that recent versions of Git (Git 1.6.3 or later) will issue a
big warning if the above command is used.  The simplest solution is to
add a new section to `.git/config' that looks like this:

     [push]
             default = matching

Then `git push origin' will work as before.  For more details, consult
the `git push' man page.

1.4 Advanced git stuff
======================

          Note: This section is not necessary for normal contributors;
          these commands are presented for information for people
          interested in learning more about git.

It is possible to work with several branches on the same local Git
repository; this is especially useful for translators who may have to
deal with both `lilypond/translation' and a stable branch, e.g.
`stable/2.12'.

   Some Git commands are introduced first, then a workflow with several
Git branches of LilyPond source code is presented.

1.4.1 Introduction to Git concepts
----------------------------------

A bit of Git vocabulary will be explained below.  The following is just
introduction material; for better understanding of Git concepts, you
are invited to read further documentation, especially Git Community
Book at `http://book.git-scm.com/'.

   The `git pull origin' command above is just a shortcut for this
command:

     git pull git://git.sv.gnu.org/lilypond.git/ BRANCH:origin/BRANCH

where `BRANCH' is typically `master', `web' or `lilypond/translation';
if you do not know or remember, see *note Getting the source code:: to
remember which commands you issued or which source code you wanted to
get.

   A _commit_ is a set of changes made to the sources; it also includes
the committish of the parent commit, the name and e-mail of the
_author_ (the person who wrote the changes), the name and e-mail of the
_committer_ (the person who brings these changes into the Git
repository), and a commit message.

   A _committish_ is the SHA1 checksum of a commit, a number made of 40
hexadecimal digits, which acts as the internal unique identifier for
this commit.  To refer to a particular revision, don't use vague
references like the (approximative) date, simply copy and paste the
committish.

   A _branch_ is nothing more than a pointer to a particular commit,
which is called the _head_ of the branch; when referring to a branch,
one often acutally thinks about its head and the ancestor commits of
the head.

   Now we will explain the two last commands you used to get the source
code from Git - see *note Getting the source code::.

     git remote add -f -t BRANCH -m BRANCH origin git://git.sv.gnu.org/lilypond.git/
     git checkout -b BRANCH origin/BRANCH

   The `git remote' has created a branch called `origin/BRANCH' in your
local Git repository.  As this branch is a copy of the remote branch
web from git.sv.gnu.org LilyPond repository, it is called a _remote
branch_, and is meant to track the changes on the branch from
git.sv.gnu.org: it will be updated every time you run `git pull origin'
or `git fetch origin'.

   The `git checkout' command has created a branch named `BRANCH'.  At
the beginning, this branch is identical to `origin/BRANCH', but it will
differ as soon as you make changes, e.g. adding newly translated pages
or editing some documentation or code source file.  Whenever you pull,
you merge the changes from `origin/BRANCH' and `BRANCH' since the last
pulling.  If you do not have push (i.e. "write") access on
git.sv.gnu.org, your `BRANCH' will always differ from `origin/BRANCH'.
In this case, remember that other people working like you with the
remote branch `BRANCH' of git://git.sv.gnu.org/lilypond.git/ (called
`origin/BRANCH' on your local repository) know nothing about your own
`BRANCH': this means that whenever you use a committish or make a
patch, others expect you to take the latest commit of `origin/BRANCH'
as a reference.

   Finally, please remember to read the man page of every Git command
you will find in this manual in case you want to discover alternate
methods or just understand how it works.

1.4.2 Git commands for managing several branches
------------------------------------------------

Listing branches and remotes
............................

You can get the exact path or URL of all remotes with running

     git remote -v

   To list Git branches on your local repositories, run

     git branch     # list local branches only
     git branch -r  # list remote branches
     git branch -a  # list all branches

Checking out branches
.....................

To know the currently checked out branch, i.e. the branch whose source
files are present in your working tree, read the first line of the
output of

     git status

The currently checked out branch is also marked with an asterisk in the
output of `git branch'.

   You can check out another branch `OTHER_BRANCH', i.e. check out
`OTHER_BRANCH' to the working tree, by running

     git checkout OTHER_BRANCH

   Note that it is possible to check out another branch while having
uncommitted changes, but it is not recommended unless you know what you
are doing; it is recommended to run `git status' to check this kind of
issue before checking out another branch.

Merging branches
................

To merge branch `FOO' into branch `BAR', i.e. to "add" all changes made
in branch `FOO' to branch `BAR', run

     git checkout BAR
     git merge FOO

   If any conflict happens, see *note Resolving conflicts::.

   There are common usage cases for merging: as a translator, you will
often want to merge `master' into `lilypond/translation'; on the other
hand, the Translations meister wants to merge `lilypond/translation'
into `master' whenever he has checked that `lilypond/translation'
builds successfully.

1.4.3 Working on LilyPond sources with several branches
-------------------------------------------------------

Fetching new branches from git.sv.gnu.org
.........................................

To fetch and check out a new branch named `BRANCH' on git.sv.gnu.org,
run from top of the Git repository

     git config --add remote.origin.fetch +refs/heads/BRANCH:refs/remotes/origin/BRANCH
     git checkout --track -b BRANCH origin/BRANCH

   After this, you can pull `BRANCH' from git.sv.gnu.org with

     git pull origin

   Note that this command generally fetches all branches you added with
`git remote add' (when you initialized the repository) or `git config
--add', i.e. it updates all remote branches from remote `origin', then
it merges the remote branch tracked by current branch into current
branch.  For example, if your current branch is `master' -- which is
the case if you got the sources with the commands described in *note
Main source code:: and did not issue any `git checkout' command --
`origin/master' will be merged into `master'.

Local clones, or having several working trees
.............................................

If you play with several Git branches, e.g. `master',
`lilypond/translation', `stable/2.12'), you may want to have one source
and build tree for each branch; this is possible with subdirectories of
your local Git repository, used as local cloned subrepositories.  To
create a local clone for the branch named `BRANCH', run

     git checkout BRANCH
     git clone -l -s -n . SUBDIR
     cd SUBDIR
     git reset --hard

   Note that `SUBDIR' must be a directory name which does not already
exist.  In `SUBDIR', you can use all Git commands to browse revisions
history, commit and uncommit changes; to update the cloned
subrepository with changes made on the main repository, cd into
`SUBDIR' and run `git pull'; to send changes made on the subrepository
back to the main repository, run `git push' from `SUBDIR'.  Note that
only one branch (the currently checked out branch) is created in the
subrepository by default; it is possible to have several branches in a
subrepository and do usual operations (checkout, merge, create,
delete...) on these branches, but this possibility is not detailed here.

   When you push `BRANCH' from `SUBDIR' to the main repository, and
`BRANCH' is checked out in the main repository, you must save
uncommitted changes (see `git stash') and do `git reset --hard' in the
main repository in order to apply pushed changes in the working tree of
the main repository.

1.4.4 Git log
-------------

The commands above don't only bring you the latest version of the
sources, but also the full history of revisions (revisons, also called
commits, are changes made to the sources), stored in the .git
directory.  You can browse this history with

     git log     # only shows the logs (author, committish and commit message)
     git log -p  # also shows diffs
     gitk        # shows history graphically

          Note: The `gitk' command may require a separate `gitk'
          package, available in the appropriate distribution's
          repositories.

1.4.5 Applying git patches
--------------------------

Well-formed git patches created with `git format-patch' should be
committed with the following command:

     git am PATCH

   Patches created without `git format-patch' can be applied in two
steps.  The first step is to apply the patch to the working tree:

     git apply PATCH

The second step is to commit the changes and give credit to the author
of the patch.  This can be done with the following command:

     git commit -a --author="First Last <user@example.net>"

1.4.6 Reverting all local changes
---------------------------------

Sometimes git will become hopelessly confused, and you just want to get
back to a known, stable state.  This command destroys any local changes
you have made, but at least you get back to the current online version:

     git reset --hard origin/master

1.5 Git on Windows
==================

1.5.1 Background to nomenclature
--------------------------------

Git is a system for tracking the changes made to source files by a
distributed set of editors.  It is designed to work without a master
repository, but we have chosen to have a master respository for
LilyPond files.  Editors hold a local copy of the master repository
together with any changes they have made locally.  Local changes are
held in a local `branch', of which there may be several, but these
instructions assume you are using just one.  The files visible in the
local repository always correspond to those on the currently `checked
out' local branch.

   Files are edited on a local branch, and in that state the changes
are said to be `unstaged'.  When editing is complete, the changes are
moved to being `staged for commit', and finally the changes are
`committed' to the local branch.  Once committed, the changes (called a
`commit') are given a unique 40-digit hexadecimal reference number
called the `Committish' or `SHA1 ID' which identifies the commit to
Git.  Such committed changes can be sent to the master repository by
`pushing' them (if you have write permission) or by sending them by
email to someone who has, either as a complete file or as a `diff' or
`patch' (which send just the differences from the master repository).

1.5.2 Installing git
--------------------

Obtain Git from `http://code.google.com/p/msysgit/downloads/list'
(note, not msysGit, which is for Git developers and not PortableGit,
which is not a full git installation) and install it.

   Note that most users will not need to install SSH.  That is not
required until you have been granted direct push permissions to the
master git repository.

   Start Git by clicking on the desktop icon.  This will bring up a
command line bash shell.  This may be unfamiliar to Windows users.  If
so, follow these instructions carefully.  Commands are entered at a $
prompt and are terminated by keying a newline.

1.5.3 Initialising Git
----------------------

Decide where you wish to place your local Git repository, creating the
folders in Windows as necessary.  Here we call the folder to contain
the repository `[path]/Git', but if you intend using Git for other
projects a directory name like `lilypond-git' might be better.  You
will need to have space for around 100Mbytes.

   Start the Git bash shell by clicking on the desk-top icon installed
with Git and type

     cd [path]/Git

   to position the shell at your new Git repository.

   Note: if [path] contains folders with names containing spaces use

     cd "[path]/Git"

   Then type

     git init

   to initialize your Git repository.

   Then type (all on one line; the shell will wrap automatically)

     git remote add -f -t master origin git://git.sv.gnu.org/lilypond.git

   to download the lilypond master files.

          Note: Be patient!  Even on a broadband connection this can
          take 10 minutes or more.  Wait for lots of [new tag] messages
          and the $ prompt.

   We now need to generate a local copy of the downloaded files in a
new local branch.  Your local branch needs to have a name.  It is usual
to call it `master' and we shall do that here.

   To do this, type

     git checkout -b master origin/master

   This creates a second branch called `master'.  You will see two
warnings (ignore these), and a message advising you that your local
branch `master' has been set up to track the remote branch.  You now
have two branches, a local branch called `master', and a tracking
branch called `origin/master', which is a shortened form of
`remotes/origin/master'.

   Return to Windows Explorer and look in your Git repository.  You
should see lots of folders.  For example, the LilyPond documentation
can be found in [path]/Git/Documentation/.

   The Git bash shell is terminated by typing `exit' or by clicking on
the usual Windows close-window widget.

1.5.4 Git GUI
-------------

Almost all subsequent work will use the Git Graphical User Interface,
which avoids having to type command line commands. To start Git GUI
first start the Git bash shell by clicking on the desktop icon, and type

     cd [path]/Git
     git gui

   The Git GUI will open in a new window.  It contains four panels and
7 pull-down menus.  At this stage do not use any of the commands under
Branch, Commit, Merge or Remote.  These will be explained later.

   The top panel on the left contains the names of files which you are
in the process of editing (Unstaged Changes), and the lower panel on
the left contains the names of files you have finished editing and have
staged ready for committing (Staged Changes).  At present, these panels
will be empty as you have not yet made any changes to any file.  After
a file has been edited and saved the top panel on the right will
display the differences between the edited file selected in one of the
panels on the left and the last version committed on the current branch.

   The panel at bottom right is used to enter a descriptive message
about the change before committing it.

   The Git GUI is terminated by entering CNTL-Q while it is the active
window or by clicking on the usual Windows close-window widget.

1.5.5 Personalising your local git repository
---------------------------------------------

Open the Git GUI, click on

     Edit -> Options

   and enter your name and email address in the left-hand (Git
Repository) panel.  Leave everything else unchanged and save it.

   Note that Windows users must leave the default setting for line
endings unchanged.  All files in a git repository must have lines
terminated by just a LF, as this is required for Merge to work, but
Windows files are terminated by CRLF by default.  The git default
setting causes the line endings of files in a Windows git repository to
be flipped automatically between LF and CRLF as required.  This enables
files to be edited by any Windows editor without causing problems in
the git repository.

1.5.6 Checking out a branch
---------------------------

At this stage you have two branches in your local repository, both
identical.  To see them click on

     Branch -> Checkout

   You should have one local branch called `master' and one tracking
branch called `origin/master'.  The latter is your local copy of the
`remotes/origin/master' branch in the master LilyPond repository.  The
local `master' branch is where you will make your local changes.

   When a particular branch is selected, i.e., checked out, the files
visible in your repository are changed to reflect the state of the
files on that branch.

1.5.7 Updating files from `remote/origin/master'
------------------------------------------------

Before starting the editing of a file, ensure your local repository
contains the latest version of the files in the remote repository by
first clicking

     Remote -> Fetch from -> origin

in the Git GUI.

   This will place the latest version of every file, including all the
changes made by others, into the `origin/master' branch of the tracking
branches in your git repository.  You can see these files by checking
out this branch, but you must _never_ edit any files while this branch
is checked out.  Check out your local `master' branch again.

   You then need to merge these fetched files into your local `master'
branch by clicking on

     Merge -> Local Merge

and if necessary select the local `master' branch.

   Note that a merge cannot be completed if you have made any local
changes which have not yet been committed.

   This merge will update all the files in the `master' branch to
reflect the current state of the `origin/master' branch.  If any of the
changes conflict with changes you have made yourself recently you will
be notified of the conflict (see below).

1.5.8 Editing files
-------------------

First ensure your `master' branch is checked out, then simply edit the
files in your local Git repository with your favourite editor and save
them back there.  If any file contains non-ASCII characters ensure you
save it in UTF-8 format.  Git will detect any changes whenever you
restart Git GUI and the file names will then be listed in the Unstaged
Changes panel.  Or you can click the Rescan button to refresh the panel
contents at any time.  You may break off and resume editing any time.

   The changes you have made may be displayed in diff form in the top
right-hand panel of Git GUI by clicking on the file name shown in one
of the left panels.

   When your editing is complete, move the files from being Unstaged to
Staged by clicking the document symbol to the left of each name.  If
you change your mind it can be moved back by clicking on the ticked box
to the left of the name.

   Finally the changes you have made may be committed to your `master'
branch by entering a brief message in the Commit Message box and
clicking the Commit button.

   If you wish to amend your changes after a commit has been made, the
original version and the changes you made in that commit may be
recovered by selecting

     Commit -> Amend Last Commit

or by checking the Amend Last Commit radio button at bottom right.
This will return the changes to the Staged state, so further editing
made be carried out within that commit.  This must only be done
_before_ the changes have been Pushed or sent to your mentor for
Pushing - after that it is too late and corrections have to be made as
a separate commit.

1.5.9 Sending changes to `remotes/origin/master'
------------------------------------------------

If you do not have write access to `remotes/origin/master' you will
need to send your changes by email to someone who does.

   First you need to create a diff or patch file containing your
changes.  To create this, the file must first be committed.  Then
terminate the Git GUI.  In the git bash shell first cd to your Git
repository with

     cd [path]/Git

   if necessary, then produce the patch with

     git format-patch origin

   This will create a patch file for all the locally committed files
which differ from `origin/master'.  The patch file can be found in
[path]/Git and will have a name formed from the commit message.

1.5.10 Resolving merge conflicts
--------------------------------

As soon as you have committed a changed file your local `master' branch
has diverged from `origin/master', and will remain diverged until your
changes have been committed in `remotes/origin/master' and Fetched back
into your `origin/master' branch.  Similarly, if a new commit has been
made to `remotes/origin/master' by someone else and Fetched, your local
`master' branch is divergent.  You can detect a divergent branch by
clicking on

     Repository -> Visualise all branch history

   This opens up a very useful new window called `gitk'.  Use this to
browse all the commits made by yourself and others.

   If the diagram at top left of the resulting window does not show
your `master' tag on the same node as the `remotes/origin/master' tag
your branch has diverged from `origin/master'.  This is quite normal if
files you have modified yourself have not yet been Pushed to
`remotes/origin/master' and Fetched, or if files modified and committed
by others have been Fetched since you last Merged `origin/master' into
your local `master' branch.

   If a file being merged from `origin/master' differs from one you
have modified in a way that cannot be resolved automatically by git,
Merge will report a Conflict which you must resolve by editing the file
to create the version you wish to keep.

   This could happen if the person updating `remotes/origin/master' for
you has added some changes of his own before committing your changes to
`remotes/origin/master', or if someone else has changed the same file
since you last fetched the file from `remotes/origin/master'.

   Open the file in your editor and look for sections which are
delimited with ...

   [to be completed when I next have a merge conflict to be sure I give
the right instructions  -td]

1.5.11 Other actions
--------------------

The instructions above describe the simplest way of using git on
Windows.  Other git facilities which may usefully supplement these
include

   * Using multiple local branches (Create, Rename, Delete)

   * Resetting branches

   * Cherry-picking commits

   * Pushing commits to remote/origin/master

   * Using gitk to review history


   Once familiarity with using git on Windows has been gained the
standard git manuals can be used to learn about these.

1.6 Other git documentation
===========================

   * Official git man pages:
     `http://www.kernel.org/pub/software/scm/git/docs/'

   * More in-depth tutorials: `http://git-scm.com/documentation'

   * Book about git: Pro Git (http://progit.org/)


2 Compiling LilyPond
********************

2.1 Compiling from source
=========================

2.1.1 Downloading source code
-----------------------------

Download source

   * tarballs from `http://lilypond.org/download/' by HTTP.

   * tarballs from `http://download.linuxaudio.org/lilypond/' by HTTP.

   * GIT from git.sv.gnu.org
     (http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary)

          git clone git://git.sv.gnu.org/lilypond.git

     The repository does not contain generated files.  To create
     `configure', run
          ./autogen.sh

   For information on packaging, see `http://lilypond.org/devel'.

2.1.2 Requirements
------------------

Compilation
...........

In addition to the packages needed for running LilyPond (see below), you
need the following extra packages for building.

   Below is a full list of packages needed to build LilyPond.  However,
for most common distributions there is an easy way of installing most
all build dependencies in one go

Distribution                         Command
-------------------------------------------------------------------------- 
Debian, Ubuntu                       `sudo apt-get build-dep lilypond'
Fedora, RHEL                         `sudo yum-builddep lilypond'
openSUSE, SLED                       `sudo zypper --build-deps-only
                                     source-install lilypond'

   When installing a binary package FOO, you may need to install the
FOO-devel, libFOO-dev or FOO-dev package too.

   * FontForge (http://fontforge.sf.net/) 20060125 or newer.

   * MetaFont (http://metafont.tutorial.free.fr/) (mf-nowin, mf, mfw or
     mfont binaries) and MetaPost
     (http://cm.bell-labs.com/who/hobby/MetaPost.html) (mpost binary),
     usually packaged with a LaTeX distribution like tetex or texlive.

   * t1utils (http://www.lcdf.org/~eddietwo/type/#t1utils) (version
     1.33 or newer recommended).

   * New Century Schoolbook fonts, as PFB files.  These are shipped with
     X11 and Ghostscript, and are named `c059033l.pfb' `c059036l.pfb',
     `c059013l.pfb' and `c059016l.pfb'.

   * GUILE (http://www.gnu.org/software/guile/guile.html) (version
     1.8.2 or newer).  If you are installing binary packages, you may
     need to install guile-devel or guile-dev or libguile-dev too.

   * Texinfo (ftp://ftp.gnu.org/gnu/texinfo/) (version 4.11 or newer).

   * The GNU c++ compiler (http://gcc.gnu.org/) (version 3.4 or newer.
     4.x is strongly recommended).

   * Python (http://www.python.org) (version 2.4 or newer)

   * GNU Make (ftp://ftp.gnu.org/gnu/make/) (version 3.78 or newer).

   * gettext (http://www.gnu.org/software/gettext/gettext.html)
     (version 0.17 or newer).

   * Flex (http://www.gnu.org/software/flex/).

   * Perl (http://www.perl.org/).

   * GNU Bison (http://www.gnu.org/software/bison/).

   * All packages required for running, including development packages
     with header files and libraries.


Running requirements
....................

Running LilyPond requires proper installation of the following software

   * Freetype (http://www.freetype.org/) (version 2.1.10 or newer).

   * FontConfig (http://fontconfig.org/) (version 2.2 or newer).

   * Pango (http://www.pango.org/) (version 1.12 or newer).

   * GUILE (http://www.gnu.org/software/guile/guile.html) (version
     1.8.2 or newer), or patch 1.8.1 with
     `http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch'.

   * Python (http://www.python.org) (version 2.4 or newer).

   * Ghostscript (http://www.ghostscript.com) (version 8.15 or newer.
     8.60 recommended)

   * Dejaview.  (This is normally installed by default)

   International fonts are required to create music with international
text or lyrics.

Requirements for building documentation
.......................................

You can view the documentation online at `http://lilypond.org/doc/',
but you can also build it locally.  This process requires a successful
compile of LilyPond, and some additional tools and packages:

   * The netpbm utilities (http://netpbm.sourceforge.net/)

   * ImageMagick

   * International fonts (see input/regression/utf-8.ly for hints about
     which font packages are necessary for your platform)

   * Ghostscript 8.60 or newer, or 8.50 with the patch from
     `http://bugs.ghostscript.com/show_bug.cgi?id=688154' and the patch
     from `http://bugs.ghostscript.com/show_bug.cgi?id=688017'.

   * Texi2HTML (http://www.nongnu.org/texi2html/) 1.82 or newer

   * rsync

2.1.3 Building LilyPond
-----------------------

Compiling
.........

To install GNU LilyPond, type

     gunzip -c lilypond-x.y.z | tar xf -
     cd lilypond-x.y.z
     ./configure		# run with --help for applicable options
     make
     su -c 'make install'

If you are not root, you should choose a `--prefix' argument that
points into your home directory, e.g.

     ./configure --prefix=$HOME/usr

   If you encounter any problems, please see *note Problems::.

Compiling for multiple platforms
................................

If you want to build multiple versions of LilyPond with different
configuration settings, you can use the `--enable-config=CONF' option
of `configure'.  You should use `make conf=CONF' to generate the output
in `out-CONF'.  For example, suppose you want to build with and without
profiling, then use the following for the normal build

     ./configure --prefix=$HOME/usr/ --enable-checking
     make
     make install

   and for the profiling version, specify a different configuration

     ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
     make conf=prof
     make conf=prof install

Compiling outside the source tree
.................................

It is possible to compile LilyPond in a build tree different from the
source tree, with `--srcdir' option of `configure':

     mkdir lily-build && cd lily-build
     SOURCEDIR/configure --srcdir=SOURCEDIR

Useful `make' variables
.......................

If a less verbose build output if desired, the variable `QUIET_BUILD'
may be set to `1' on `make' command line, or in `local.make' at top of
the build tree.

2.1.4 Building documentation
----------------------------

This requires a successful compile of LilyPond, or using an external
LilyPond binary.

Commands for building documentation
...................................

The documentation is built by issuing

     make doc

   After compilation, the HTML documentation tree is available in
`out-www/offline-root/', and can be browsed locally.  Various portions
of the documentation can be found by looking in `out/' and `out-www'
subdirectories in other places in the source tree, but these are only
_portions_ of the docs.  Please do not complain about anything which is
broken in those places; the only complete set of documentation is in
`out-www/offline-root/' from the top of the source tree.

   The HTML, PDF and if available Info files can be installed into the
standard documentation path by issuing

     make install-doc

This also installs Info documentation with images if the installation
prefix is properly set; otherwise, instructions to complete proper
installation of Info documentation are printed on standard output.

   Compilation of documentation in Info format with images can be done
separately by issuing

     make info

Separate installation of this documentation is done by issuing

     make install-info

Note that to get the images in Info documentation, `install-doc' target
creates symbolic links to HTML and PDF installed documentation tree in
`PREFIX/share/info', in order to save disk space, whereas
`install-info' copies images in `PREFIX/share/info' subdirectories.

   It is possible to build a documentation tree in
`out-www/online-root/', with special processing, so it can be used on a
website with content negotiation for automatic language selection; this
can be achieved by issuing

     make WEB_TARGETS=online doc

and both `offline' and `online' targets can be generated by issuing

     make WEB_TARGETS="offline online" doc

   Several targets are available to clean the documentation build and
help with maintaining documentation; an overview of these targets is
available with

     make help

from every directory in the build tree.  Most targets for documentation
maintenance are available from `Documentation/'; for more information,
see the Contributors' Guide, section _Documentation work_.

   The makefile variable `QUIET_BUILD' may be set to `1' for a less
verbose build output, just like for building the programs.



Known issues and warnings
.........................

The most time consuming task for building the documentation is running
LilyPond to build images of music, and there cannot be several
simultaneously running `lilypond-book' instances, so `-j' `make' option
does not significantly speed up the build process.  To help speed it
up, the makefile variable CPU_COUNT may be set in `local.make' or on
the command line to the number of `.ly' files that LilyPond should
process simultaneously, e.g. on a bi-processor or dual core machine

     make -j3 CPU_COUNT=3 doc

The recommended value of CPU_COUNT is one plus the number of cores or
processors, but it is advisable to set it to a smaller value if your
system has not enough RAM to run that many simultaneous LilyPond
instances.

   If source files have changed since last documentation build, output
files that need to be rebuilt are normally rebuilt, even if you do not
run `make doc-clean' first.  However, building dependencies in the
documentation are so complex that rebuilding of some targets may not be
triggered as they should be; a workaround is to force rebuilding by
touching appropriate files, e.g.

     touch Documentation/notation/*.itely
     touch Documentation/snippets/*.ly

Building documentation without compiling LilyPond
.................................................

The documentation can be built locally without compiling LilyPond
binary, if LilyPond is already installed on your system.

   From a fresh Git checkout, do

     ./autogen.sh   # ignore any warning messages
     cp GNUmakefile.in GNUmakefile
     make -C python
     nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc

   Please note that this may break sometimes - for example, if a new
feature is added with a test file in input/regression, even the latest
development release of LilyPond will fail to build the docs.

   You may build the manual without building all the `input/*' stuff
(i.e. mostly regression tests): change directory, for example to
`Documentation/', issue `make doc', which will build documentation in a
subdirectory `out-www' from the source files in current directory.  In
this case, if you also want to browse the documentation in its
post-processed form, change back to top directory and issue

     make out=www WWW-post


Known issues and warnings
.........................

You may also need to create a script for `pngtopnm' and `pnmtopng'.  On
GNU/Linux, I use this:

export LD_LIBRARY_PATH=/usr/lib
exec /usr/bin/pngtopnm "$@"

   On MacOS X with fink, I use this:

export DYLD_LIBRARY_PATH=/sw/lib
exec /sw/bin/pngtopnm "$@"

   On MacOS X with macports, you should use this:

export DYLD_LIBRARY_PATH=/opt/local/lib
exec /opt/local/bin/pngtopnm "$@"

2.1.5 Testing LilyPond
----------------------

LilyPond comes with an extensive suite that exercises the entire
program.  This suite can be used to automatically check the impact of a
change.  This is done as follows

     make test-baseline
     _## apply your changes, compile_
     make check

   This will leave an HTML page `out/test-results/index.html'.  This
page shows all the important differences that your change introduced,
whether in the layout, MIDI, performance or error reporting.

   To rerun tests, use

     make test-redo           _## redo files differing from baseline_
     make test-clean          _## remove all test results_

and then run `make check' again.

   For tracking memory usage as part of this test, you will need GUILE
CVS; especially the following patch:
`http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch'.

   For checking the coverage of the test suite, do the following

     ./scripts/auxiliar/build-coverage.sh
     _# uncovered files, least covered first_
     ./scripts/auxiliar/coverage.py  --summary out-cov/*.cc
     _# consecutive uncovered lines, longest first_
     ./scripts/auxiliar/coverage.py  --uncovered out-cov/*.cc

2.1.6 Problems
--------------

For help and questions use <lilypond-user@gnu.org>.  Send bug reports
to <bug-lilypond@gnu.org>.

   Bugs that are not fault of LilyPond are documented here.

Bison 1.875
...........

There is a bug in bison-1.875: compilation fails with "parse error
before `goto'" in line 4922 due to a bug in bison.  To fix, please
recompile bison 1.875 with the following fix

     $ cd lily; make out/parser.cc
     $ vi +4919 out/parser.cc
     # append a semicolon to the line containing "__attribute__ ((__unused__))
     # save
     $ make

Compiling on MacOS X
....................

Here are special instructions for compiling under MacOS X.  These
instructions assume that dependencies are installed using MacPorts.
(http://www.macports.org/) The instructions have been tested using OS X
10.5 (Leopard).

   First, install the relevant dependencies using MacPorts.

   Next, add the following to your relevant shell initialization files.
This is `~/.profile' by default. You should create this file if it does
not exist.

     export PATH=/opt/local/bin:/opt/local/sbin:$PATH
     export DYLD_LIBRARY_PATH=/System/Library/Frameworks/ApplicationServices.framework/Versions/A/Frameworks/ImageIO.framework/Versions/A/Resources:\
     /opt/local/lib:$DYLD_LIBRARY_PATH

   Now you must edit the generated `config.make' file.  Change

     FLEXLEXER_FILE = /usr/include/FlexLexer.h

to:

     FLEXLEXER_FILE = /opt/local/include/FlexLexer.h

   At this point, you should verify that you have the appropriate fonts
installed with your ghostscript installation. Check `ls
/opt/local/share/ghostscript/fonts' for: 'c0590*' files (.pfb, .pfb and
.afm).  If you don't have them, run the following commands to grab them
from the ghostscript SVN server and install them in the appropriate
location:

     svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
     sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
     rm -rf urw-fonts-1.07pre44

   Now run the `./configure' script. To avoid complications with
automatic font detection, add

     --with-ncsb-dir=/opt/local/share/ghostscript/fonts

Solaris
.......

Solaris7, ./configure

   `./configure' needs a POSIX compliant shell.  On Solaris7, `/bin/sh'
is not yet POSIX compliant, but `/bin/ksh' or bash is.  Run configure
like

     CONFIG_SHELL=/bin/ksh ksh -c ./configure

or

     CONFIG_SHELL=/bin/bash bash -c ./configure

FreeBSD
.......

To use system fonts, dejaview must be installed.  With the default
port, the fonts are installed in `usr/X11R6/lib/X11/fonts/dejavu'.

   Open the file `$LILYPONDBASE/usr/etc/fonts/local.conf' and add the
following line just after the `<fontconfig>' line.  (Adjust as necessary
for your hierarchy.)

     <dir>/usr/X11R6/lib/X11/fonts</dir>

International fonts
...................

On Mac OS X, all fonts are installed by default.  However, finding all
system fonts requires a bit of configuration; see this post
(http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html)
on the `lilypond-user' mailing list.

   On Linux, international fonts are installed by different means on
every distribution.  We cannot list the exact commands or packages that
are necessary, as each distribution is different, and the exact package
names within each distribution changes.  Here are some hints, though:

Red Hat Fedora

    taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
         ttfonts-zh_CN fonts-ja fonts-hebrew

Debian GNU/Linux

   apt-get install emacs-intl-fonts xfonts-intl-.* \
        ttf-kochi-gothic ttf-kochi-mincho \
        xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi

2.2 Concurrent Stable and Development Versions
==============================================

It can be useful to have both the stable and the development versions
of Lilypond available at once. One way to do this on GNU/Linux is to
install the stable version using the precompiled binary, and run the
development version from the source tree. After running `make all' from
the top directory of the Lilypond source files, there will be a binary
called `lilypond' in the `out' directory:

     <PATH TO>/lilypond/out/bin/lilypond

   This binary can be run without actually doing the `make install'
command. The advantage to this is that you can have all of the latest
changes available after pulling from git and running `make all',
without having to uninstall the old version and reinstall the new.

   So, to use the stable version, install it as usual and use the
normal commands:

     lilypond foobar.ly

   To use the development version, create a link to the binary in the
source tree by saving the following line in a file somewhere in your
`$PATH':

     exec <PATH TO>/lilypond/out/bin/lilypond "$@"

   Save it as `Lilypond' (with a capital L to distinguish it from the
stable `lilypond'), and make it executable:

     chmod +x Lilypond

   Then you can invoke the development version this way:

     Lilypond foobar.ly

   TODO: ADD

   - other compilation tricks for developers

2.3 Using a Virtual Machine to Compile Lilypond
===============================================

Since it is not possible to compile Lilypond on Windows, some
developers may find it useful to install a GNU/Linux virtual machine. A
disk image with a special remix of *Ubuntu* has been created for this
purpose. It has all of the Lilypond build dependencies in place, so
that once installed, it is ready to compile both Lilypond and the
Documentation.  The `lilybuntu' remix is available for download here:

     `http://prodet.hu/bert/lilydev/lilybuntu.iso'

   We do not necessarily recommend any one virtualization tool, however
the `lilybuntu' remix is known to work well on Sun VirtualBox
(http://www.virtualbox.org/wiki/Downloads), which is a free download.
Consult your virtualization software's documentation for instructions
on setting up the software and for general instructions on installing a
virtual machine.

   Steps to setting up `lilybuntu' in a virtual machine:

  1. Download the `lilybuntu' disk image.

  2. Install `lilybuntu'. You will use the `.iso' file as the boot
     disk. It should not be necessary to burn it to a DVD, but consult
     the documentation for your virtualization software for specific
     instructions. If possible, use at least the recommended amount of
     RAM for the virtual machine (384 MB on VirtualBox), and use a
     dynamically expanding virtual hard drive starting with at least
     5-6 GB of space, more if you can spare it.  The Ubuntu installer
     should be straightforward, although in the partitioning stage do
     not be afraid to select "use entire disk," since this is only your
     *virtual disk* and not your machine's actual hard drive.

  3. After installation is complete, restart the virtual machine. (If
     you are using *VirtualBox*, you may wish to install the "Guest
     Additions," which will allow you to use the virtual machine in
     full screen.)

  4. Open a *terminal*.  (`Applications > Accessories > Terminal')

  5. Open *Firefox* (there's an icon for it on the panel at the top of
     the screen) and go to the online Lilypond Contributor's Guide
     (http://lilypond.org/doc/v2.13/Documentation/devel/contrib-guide).

  6. To retrieve the Lilypond source code from `git', copy-and-paste
     each command from the CG "Main source code" section into the
     terminal. (paste into the terminal with keystroke `CTRL+SHIFT+V')

  7. Prepare to build Lilypond by running the configuration script.
     Type

          ./autogen.sh

     When it is finished you should be presented with the three most
     common `make' options:

          Type:
              make all       to build LilyPond
              make install   to install LilyPond
              make help      to see all possible targets

          Edit local.make for local Makefile overrides.

  8. First type `make all' to build Lilypond. This will take a while.

  9. When Lilypond is finished building, build the documentation by
     typing

          make doc

     Depending on your system specs it could take from 30-60 minutes to
     finish.


   At this point everything has been compiled.  You may install
Lilypond using `make install', or you may wish to set up your system
with concurrent stable and development versions as described in the
previous section.

3 Documentation work
********************

3.1 Introduction to documentation work
======================================

Our documentation tries to adhere to our *note Documentation policy::.
This policy contains a few items which may seem odd.  One policy in
particular is often questioned by potential contributors: we do not
repeat material in the Notation Reference, and instead provide links to
the "definitive" presentation of that information.  Some people point
out, with good reason, that this makes the documentation harder to
read.  If we repeated certain information in relevant places, readers
would be less likely to miss that information.

   That reasoning is sound, but we have two counter-arguments.  First,
the Notation Reference - one of _five_ manuals for users to read - is
already over 500 pages long.  If we repeated material, we could easily
exceed 1000 pages!  Second, and much more importantly, LilyPond is an
evolving project.  New features are added, bugs are fixed, and bugs are
discovered and documented.  If features are discussed in multiple
places, the documentation team must find every instance.  Since the
manual is so large, it is impossible for one person to have the
location of every piece of information memorized, so any attempt to
update the documentation will invariably omit a few places.  This second
concern is not at all theoretical; the documentation used to be plagued
with inconsistent information.

   If the documentation were targeted for a specific version - say,
LilyPond 2.10.5 - and we had unlimited resources to spend on
documentation, then we could avoid this second problem.  But since
LilyPond evolves (and that is a very good thing!), and since we have
quite limited resources, this policy remains in place.

   A few other policies (such as not permitting the use of tweaks in
the main portion of NR 1+2) may also seem counter-intuitive, but they
also stem from attempting to find the most effective use of limited
documentation help.

3.2 Documentation suggestions
=============================

Small additions
---------------

For additions to the documentation,

  1. Tell us where the addition should be placed. Please include both
     the section number and title (i.e. "LM 2.13 Printing lyrics").

  2. Please write exact changes to the text.

  3. A formal patch to the source code is _not_ required; we can take
     care of the technical details. Here is an example of a perfect
     documentation report:

     To: lilypond-devel@gnu.org
     From: helpful-user@example.net
     Subject: doc addition

     In LM 2.13 (printing lyrics), above the last line ("More options,
     like..."), please add:

     ----
     To add lyrics to a divided part, use blah blah blah.  For example,

     \score {
       \notes {blah <<blah>> }
       \lyrics {blah <<blah>> }
       blah blah blah
     }
     ----

     In addition, the second sentence of the first paragraph is
     confusing.  Please delete that sentence (it begins "Users
     often...") and replace it with this:
     ----
     To align lyrics with something, do this thing.
     ----

     Have a nice day,
     Helpful User


Larger contributions
--------------------

To replace large sections of the documentation, the guidelines are
stricter. We cannot remove parts of the current documentation unless we
are certain that the new version is an improvement.

  1. Ask on the lilypond-devel maillist if such a rewrite is necessary;
     somebody else might already be working on this issue!

  2. Split your work into small sections; this makes it much easier to
     compare the new and old documentation.

  3. Please prepare a formal git patch.


   Once you have followed these guidelines, please send a message to
lilypond-devel with your documentation submissions. Unfortunately there
is a strict “no top-posting” check on the mailist; to avoid this,
add:

   > I'm not top posting.

   (you must include the > ) to the top of your documentation addition.

   We may edit your suggestion for spelling, grammar, or style, and we
may not place the material exactly where you suggested, but if you give
us some material to work with, we can improve the manual much faster.
Thanks for your interest!

3.3 Texinfo introduction and usage policy
=========================================

3.3.1 Texinfo introduction
--------------------------

The language is called Texinfo; you can see its manual here:

   `http://www.gnu.org/software/texinfo/manual/texinfo/'

   However, you don't need to read those docs.  The most important
thing to notice is that text is text.  If you see a mistake in the
text, you can fix it.  If you want to change the order of something,
you can cut-and-paste that stuff into a new location.

          Note: Rule of thumb: follow the examples in the existing docs.
          You can learn most of what you need to know from this; if you
          want to do anything fancy, discuss it on `lilypond-devel'
          first.

3.3.2 Documentation files
-------------------------

All manuals live in `Documentation/'.

   In particular, there are four user manuals, their respective master
source files are `learning.tely' (LM, Learning Manual), `notation.tely'
(NR, Notation Reference), `music-glossary.tely' (MG, Music Glossary),
and `lilypond-program' (AU).  Each chapter is written in a separate
file, ending in `.itely' for files containing lilypond code, and
`.itexi' for files without lilypond code, located in a subdirectory
associated to the manual (`learning/' for `learning.tely', and so on);
list the subdirectory of each manual to determine the filename of the
specific chapter you wish to modify.

   Developer manuals live in `Documentation/' too.  Currently there is
only one: the Contributors' Guide `contrib-guide.texi' you are reading.

   Snippet files are part of documentation, and the Snippet List (SL)
lives in `Documentation/' just like the manuals.  For information about
how to modify the snippet files and SL, see *note LSR work::.

3.3.3 Sectioning commands
-------------------------

Most of the manual operates at the

     @node Foo
     @subsubsection Foo

level.  Sections are created with

     @node Foo
     @subsection Foo

   * Please leave two blank lines above a @node; this makes it easier
     to find sections in texinfo.

   * Sectioning commands (@node and @section) must not appear inside an
     @ignore.  Separate those commands with a space, ie @n ode.


   Nodes must be included inside a

     @menu
     * foo::
     * bar::
     @end menu

construct.  These are easily constructed with the emacs `M-x
texinfo-all-menus-update' construct, or by this command-line script:

     #!/bin/sh
     emacs $1 -batch -f texinfo-all-menus-update -f save-buffer

(save the above as something like `texinfo-menus.sh', make it
executable, then run `texinfo-menus.sh foo.itely')

3.3.4 LilyPond formatting
-------------------------

   * Use two spaces for indentation in lilypond examples.  (no tabs)

   * All text strings should be prefaced with #.  LilyPond does not
     strictly require this, but it is helpful to get users accustomed
     to this scheme construct.  ie `\set Staff.instrumentName =
     #"cello"'

   * All engravers should have double-quotes around them:

          \consists "Spans_arpeggio_engraver"

     Again, LilyPond does not strictly require this, but it is a useful
     standard to follow.

   * Examples should end with a complete bar if possible.

   * If possible, only write one bar per line.  The notes on each line
     should be an independent line - tweaks should occur on their own
     line if possible.  Bad:

          \override textscript #'padding = #3 c1^"hi"

     Good:

          \override textscript #'padding = #3
          c1^"hi"

   * Most LilyPond input should be produced with:

          @lilypond[verbatim,quote,relative=2]

     or

          @lilypond[verbatim,quote,relative=1]

     If you want to use \layout{} or define variables, use

          @lilypond[verbatim,quote]

     In rare cases, other options may be used (or omitted), but ask
     first.

   * Inspirational headwords are produced with

          @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
          {pitches-headword.ly}

   * LSR snippets are linked with

          @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
          {filename.ly}

     excepted in Templates, where `doctitle' may be omitted.

   * Avoid long stretches of input code.  Noone is going to read them
     in print.  Please create a smaller example.  (the smaller example
     does not need to be minimal, however)

   * Specify durations for at least the first note of every bar.

   * If possible, end with a complete bar.

   * Comments should go on their own line, and be placed before the
     line(s) to which they refer.

   * Add extra spaces around { } marks; ie

          not:          \chordmode {c e g}
          but instead:  \chordmode { c e g }

   * If you only have one bar per line, omit bar checks.  If you put
     more than one bar per line (not recommended), then include bar
     checks.

   * If you want to work on an example outside of the manual (for
     easier/faster processing), use this header:

          \paper {
            indent = 0\mm
            line-width = 160\mm - 2.0 * 0.4\in
            ragged-right = ##t
            force-assignment = #""
            line-width = #(- line-width (* mm  3.000000))
          }

          \layout {
          }

     You may not change any of these values.  If you are making an
     example demonstrating special \paper{} values, contact the
     Documentation Editor.


3.3.5 Text formatting
---------------------

   * Lines should be less than 72 characters long.  (I personally
     recommend writing with 66-char lines, but don't bother modifying
     existing material.)

   * Do not use tabs.

   * Do not use spaces at the beginning of a line (except in @example
     or @verbatim environments), and do not use more than a single
     space between words.  `makeinfo' copies the input lines verbatim
     without removing those spaces.

   * Use two spaces after a period.

   * In examples of syntax, use @var{musicexpr} for a music expression.

   * Don't use @rinternals{} in the main text.  If you're tempted to do
     so, you're probably getting too close to "talking through the
     code".  If you really want to refer to a context, use @code{} in
     the main text and @rinternals{} in the @seealso.

   * Variables or numbers which consist of a single character (probably
     followed by a punctuation mark) should be tied properly, either to
     the previous or the next word.  Example:

          The variable@tie{}@var{a} ...

   * To get consistent indentation in the DVI output it is better to
     avoid the @verbatim environment.  Use the @example environment
     instead if possible, but without extraneous indentation.  For
     example, this

          @example
            foo {
              bar
            }
          @end example

     should be replaced with

          @example
          foo {
            bar
          }
          @end example

     where `@example' starts the line (without leading spaces).

   * Do not compress the input vertically; this is, do not use

              Beginning of logical unit
              @example
              ...
              @end example
              continuation of logical unit

     but instead do

          Beginning of logical unit

          @example
          ...
          @end example

          @noindent
          continuation of logical unit

     This makes it easier to avoid forgetting the `@noindent'.  Only
     use @noindent if the material is discussing the same material; new
     material should simply begin without anything special on the line
     above it.

   * in @itemize use @item on a separate line like this:

          @itemize
          @item
          Foo

          @item
          Bar

     Do not use @itemize @bullet.

   * To get LilyPond version, use @version{} (this does not work inside
     LilyPond snippets).  If you write "@version{}" (enclosed with
     quotes), or generally if @version{} is not followed by a space,
     tere will be an ugly line break in PDF output unless you enclose
     it with

          @w{ ... }

            e.g.

          @w{"@version{}"}


3.3.6 Syntax survey
-------------------

   * @c - single line comments   "@c NOTE:" is a comment which should
     remain in the final   version.  (gp only command ;)

   * @ignore ... @end ignore - multi-line comment

   * @cindex - General index. Please add as many as you can.  Don't
     capitalize the first word.

   * @funindex - is for a \lilycommand.

   * @example ... @end ignore - example text that should be set as a
     blockquote.  Any {} must be escaped with @{ }@

   * @itemize @item A @item B ... @end itemize - for bulleted lists.
     Do not compress vertically like this.

   * @code{} - typeset in a tt-font. Use for actual lilypond code or
     property/context names.  If the name contains a space, wrap   the
     entire thing inside @w{@code{  }}.

   * @notation{} - refers to pieces of notation, e.g.
     "@notation{cres.}".  Also use to specific lyrics ("the
     @notation{A - men} is centered").  Only use once per subsection
     per term.

   * @q{} - Single quotes. Used for `vague' terms.

   * @qq{} - Double quotes.  Used for actual quotes ("he said") or for
     introducing special input modes.

   * @tie{} - Variables or numbers which consist of a single character
     (probably followed by a punctuation mark) should be tied
     properly, either to the previous or the next word.  Example:
     "The letter@tie{}@q{I} is skipped"

   * @var - Use for variables.

   * @warning{} - produces a "Note: " box. Use for important messages.

   * @bs - Generates a backslash inside @warning.      Any `\' used
     inside @warning (and @q or @qq) must be written as `@bs{}'
     (texinfo would also allow \\, but this breaks with PDF output).

   * @ref{} - normal references (type the exact node name inside the
     {}).

   * @ruser{} - link to the NR.

   * @rlearning{} - link to the LM.

   * @rglos{} - link to the MG.

   * @rprogram{} - link to the AU.

   * @rlsr{} - link to a Snippet section.

   * @rinternals{} - link to the IR.

   * @uref{} - link to an external url.


3.3.7 Other text concerns
-------------------------

   * References must occur at the end of a sentence, for more
     information see @ref{the texinfo manual}.  Ideally this should
     also be the final sentence of a paragraph, but this is not
     required.  Any link in a doc section must be duplicated in the
     @seealso section at the bottom.

   * Introducing examples must be done with

          . (ie finish the previous sentence/paragaph)
          : (ie `in this example:')
          , (ie `may add foo with the blah construct,')

     The old "sentence runs directly into the example" method is not
     allowed any more.

   * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.

   * Colon usage

       1. To introduce lists

       2. When beginning a quote: "So, he said,...".

          This usage is rarer.  Americans often just use a comma.

       3. When adding a defining example at the end of a sentence.


   * Non-ASCII characters which are in utf-8 should be directly used;
     this is, don't say `Ba@ss{}tuba' but `Baßtuba'.  This ensures
     that all such characters appear in all output formats.


3.4 Documentation policy
========================

3.4.1 Books
-----------

There are four parts to the documentation: the Learning Manual, the
Notation Reference, the Program Reference, and the Music Glossary.

   * Learning Manual:

     The LM is written in a tutorial style which introduces the most
     important concepts, structure and syntax of the elements of a
     LilyPond score in a carefully graded sequence of steps.
     Explanations of all musical concepts used in the Manual can be
     found in the Music Glossary, and readers are assumed to have no
     prior knowledge of LilyPond.  The objective is to take readers to
     a level where the Notation Reference can be understood and
     employed to both adapt the templates in the Appendix to their
     needs and to begin to construct their own scores.  Commonly used
     tweaks are introduced and explained.  Examples are provided
     throughout which, while being focussed on the topic being
     introduced, are long enough to seem real in order to retain the
     readers' interest.  Each example builds on the previous material,
     and comments are used liberally.  Every new aspect is thoroughly
     explained before it is used.

     Users are encouraged to read the complete Learning Manual from
     start-to-finish.

   * Notation Reference: a (hopefully complete) description of LilyPond
     input notation.  Some material from here may be duplicated in the
     Learning Manual (for teaching), but consider the NR to be the
     "definitive" description of each notation element, with the LM
     being an "extra".  The goal is _not_ to provide a step-by-step
     learning environment - do not avoid using notation that has not be
     introduced previously in the NR  (for example, use \break if
     appropriate).  This section is written in formal technical writing
     style.

     Avoid duplication.  Although users are not expected to read this
     manual from start to finish, they should be familiar with the
     material in the Learning Manual (particularly "Fundamental
     Concepts"), so do not repeat that material in each section of this
     book.  Also watch out for common constructs, like ^ - _ for
     directions - those are explained in NR 3.  In NR 1, you can write:
     DYNAMICS may be manually placed above or below the staff, see
     @ref{Controlling direction and placement}.

     Most tweaks should be added to LSR and not placed directly in the
     .itely file.  In some cases, tweaks may be placed in the main
     text, but ask about this first.

     Finally, you should assume that users know what the notation
     means; explaining musical concepts happens in the Music Glossary.

   * Application Usage: information about using the program lilypond
     with other programs (lilypond-book, operating systems, GUIs,
     convert-ly, etc).  This section is written in formal technical
     writing style.

     Users are not expected to read this manual from start to finish.

   * Music Glossary: information about the music notation itself.
     Explanations and translations about notation terms go here.

     Users are not expected to read this manual from start to finish.

   * Internals Reference: not really a documentation book, since it is
     automagically generated from the source, but this is its name.


3.4.2 Section organization
--------------------------

   * The order of headings inside documentation sections should be:

          main docs
          @predefined
          @endpredefined
          @snippets
          @seealso
          @knownissues

   * You _must_ include a @seealso.

        * The order of items inside the @seealso section is

               Music Glossary:
               @rglos{foo},
               @rglos{bar}.

               Learning Manual:
               @rlearning{baz},
               @rlearning{foozle}.

               Notation Reference:
               @ruser{faazle},
               @ruser{boo}.

               Application Usage:
               @rprogram{blah}.

               Installed Files:
               @file{path/to/dir/blahz}.

               Snippets: @rlsr{section}.

               Internals Reference:
               @rinternals{fazzle},
               @rinternals{booar}.

        * If there are multiple entries, separate them by commas but do
          not include an `and'.

        * Always end with a period.

        * Place each link on a new line as above; this makes it much
          easier to add or remove links.  In the output, they appear on
          a single line.

          ("Snippets" is REQUIRED; the others are optional)

        * Any new concepts or links which require an explanation should
          go as a full sentence(s) in the main text.

        * Don't insert an empty line between @seealso and the first
          entry!  Otherwise there is excessive vertical space in the
          PDF output.


   * To create links, use @ref{} if the link is within the same manual.

   * @predefined ... @endpredefined is for commands in ly/*-init.ly
     FIXME?

   * Do not include any real info in second-level sections (ie 1.1
     Pitches).  A first-level section may have introductory material,
     but other than that all material goes into third-level sections
     (ie 1.1.1 Writing Pitches).


3.4.3 Checking cross-references
-------------------------------

Cross-references between different manuals are heavily used in the
documentation, but they are not checked during compilation.  However,
if you compile the documentation, a script called check_texi_refs can
help you with checking and fixing these cross-references; for
information on usage, cd into a source tree where documentation has
been built, cd into Documentation and look for check-xrefs and
fix-xrefs targets in 'make help' output.  Note that you have to find
yourself the source files to fix cross-references in the generated
documentation such as the Internals Reference; e.g. you can grep scm/
and lily/.

3.4.4 General writing
---------------------

   * Do not forget to create @cindex entries for new sections of text.
     Enter commands with @funindex, i.e.

          @cindex pitches, writing in different octaves
          @funindex \relative

     do not bother with the @code{} (they are added automatically).
     These items are added to both the command index and the unified
     index.

     Both index commands should go in front of the actual material.

     @cindex entries should not be capitalized, ie

          @cindex time signature

     is preferred instead of "Time signature",   Only use capital
     letters for musical terms which demand them, like D.S. al Fine.

     For scheme functions, only include the final part, i.e.,

          @funindex modern-voice-cautionary
               and NOT
          @funindex #(set-accidental-style modern-voice-cautionary)

   * Preferred terms:

        * In general, use the American spellings.  The internal lilypond
          property names use this spelling.

        * List of specific terms:

               canceled
               simultaneous    NOT concurrent
               measure: the unit of music
               bar line: the symbol delimiting a measure   NOT barline
               note head   NOT notehead
               chord construct   NOT chord (when referring to <>)



3.4.5 Technical writing style
-----------------------------

These refer to the NR.  The LM uses a more gentle, colloquial style.

   * Do not refer to LilyPond in the text.  The reader knows what the
     manual is about.  If you do, capitalization is LilyPond.

   * If you explicitly refer to `lilypond' the program (or any other
     command to be executed), write `@command{lilypond}'.

   * Do not explicitly refer to the reader/user.  There is no one else
     besides the reader and the writer.

   * Avoid contractions (don't, won't, etc.).  Spell the words out
     completely.

   * Avoid abbreviations, except for commonly used abbreviations of
     foreign language terms such as etc. and i.e.

   * Avoid fluff ("Notice that," "as you can see," "Currently,").

   * The use of the word `illegal' is inappropriate in most cases.  Say
     `invalid' instead.


3.5 Tips for writing docs
=========================

In the NR, I highly recommend focusing on one subsection at a time.
For each subsection,

   * check the mundane formatting.  Are the headings (@predefined,
     @seealso, etc.) in the right order?

   * add any appropriate index entries.

   * check the links in the @seealso section - links to music glossary,
     internal references, and other NR sections are the main concern.
     Check for potential additions.

   * move LSR-worthy material into LSR.  Add the snippet, delete the
     material from the .itely file, and add a @lilypondfile command.

   * check the examples and descriptions.  Do they still work?  *Do
     not* assume that the existing text is accurate/complete; some of
     the manual is highly out of date.

   * is the material in the @knownissues  still accurate?

   * can the examples be improved (made more explanatory), or is there
     any missing info?  (feel free to ask specific questions on -user;
     a couple of people claimed to be interesting in being
     "consultants" who would help with such questions)


   In general, I favor short text explanations with good examples - "an
example is worth a thousand words".  When I worked on the docs, I spent
about half my time just working on those tiny lilypond examples.
Making easily-understandable examples is much harder than it looks.

Tweaks
......

In general, any \set or \override commands should go in the "select
snippets" section, which means that they should go in LSR and not the
.itely file.  For some cases, the command obviously belongs in the
"main text" (i.e. not inside @predefined or @seealso or whatever) -
instrument names are a good example of this.

     \set Staff.instrumentName = #"foo"

   On the other side of this,

     \override Score.Hairpin #'after-line-breaking = ##t

   clearly belongs in LSR.

   I'm quite willing to discuss specific cases if you think that a
tweaks needs to be in the main text.  But items that can go into LSR
are easier to maintain, so I'd like to move as much as possible into
there.

   It would be "nice" if you spent a lot of time crafting nice tweaks
for users... but my recommendation is *not* to do this.  There's a lot
of doc work to do without adding examples of tweaks.  Tweak examples
can easily be added by normal users by adding them to the LSR.

   One place where a documentation writer can profitably spend time
writing or upgrading tweaks is creating tweaks to deal with known
issues.  It would be ideal if every significant known issue had a
workaround to avoid the difficulty.



See also
........



   *note Adding and editing snippets::.

3.6 Updating doc with `convert-ly'
==================================

cd into `Documentation/' and run

     find . -name '*.itely' | xargs convert-ly -e

This also updates translated documentation.

3.7 Translating the documentation
=================================

The mailing list `translations@lilynet.net' is dedicated to LilyPond
web site and documentation translation; on this list, you will get
support from the Translations Meister and experimented translators, and
we regularly discuss translations issues common to all languagues.  All
people interested in LilyPond translations are invited to subscribe to
this list regardless of the amount of their contribution, by sending an
email to `translations-request@lilynet.net' with subject `subscribe'
and an empty message body.

3.7.1 Getting started with documentation translation
----------------------------------------------------

First, get the sources from the Git repository, see *note Documentation
translations source code::.

Translation requirements
........................

Working on LilyPond documentation translations requires the following
pieces of software, in order to make use of dedicated helper tools:

   * Python 2.4 or higher,

   * GNU Make,

   * Gettext,

   * Git.

   It is not required to build LilyPond and the documentation to
translate the documentation.  However, if you have enough time and
motivation and a suitable system, it can be very useful to build at
least the documentation so that you can check the output yourself and
more quickly; if you are interested, see *note Compiling from source::.

Which documentation can be translated
.....................................

FIXME: take into account the new web site integration in main sources.

   The makefiles and scripts infrastructure currently supports
translation of the following documentation:

   * documentation index (HTML);

   * the Learning Manual, the Notation Reference and Application Usage
     - Texinfo source, PDF and HTML output; Info output might be added
     if there is enough demand for it;

   * the Changes document.

   Support for translating the following pieces of documentation should
be added soon, by decreasing order of priority:

   * automatically generated documentation: markup commands, predefined
     music functions;

   * the Snippets List;

   * the Internals Reference.

Starting translation in a new language
......................................

At top of the source directory, do

     ./autogen.sh

or (if you want to install your self-compiled LilyPond locally)

     ./autogen.sh --prefix=$HOME

If you want to compile LilyPond - which is almost required to build the
documentation, but is not required to do translation only - fix all
dependencies and rerun `./configure' (with the same options as for
`autogen.sh').

   Then `cd' into `Documentation/' and run

     make ISOLANG=MY-LANGUAGE new-lang

where MY-LANGUAGE is the ISO 639 language code.

   Finally, add a language definition for your language in
`python/langdefs.py'.

   Before starting the real translation work, it is recommended to
commit changes you made so far to Git, so e.g. you are able to get back
to this state of the sources easily if needed; see *note Sharing your
changes::.

3.7.2 Documentation translation details
---------------------------------------

Please follow all the instructions with care to ensure quality work.

   All files should be encoded in UTF-8.

Files to be translated
......................

Translation of `Documentation/foo/bar' should be
`Documentation/LANG/foo/bar'.  Unmentioned files should not be
translated.

   Priorities:
   * 1. delivery,

   * 2. 3. 4. 5. later,

   * 6. optional.

   Files marked with priority 3, 4 or 5 may be submitted individually.
Word counts (excluding LilyPond snippets) are given for each file.

   FIXME: take into account the new web site integration in main
sources.

     -1- Tutorial
     132   learning.tely
     2678  learning/tutorial.itely
     4138  learning/common-notation.itely
     23    dedication.itely
     1059  macros.itexi
     161   translations.template.html.in
     1670  po/lilypond-doc.pot (translate to po/MY_LANGUAGE.po)
     ---   lilypond-texi2html.init (section TRANSLATIONS)
     9861  total

     -2- Fundamental Concepts and beginning of Application Usage
     11135 learning/fundamental.itely -- Fundamental concepts
     411   learning/preface.itely
     145   usage.tely
     3531  usage/running.itely
     1189  usage/updating.itely
     16411 total

     -3- Rest of Learning manual and Suggestions on writing LilyPond files
     15578 learning/tweaks.itely -- Tweaking output
     201   learning/templates.itely -- Templates
     2694  usage/suggestions.itely -- Suggestions on writing LilyPond files
     18473 total

     -4- Notation reference
     467   notation.tely
     91    notation/notation.itely -- Musical notation
     3155  notation/pitches.itely
     4757  notation/rhythms.itely
     1392  notation/expressive.itely
     555   notation/repeats.itely
     1456  notation/simultaneous.itely
     1689  notation/staff.itely
     919   notation/editorial.itely
     2412  notation/text.itely
     81    notation/specialist.itely -- Specialist notation
     2725  notation/vocal.itely
     1516  notation/chords.itely
     702   notation/piano.itely
     810   notation/percussion.itely
     826   notation/guitar.itely
     66    notation/strings.itely
     242   notation/bagpipes.itely
     4487  notation/ancient.itely
     6264  notation/input.itely -- Input syntax
     2164  notation/non-music.itely -- Non-musical notation
     8433  notation/spacing.itely -- Spacing issues
     11933 notation/changing-defaults.itely -- Changing defaults
     5187  notation/programming-interface.itely -- Interfaces for programmers
     2002  notation/notation-appendices.itely -- Notation manual tables
     252   notation/cheatsheet.itely -- Cheat sheet
     64583 total

     -5- Rest of Application Usage
     3511  usage/lilypond-book.itely -- LilyPond-book
     1122  usage/converters.itely -- Converting from other formats
     4633  total

     -6- Appendices whose translation is optional
     310   notation/literature.itely
     1222  learning/scheme-tutorial.itely (should be revised first)
     1532  total

Translating the Learning Manual and other Texinfo documentation
...............................................................

Note: node names and section titles are now translated directly in
Texinfo source files. In case you have files in your working tree that
have not been converted, please pull first, then run

     make -C Documentation/po doc
     export LYDOC_LOCALEDIR=Documentation/po/out-www
     export PYTHONPATH=python:python/auxiliar
     scripts/auxiliar/tely-gettext.py MANUAL.TELY

This will also update files included in `MANUAL.tely', and of course
this script can be used for individual `FOO.itely' files too.

   Every piece of text should be translated in the source file, except
Texinfo comments, text in `@lilypond' blocks and a few cases mentioned
below.

   Node names are translated, but the original node name in English
should be kept as the argument of `@translationof' put after the section
title; that is, every piece in the original file like

     @node Foo bar
     @SECTION_COMMAND Bar baz

should be translated as

     @node TRANSLATION OF FOO BAR
     @SECTION_COMMAND TRANSLATION OF BAR BAZ
     @translationof Foo bar

   The argument of `@rglos' commands and the first argument of
`@rglosnamed' commands must not be translated, as it is the node name
of an entry in Music Glossary.

   Every time you translate a node name in a cross-reference, i.e. the
argument of commands `@ref, @rprogram, @rlearning, @rlsr, @ruser' or
the first argument of their `*named' variants, you should make sure the
target node is defined in the correct source file; if you do not intend
to translate the target node right now, you should at least write the
node definition (that is, the `@node @SECTION_COMMMAND @translationof'
trio mentioned above) in the expected source file and define all its
parent nodes; for each node you have defined this way but have not
translated, insert a line that contains `@untranslated' and append ` @c
external' to the line that contains `@translationof'. That is, you
should end up for each untranslated node with something like

     @node TRANSLATION OF FOO BAR
     @SECTION_COMMAND TRANSLATION OF BAR BAZ
     @translationof Foo bar @c external

     @untranslated

Finally, press in Emacs <C-c C-u C-a> to update or generate menus. This
process should be made easier in the future, when the helper script
`texi-langutils.py' and the makefile target are updated.

   Some pieces of text manipulated by build scripts that appear in the
output are translated in a `.po' file - just like LilyPond output
messages - in `Documentation/po'.  The Gettext domain is named
`lilypond-doc', and unlike `lilypond' domain it is not managed through
the Free Translation Project.

   Take care of using typographic rules for your language, especially in
`macros.itexi'.

   Please keep verbatim copies of music snippets (in `@lilypond'
blocs).  However, some music snippets containing text that shows in the
rendered music, and sometimes translating this text really helps the
user to understand the documentation; in this case, and only in this
case, you may as an exception translate text in the music snippet, and
then you must add a line immediately before the `@lilypond' block,
starting with

     @c KEEP LY

Otherwise the music snippet would be reset to the same content as the
English version at next `make snippet-update' run - see *note Updating
documentation translation::.

   When you encounter

     @lilypondfile[<number of fragment options>,texidoc]{FILENAME.LY}

in the source, open `Documentation/snippets/FILENAME.ly', translate the
`texidoc' header field it contains, enclose it with `texidocMY-LANGUAGE
= "' and `"', and write it into
`Documentation/MY-LANGUAGE/texidocs/FILENAME.texidoc'.  Additionnally,
you may translate the snippet's title in `doctitle' header field, in
case `doctitle' is a fragment option used in `@lilypondfile'; you can
do this exactly the same way as `texidoc'.  For instance,
`Documentation/MY-LANGUAGE/texidocs/FILENAME.texidoc' may contain

     doctitlees = "Spanish title baz"
     texidoces = "
     Spanish translation blah
     "

Then, you should get these translated strings into compiled snippets in
`Documentation/snippets', see `General guidelines' in *note Adding and
editing snippets::.

   `@example' blocs need not be verbatim copies, e.g. variable names,
file names and comments should be translated.

   Finally, please carefully apply every rule exposed in *note Texinfo
introduction and usage policy::, and *note Documentation policy::.  If
one of these rules conflicts with a rule specific to your language,
please ask the Translation meister on <translations@lilynet.net> list
and/or the Documentation Editors on <lilypond-devel@gnu.org> list.

Translating the Notation Reference and Application Usage
........................................................

Copy `notation.tely' (or `application.tely', respectively) into
`MY-LANGUAGE', then translate this file and run `skeleton-update' - see
*note Updating documentation translation::.  Your are now ready to
translate the Notation Reference (Application Usage, respectively)
exactly like the Learning Manual.

Translating the Documentation index `index.html.in'
...................................................

Unlike almost all HTML pages in this documentation, links in this page
are not tweaked by `postprocess_html.py', so links should be manually
edited to link to existing translations.

3.7.3 Documentation translation maintenance
-------------------------------------------

Several tools have been developed to make translations maintenance
easier.  These helper scripts make use of the power of Git, the version
control system used for LilyPond development.

Check state of translation
..........................

First pull from Git, then cd into `Documentation/' (or at top of the
source tree, replace `make' with `make -C Documentation') and run

     make ISOLANG=MY_LANGUAGE check-translation

This presents a diff of the original files since the most recent
revision of the translation.  To check a single file, cd into
`Documentation/' and run

     make CHECKED_FILES=MY_LANGUAGE/MANUAL/FOO.itely check-translation

In case this file has been renamed since you last updated the
translation, you should specify both old and new file names, e.g.
`CHECKED_FILES=MY_LANGUAGE/{MANUAL,user}/FOO.itely'.

   To see only which files need to be updated, do

     make ISOLANG=MY_LANGUAGE check-translation | grep 'diff --git'

   To avoid printing terminal colors control characters, which is often
desirable when you redirect output to a file, run

     make ISOLANG=MY_LANGUAGE NO_COLOR=1 check-translation

   Global state of the translation is recorded in
`Documentation/translations.html.in', which is used to generate
Translations status page.  To update that page, do from `Documentation/'

     make translation-status

   This will also leave `out/translations-status.txt', which contains
up-to-dateness percentages for each translated file, and update word
counts of documentation files in this Guide.



See also
........



   *note Maintaining without updating translations::.

Updating documentation translation
..................................

Instead of running `check-translation', you may want to run
`update-translation', which will run your favorite text editor to
update files.  First, make sure environment variable `EDITOR' is set to
a text editor command, then run from `Documentation/'

     make ISOLANG=MY_LANGUAGE update-translation

or to update a single file

     make CHECKED_FILES=MY_LANGUAGE/MANUAL/FOO.ITELY update-translation

   For each file to be udpated, `update-translation' will open your
text editor with this file and a diff of the file in English; if the
diff cannot be generated or is bigger than the file in English itself,
the full file in English will be opened instead.

   Texinfo skeleton files, i.e. `.itely' files not yet translated,
containing only the Texinfo structure can be updated automatically:
whenever `make check-translation' shows that such files should be
updated, run from `Documentation/'

     make ISOLANG=MY_LANGUAGE skeleton-update

   `.po' message catalogs in `Documentation/po/' may be updated by
issuing from `Documentation/' or `Documentation/po/'

     make po-update

          Note: if you run po-update and somebody else does the same and
          pushes before you push or send a patch to be applied, there
          will be a conflict when you pull.  Therefore, it is better
          that only the Translation meister runs this command.

   Updating music snippets can quickly become cumbersome, as most
snippets should be identical in all languages.  Fortunately, there is a
script that can do this odd job for you (run from `Documentation/'):

     make ISOLANG=MY_LANGUAGE snippet-update

   This script overwrites music snippets in
`MY_LANGUAGE/FOO/EVERY.ITELY' with music snippets from
`FOO/EVERY.ITELY'.  It ignores skeleton files, and keeps intact music
snippets preceded with a line starting with `@c KEEP LY'; it reports an
error for each `.itely' that has not the same music snippet count in
both languages.  Always use this script with a lot of care, i.e. run it
on a clean Git working tree, and check the changes it made with `git
diff' before committing; if you don't do so, some `@lilypond' snippets
might be broken or make no sense in their context.

   When you have updated texidocs in
`Documentation/MY-LANGUAGE/texidocs', you can get these changes into
compiled snippets in `Documentation/snippets', see `General guidelines'
in *note Adding and editing snippets::.

   Finally, a command runs the three update processes above for all
enabled languages (from `Documentation/'):

     make all-translations-update

   Use this command with caution, and keep in mind it will not be really
useful until translations are stabilized after the end of GDP and GOP.



See also
........



   *note Maintaining without updating translations::, *note Adding and
editing snippets::.

3.7.4 Translations management policies
--------------------------------------

These policies show the general intent of how the translations should
be managed, they aim at helping translators, developers and
coordinators work efficiently.

Maintaining without updating translations
.........................................

Keeping translations up to date under heavy changes in the documentation
in English may be almost impossible, especially as during the former
Grand Documentation Project (GDP) or the Grand Organization Project
(GOP) when a lot of contributors brings changes.  In addition,
translators may be -- and that is a very good thing -- involved in
these projects too.

   it is possible -- and even recommended -- to perform some maintenance
that keeps translated documentation usable and eases future translation
updating.  The rationale below the tasks list motivates this plan.

   The following tasks are listed in decreasing priority order.

  1. Update macros.itexi.  For each obsolete macro definition, if it is
     possible to update macro usage in documentation with an automatic
     text or regexp substitution, do it and delete the macro definition
     from macros.itexi; otherwise, mark this macro definition as
     obsolete with a comment, and keep it in macros.itexi until the
     documentation translation has been updated and no longer uses this
     macro.

  2. Update `*.tely' files completely with `make check-translation' -
     you may want to redirect ouptput to a file because of overwhelming
     output, or call check-translation.py on individual files, see
     *note Check state of translation::.

  3. In `.itelys', match sections and .itely file names with those from
     English docs, which possibly involves moving nodes contents in
     block between files, without updating contents itself.  In other
     words, the game is catching where has gone each section.  In
     Learning manual, and in Notation Reference sections which have
     been revised in GDP, there may be completely new sections: in this
     case, copy `@node' and `@section'-command from English docs, and
     add the marker for untranslated status `@untranslated' on a single
     line.  Note that it is not possible to exactly match subsections
     or subsubsections of documentation in English, when contents has
     been deeply revised; in this case, keep obsolete (sub)subsections
     in the translation, marking them with a line `@c obsolete' just
     before the node.

     Emacs with Texinfo mode makes this step easier:

        * without Emacs AucTeX installed, <C-c C-s> shows structure of
          current Texinfo file in a new buffer `*Occur*'; to show
          structure of two files simultaneously, first split Emacs
          window in 4 tiles (with <C-x 1> and <C-x 2>), press <C-c C-s>
          to show structure of one file (e.g. the translated file),
          copy `*Occur*' contents into `*Scratch*', then press <C-c
          C-s> for the other file.

          If you happen to have installed AucTeX, you can either call
          the macro by doing <M-x texinfo-show-structure> or create a
          key binding in your `~/.emacs', by adding the four following
          lines:

               (add-hook 'Texinfo-mode-hook
                         '(lambda ()
                            (define-key Texinfo-mode-map "\C-cs"
                             'texinfo-show-structure)))

          and then obtain the structure in the `*Occur*' buffer with
          <C-c s>.

        * Do not bother updating `@menu's when all menu entries are in
          the same file, just do <C-c C-u C-a> ("update all menus")
          when you have updated all the rest of the file.

        * Moving to next or previous node using incremental search:
          press <C-s> and type `node' (or <C-s @node> if the text
          contains the word `node') then press <C-s> to move to next
          node or <C-r> to move to previous node.  Similar operation
          can be used to move to the next/previous section.  Note that
          every cursor move exits incremental search, and hitting <C-s>
          twice starts incremental search with the text entered in
          previous incremental search.

        * Moving a whole node (or even a sequence of nodes): jump to
          beginning of the node (quit incremental search by pressing an
          arrow), press <C-SPACE>, press <C-s node> and repeat <C-s>
          until you have selected enough text, cut it with <C-w> or
          <C-x>, jump to the right place (moving between nodes with the
          previous hint is often useful) and paste with <C-y> or <C-v>.

  4. Update sections finished in the English documentation; check
     sections status at
     `http://lilypondwiki.tuxfamily.org/index.php?title=Documentation_coordination'.

  5. Update documentation PO.  It is recommended not to update strings
     which come from documentation that is currently deeply revised in
     English, to avoid doing the work more than once.

  6. Fix broken cross-references by running (from `Documentation/')

          make ISOLANG=YOUR-LANGUAGE fix-xrefs

     This step requires a sucessful documentation build (with `make
     doc').  Some cross-references are broken because they point to a
     node that exists in the documentation in English, which has not
     been added to the translation; in this case, do not fix the
     cross-reference but keep it "broken", so that the resulting HTML
     link will point to an existing page of documentation in English.

Rationale
.........

You may wonder if it would not be better to leave translations as-is
until you can really start updating translations.  There are several
reasons to do these maintenance tasks right now.

   * This will have to be done sooner or later anyway, before updating
     translation of documentation contents, and this can already be done
     without needing to be redone later, as sections of documentation in
     English are mostly revised once.  However, note that not all
     documentation sectioning has been revised in one go, so all this
     maintenance plan has to be repeated whenever a big reorganization
     is made.

   * This just makes translated documentation take advantage of the new
     organization, which is better than the old one.

   * Moving and renaming sections to match sectioning of documentation
     in English simplify future updating work: it allows updating the
     translation by side-by-side comparison, without bothering whether
     cross-reference names already exist in the translation.

   * Each maintenance task except `Updating PO files' can be done by
     the same person for all languages, which saves overall time spent
     by translators to achieve this task: the node names and section
     titles are in English, so you can do.  It is important to take
     advantage of this now, as it will be more complicated (but still
     possible) to do step 3 in all languages when documentation is
     compiled with `texi2html' and node names are directly translated
     in source files.

Managing documentation translation with Git
...........................................

This policy explains how to manage Git branches and commit translations
to Git.

   * Translation changes matching master branch are preferably made on
     `lilypond/translation' branch; they may be pushed directly to
     `master' only if they do not break compilation of LilyPond and its
     documentation, and in this case they should be pushed to
     `lilypond/translation' too.  Similarly, changes matching
     `stable/X.Y' are preferably made on `lilypond/X.Ytranslation'.

   * `lilypond/translation' Git branch may be merged into master only
     if LilyPond (`make all') and documentation (`make doc') compile
     succesfully.

   * `master' Git branch may be merged into `lilypond/translation'
     whenever `make' and `make doc' are succesful (in order to ease
     documentation compilation by translators), or when significant
     changes had been made in documentation in English in master branch.

   * General maintenance may be done by anybody who knows what he does
     in documentation in all languages, without informing translators
     first.  General maintenance include simple text substitutions
     (e.g. automated by sed), compilation fixes, updating Texinfo or
     lilypond-book commands, updating macros, updating ly code, fixing
     cross-references, and operations described in *note Maintaining
     without updating translations::.

3.7.5 Technical background
--------------------------

A number of Python scripts handle a part of the documentation
translation process.  All scripts used to maintain the translations are
located in `scripts/auxiliar/'.

   * `check_translation.py'  - show diff to update a translation,

   * `texi-langutils.py'  - quickly and dirtily parse Texinfo files to
     make message catalogs and Texinfo skeleton files,

   * `texi-skeleton-update.py' - update Texinfo skeleton files,

   * `update-snippets.py' - synchronize ly snippets with those from
     English docs,

   * `translations-status.py' - update translations status pages and
     word counts in the file you are reading,

   * `tely-gettext.py' - gettext node names, section titles and
     references in the sources; WARNING only use this script once for
     each file, when support for "makeinfo -html" has been dropped.

   Other scripts are used in the build process, in `scripts/build/':

   * `mass-link.py' - link or symlink files between English
     documentation and documentation in other languages.

   Python modules used by scripts in `scripts/auxiliar/' or
`scripts/build/' (but not by installed Python scripts) are located in
`python/auxiliar/':
   * `manuals_definitions.py' - define manual names and name of
     cross-reference Texinfo macros,

   * `buildlib.py' - common functions (read piped output of a shell
     command, use Git),

   * `postprocess_html.py' (module imported by `www_post.py') - add
     footer and tweak links in HTML pages.

   And finally
   * `python/langdefs.py'  - language definitions module

4 Website work
**************

4.1 Introduction to website work
================================

Short answer: don't do it yet.  We're completely revamping the website.

4.2 Translating the website
===========================

5 LSR work
**********

5.1 Introduction to LSR
=======================

The LilyPond Snippet Repository (LSR) (http://lsr.dsi.unimi.it/) is a
collection of lilypond examples.  A subset of these examples are
automatically imported into the documentation, making it easy for users
to contribute to the docs without learning Git and Texinfo.

5.2 Adding and editing snippets
===============================

General guidelines
------------------

When you create (or find!) a nice snippet, if it supported by LilyPond
version running on LSR, please add it to LSR.  Go to LSR
(http://lsr.dsi.unimi.it/) and log in - if you haven't already, create
an account.  Follow the instructions on the website.  These
instructions also explain how to modify existing snippets.

   If you think the snippet is particularly informative and you think it
should be included in the documentation, tag it with "docs" and one or
more other categories, or ask somebody who has editing permissions to
do it on the development list.

   Please make sure that the lilypond code follows the guidelines in
*note LilyPond formatting::.

   If a new snippet created for documentation purposes compiles with
LilyPond version currently on LSR, it should be added to LSR, and a
reference to the snippet should be added to the documentation.

   If the new snippet uses new features that are not available in the
current LSR version, the snippet should be added to
`Documentation/snippets/new' and a reference should be added to the
manual.

   Snippets created or updated in `Documentation/snippets/new' should
be copied to `Documentation/snippets' by invoking at top of the source
tree

     scripts/auxiliar/makelsr.py

This also copies translated texidoc fields and snippet titles into
snippets in `Documentation/snippets'.

   Be sure that `make doc' runs successfully before submitting a patch,
to prevent breaking compilation.

Formatting snippets in `Documentation/snippets/new'
---------------------------------------------------

When adding a file to this directory, please start the file with

     \version "2.x.y"
     \header {
       lsrtags = "rhythms,expressive-marks"  % use existing LSR tags other than
     %   'docs'; see makelsr.py for the list of tags used to sort snippets.
       texidoc = "This code demonstrates ..."  % this will be formated by Texinfo
       doctitle = "Snippet title"  % please put this at the end so that
         the '% begin verbatim' mark is added correctly by makelsr.py.
     }

   and name the file `snippet-title.ly'.

5.3 Approving snippets
======================

The main task of LSR editors is approving snippets.  To find a list of
unapproved snippets, log into LSR (http://lsr.dsi.unimi.it/) and select
"No" from the dropdown menu to the right of the word "Approved" at the
bottom of the interface, then click "Enable filter".

   Check each snippet:

  1. Does the snippet make sense and does what the author claims that
     it does?  If you think the snippet is particularly helpful, add
     the "docs" tag and at least one other tag.

  2. If the snippet is tagged with "docs", check to see if it matches
     our guidelines for *note LilyPond formatting::.

  3. If the snippet uses scheme, check that everything looks good and
     there are no security risks.

               Note: Somebody could sneak a `#'(system "rm -rf /")'
               command into our source tree if you do not do this!
               Take this step *VERY SERIOUSLY*.


5.4 LSR to Git
==============

  1. Make sure that `convert-ly' and `lilypond' commands in current
     PATH are in a bleeding edge version - latest release from master
     branch, or even better a fresh snapshot from Git master branch.

  2. From the top source directory, run:

          wget http://lsr.dsi.unimi.it/download/lsr-snippets-docs-YYYY-MM-DD.tar.gz
          tar -xzf lsr-snippets-docs-YYYY-MM-DD.tar.gz
          scripts/auxiliar/makelsr.py lsr-snippets-docs-YYYY-MM-DD

     where YYYY-MM-DD is the current date, e.g. 2009-02-28.

  3. Follow the instructions printed on the console to manually check
     for unsafe files.

               Note: Somebody could sneak a `#'(system "rm -rf /")'
               command into our source tree if you do not do this!
               Take this step *VERY SERIOUSLY*.

  4. Do a git add / commit / push.


   Note that whenever there is one snippet from
`Documentation/snippets/new' and the other from LSR with the same file
name, the one from `Documentation/snippets/new' will be copied by
`makelsr.py'.

5.5 Fixing snippets in LilyPond sources
=======================================

In case some snippet from `Documentation/snippets' causes the
documentation compilation to fail, the following steps should be
followed to fix it reliably.

  1. Look up the snippet filename `FOO.ly' in the error output or log,
     then fix the file `Documentation/snippets/FOO.ly' to make the
     documentation build succesfully.

  2. Determine where it comes from by looking at its first line, e.g.
     run

          head -1 Documentation/snippets/FOO.ly

  3. *In case the snippet comes from LSR*, apply the fix to the snippet
     in LSR and send a notification email to a LSR editor with CC to
     the development list - see *note Adding and editing snippets::.
     The failure may sometimes not be caused by the snippet in LSR but
     by the syntax conversion made by `convert-ly'; in this case, try
     to fix `convert-ly' or report the problem on the development list,
     then run `makelsr.py' again, see *note LSR to Git::.  In some
     cases, when some features has been introduced or vastly changed so
     it requires (or takes significant advantage of) important changes
     in the snippet, it is simpler and recommended to write a new
     version of the snippet in `Documentation/snippets/new', then run
     `makelsr.py'.

  4. *In case the snippet comes from* `Documentation/snippets/new',
     apply in `Documentation/snippets/new/FOO.ly' the same fix you did
     in `Documentation/snippets/FOO.ly'.  In case the build failure was
     caused by a translation string, you may have to fix
     `input/texidocs/FOO.texidoc' instead.

  5. In any case, commit all changes to Git.


5.6 Updating LSR to a new version
=================================

To update LSR, perform the following steps:

  1. Download the latest snippet tarball, extract it, and run
     `convert-ly' on all files using the command-line option
     `--to=VERSION' to ensure snippets are updated to the correct
     stable version.

  2. Copy relevant snippets (i.e., snippets whose version is equal to
     or less than the new version of LilyPond) from
     `Documentation/snippets/new/' into the tarball.

     You must not rename any files during this, or the next, stage.

  3. Verify that all files compile with the new version of LilyPond,
     ideally without any warnings or errors.  To ease the process, you
     may use the shell script that appears after this list.

     Due to the workload involved, we _do not_ require that you verify
     that all snippets produce the expected output.  If you happen to
     notice any such snippets and can fix them, great; but as long as
     all snippets compile, don't delay this step due to some weird
     output.  If a snippet is broken, the hordes of willing web-2.0
     volunteers will fix it.  It's not our problem.

  4. Create a tarball and send it back to Sebastiano.

  5. When LSR has been updated, download another snippet tarball,
     verify that the relevant snippets from
     `Documentation/snippets/new/' were included, then delete those
     snippets from `Documentation/snippets/new/'.


   Here is a shell script to run all `.ly' files in a directory and
redirect terminal output to text files, which are then searched for the
word "failed" to see which snippets do not compile.

     #!/bin/bash

     for LILYFILE in *.ly
     do
       STEM=$(basename "$LILYFILE" .ly)
       echo "running $LILYFILE..."
       lilypond --format=png -ddelete-intermediate-files "$LILYFILE" >& "$STEM".txt
     done

     grep failed *.txt

6 Issues
********

6.1 Introduction to issues
==========================

First, "issue" isn't just a politically-correct term for "bug".  We use
the same tracker for feature requests and code TODOs, so the term "bug"
wouldn't be accurate.

   Second, the classification of what counts as a bug vs. feature
request, and the priorities assigned to bugs, are a matter of concern
*for developers only*.  If you are curious about the classification,
read on, but don't complain that your particular issue is higher
priority or counts as a bug rather than a feature request.

6.2 Issue classification
========================

Status values:

   * New: the item was added by a non-member.  Should be reviewed by
     the Bug Meister.

   * Accepted: the Bug Meister added it, or reviewed the item.

   * Started: a programmer is working on a bugfix.  (used infrequently,
     but should be used more often)


   Closed status values:

   * Invalid: issue should not have been added in the current state.

   * Duplicate: issue already exists in the tracker.

   * Fixed: programmer claims to have fixed the bug.  The Bug Meister
     should check the input code in an official binary release.

   * Verified: Bug Meister has confirmed that the issue is closed.


   Type labels:

   * Type-Defect: a problem that requires no (or very little) new code
     to fix.

   * Type-Enhancement: a problem (or new feature) that requries a
     significant amount of new code.

   * Type-Collision: overlapping notation.  (this label takes
     precedence over -Defect and -Enhancement)

   * Type-Task: not used, I think.  TODO: start using it or delete it.

   * Type-Other: anything else.  TODO: start using it or delete it.


   Priority labels:

   * Priority-High: lilypond segfaults.

   * Priority-Regression: it used to work.

   * Priority-Medium: normal priority; this is the highest priority a
     non-crashing, non-regression bug report can receive.  (regardless
     of the perceived importance)

   * Priority-Low: less important than normal.

   * Priority-Postponed: no fix planned.  Generally used for things
     like Ancient notation, which nobody wants to touch.


   Opsys lables: pretty self-explanatory.

   Other lables:

   * Security: not used.  TODO: delete, unless anybody is serious about
     this.

   * Performance: not used.  TODO: delete.

   * Usability: not used.  TODO: delete.

   * Maintainability: hinders developent of LilyPond.  For example,
     improvements to the build system, or "helper" python scripts.

   * Bounty: somebody is willing to pay for the fix.

   * Engraving-nitpick: output is not beautiful, but not strictly
     speaking "wrong".  For example, a slur shape which does not
     collide with any notation, but looks ugly.

   * Warning-nitpick: graphical output is fine, but lilypond prints a
     false/misleading warning message.


6.3 Adding issues to the tracker
================================

FIXME: prettify.

   only done by Bug Meister, unless you're really certain you know what
you're doing.

7 Regression tests
******************

7.1 Introduction to regression tests
====================================

7.2 Current regtest output
==========================

7.3 Comparison regtest output
=============================

7.4 MusicXML tests
==================

8 Programming work
******************

8.1 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 master's thesis
(http://lilypond.org/web/images/thesis-erik-sandberg.pdf).

   The first stage of LilyPond processing is _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 _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 _translation_.  During
translation, music events are prepared for graphical or midi output.
The translation step is accomplished by translators or engravers (the
distinction is unclear).

   Translators are defined in C++ files named *-engraver.cc.  In
*-engraver.cc, a C++ class of Engraver type is created.  The Engraver
is also declared as a translator.  Much of the work of translating is
handled by Scheme functions, which is one of the keys to LilyPond's
exceptional flexibility.

8.2 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.

8.2.1 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 GUILE Reference Manual
(http://www.gnu.org/software/guile/manual/html_node/index.html).

8.2.2 GNU Bison
---------------

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

8.2.3 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
the GNU website (http://www.gnu.org/software/make/manual/).

8.2.4 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 GUILE Reference Manual
(http://www.gnu.org/software/guile/manual/html_node/index.html) is
available online.

   Structure and Interpretation of Computer Programs
(http://mitpress.mit.edu/sicp/full-text/book/book.html), 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 *note Scheme tutorial:
(lilypond-learning)Scheme tutorial.

8.2.5 MetaFont
--------------

MetaFont is used to create the music fonts used by LilyPond.  A MetaFont
tutorial is available at the METAFONT tutorial page
(http://metafont.tutorial.free.fr/).

8.2.6 PostScript
----------------

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

8.2.7 Python
------------

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

   Python documentation is available at python.org
(http://www.python.org/doc/).

8.3 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.

8.3.1 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.

8.3.2 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
`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 *note
Texinfo introduction and usage policy::.

8.4 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.

8.4.1 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.

8.4.2 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

     grep -i functionName subdirectory/*

   This command will search all the contents of the directory
subdirectory/ and display every line in any of the files that contains
functionName.  The `-i' option makes `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.

8.4.3 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:

     git grep functionName

   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 `less', so the results are displayed one page at a
time.

8.4.4 Searching on the git repository at Savannah
-------------------------------------------------

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

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

   * In the pulldown box that says commit, select grep.

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


   This will initiate a search of the remote git repository.

8.5 Code style
==============

          Note: this is pending some confirmation on -devel.  July 2009
          -gp

Command-line script to format stuff with emacs:

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

   (that's all on one line)

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

8.5.1 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.

8.5.2 Languages
---------------

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

8.5.3 Filenames
---------------

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

   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))

   The class Class_name is coded in `class-name.*'

8.5.4 Indentation
-----------------

Standard GNU coding style is used. In emacs:

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

   If you like using font-lock, you can also add this to your `.emacs':

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

8.5.5 Classes and Types
-----------------------

This_is_a_class

8.5.6 Members
-------------

Member variable names end with an underscore:

Type Class::member_

8.5.7 Macros
------------

Macro names should be written in uppercase completely.

8.5.8 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.

8.5.9 Naming
------------

8.5.10 Messages
---------------

Messages need to follow Localization.

8.5.11 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.

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

   * Don't localize/gettextify:

        * `programming_error ()'s

        * `programming_warning ()'s

        * debug strings

        * output strings (PostScript, TeX, etc.)


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

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

     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'.

          char const* messages[] = {
            _i ("enable debugging output"),
            _i ("ignore lilypond version"),
            0
          };

          void
          foo (int i)
          {
            puts (gettext (messages i));
          }

     See also `flower/getopt-long.cc' and `lily/main.cc'.

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

          message ("Calculating line breaks..." + " ");

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

          foo.ly: 12: not a duration: 3

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

          Processing foo.ly...
          `foo': not declared.
          Not declaring: `foo'.

   * 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:

          _f ("cannot open file: `%s'", name_str)
          _f ("cannot find character number: %d", i)

   * 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

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

     have

          _f ("stem at %s does not fit in beam", moment.str ())

   * Split up multi-sentence messages, whenever possible. Instead of

          warning (_f ("out of tune!  Can't find: `%s'", "Key_engraver"));
          warning (_f ("cannot find font `%s', loading default", font_name));

     rather say:

          warning (_ ("out of tune:"));
          warning (_f ("cannot find: `%s', "Key_engraver"));
          warning (_f ("cannot find font: `%s', font_name));
          warning (_f ("Loading default font"));

   * 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.

          _f ("Non-matching braces in text `%s', adding braces", text)
          _ ("Debug output disabled.  Compiled with NPRINT.")
          _f ("Huh?  Not a Request: `%s'.  Ignoring.", request)

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

   * 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.

          en: cannot open: `foo.ly'
          +   nl: kan `foo.ly' niet openen (1)
          kan niet openen: `foo.ly'*   (2)
          niet te openen: `foo.ly'*    (3)

     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).

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


8.6 Debugging LilyPond
======================

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

8.6.1 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.

8.6.2 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.

     ./configure  --disable-optimising

     make

   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 MAKE INSTALL if you want to use a debugger with
LilyPond.  MAKE INSTALL will strip the debugging information from the
LilyPond binary.

   To set breakpoints in Scheme functions, put

     \include "guile-debugger.ly"

   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
`break!' procedure:

     guile> (break! my-scheme-procedure)

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

     guile> (quit)

   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:

     debug> help

8.6.3 Typical gdb usage
-----------------------

8.6.4 Typical .gdbinit files
----------------------------

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

   The .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).

     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

8.6.5 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:

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

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

     #(top-repl)

   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:

     guile> (set-current-module lilypond-module)

   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:

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

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

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

   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:

     guile> (quit)

   The compilation of the .ly file will then continue.

8.7 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.

8.7.1 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.

8.7.2 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.

8.7.3 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.

8.7.4 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:

     find Documentation/ -name '*.itely' | xargs convert-ly -e --from "X.Y.Z"

where X.Y.Z is the version number of the last released development
version.

   Next, for the snippets, do:

     find Documentation/snippets/ -name '*.ly' | xargs convert-ly -e --from "X.Y.Z"

   Finally, for the regression tests, do:

     find input/regression/ -name '*.ly' | xargs convert-ly -e --from "X.Y.Z"

8.7.5 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 "% 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:

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

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

   Update the snippet files by running:

     scripts\auxiliar\makelsr.py

   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.

8.7.6 Write NEWS entry
----------------------

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

   Hints for NEWS file entries are given at the top of the NEWS file.

   New entries in NEWS go at the top of the file.

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

8.7.7 Verify successful build
-----------------------------

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

     make all
     make doc

   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.

8.7.8 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 *note
Regression tests::.

8.7.9 Post patch for comments
-----------------------------

For any change other than a minor change, a patch set should be posted
on Rietveld for comment.  This requires the use of an external package,
git-cl.

   git-cl is installed by:

     git clone git://neugierig.org/git-cl.git

   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 will is then configured by

     git-cl config

and answering the questions that are asked.

   The patch set is posted by issuing the following command, after
first committing all changes:

     git-cl upload <reference SHA1 ID>

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).

   After prompting for an email and a password, the patch set will be
posted to Rietveld.

   An email should then be sent 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.

8.7.10 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.

8.7.11 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 `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
`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.

9 Release work
**************

9.1 Development phases
======================

There are 2.5 states of development for LilyPond.

   * *Stable phase*: Starting from the release of a new major version
     `2.x.0', the following patches *MAY NOT* be merged with master:

        * Any change to the input syntax.  If a file compiled with a
          previous `2.x' version, then it must compile in the new
          version.

        * New features with new syntax _may be committed_, although
          once committed that syntax cannot change during the remainder
          of the stable phase.

        * Any change to the build dependencies (including programming
          libraries, documentation process programs, or python modules
          used in the buildscripts).  If a contributor could compile a
          previous lilypond `2.x', then he must be able to compile the
          new version.


   * *Development phase*: Any commits are fine.  Readers may be
     familiar with the term "merge window" from following Linux kernel
     news.

   * *Release prep phase*: FIXME: I don't like that name.

     A new git branch `stable/2.x' is created, and a major release is
     made in two weeks.

        * `stable/2.x branch': Only translation updates and important
          bugfixes are allows.

        * `master': Normal "stable phase" development occurs.


     If we discover the need to change the syntax or build system, we
     will apply it and re-start the release prep phase.


   This marks a radical change from previous practice in LilyPond.
However, this setup is not intended to slow development - as a rule of
thumb, the next development phase will start within a month of somebody
wanting to commit something which is not permitted during the stable
phase.

9.2 Minor release checklist
===========================

A "minor release" means an update of `y' in `2.x.y'.

   email brief summary to info-lilypond

9.3 Major release checklist
===========================

A "major release" means an update of `x' in `2.x.0'.

   Before release:

   * write release notes. note: stringent size requirements for
various websites, so be brief.

   * write preface section for manual.

   * submit pots for translation : send url of tarball to
translation@iro.umontreal.ca, mentioning lilypond-VERSION.pot

   * Check reg test

   * Check all 2ly scripts.

   * Run convert-ly on all files, bump parser minimum version.

   * Make FTP directories on lilypond.org

   * website:   - Make new table in download.html

   - add to documentation list

   - revise examples tour.html/howto.html

   - add to front-page quick links

   - change all links to the stable documentation

   - doc auto redirects  to v2.LATEST-STABLE

   News:

   comp.music.research         comp.os.linux.announce

   comp.text.tex         rec.music.compose

   Mail:

   info-lilypond@gnu.org

   linux-audio-announce@lists.linuxaudio.org
linux-audio-user@lists.linuxaudio.org
linux-audio-dev@lists.linuxaudio.org

   tex-music@icking-music-archive.org

   -- non-existant?          abcusers@blackmill.net

   rosegarden-user@lists.sourceforge.net         info-gnu@gnu.org
 noteedit-user@berlios.de

   gmane.comp.audio.fomus.devel         gmane.linux.audio.users
gmane.linux.audio.announce         gmane.comp.audio.rosegarden.devel

   Web:

   lilypond.org         freshmeat.net         linuxfr.com
http://www.apple.com/downloads         harmony-central.com
(news@harmony-central.com)         versiontracker.com [auto]
hitsquad.com [auto]         http://www.svgx.org

9.4 Making a release
====================

Technical notes
---------------

To build GUB:

   * Run the following (from the gub/ dir):

          make -f lilypond.make update-versions

   * If you do not have the previous release test-output tarball,
     download it and put it in `uploads/'

   * Run:

          make lilypond


   To upload:

   * Remove the "t" from the rsync command in
     test-lily/rsync-lily-doc.py

   * run:

          python test-lily/upload.py --branch=master --url git://git.sv.gnu.org/lilypond.git --execute


Policy notes
------------

   * Build with GUB, and if it's a stable release, check the regtests.

   * Upload the tarballs and sh scripts.

   * (if major) Branch MASTER to stable/2.x.

   * Make announcement.


Appendix A GNU Free Documentation License
*****************************************

                        Version 1.1, March 2000

     Copyright (C) 2000 Free Software Foundation, Inc.
     51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     written document "free" in the sense of freedom: to assure everyone
     the effective freedom to copy and redistribute it, with or without
     modifying it, either commercially or noncommercially.  Secondarily,
     this License preserves for the author and publisher a way to get
     credit for their work, while not being considered responsible for
     modifications made by others.

     This License is a kind of `copyleft', which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.
     We recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work that contains a
     notice placed by the copyright holder saying it can be distributed
     under the terms of this License.  The `Document', below, refers to
     any such manual or work.  Any member of the public is a licensee,
     and is addressed as `you'.

     A `Modified Version' of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A `Secondary Section' is a named appendix or a front-matter
     section of the Document that deals exclusively with the
     relationship of the publishers or authors of the Document to the
     Document's overall subject (or to related matters) and contains
     nothing that could fall directly within that overall subject.
     (For example, if the Document is in part a textbook of
     mathematics, a Secondary Section may not explain any mathematics.)
     The relationship could be a matter of historical connection with
     the subject or with related matters, or of legal, commercial,
     philosophical, ethical or political position regarding them.

     The `Invariant Sections' are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in
     the notice that says that the Document is released under this
     License.

     The `Cover Texts' are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.

     A `Transparent' copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, whose contents can be viewed and edited directly
     and straightforwardly with generic text editors or (for images
     composed of pixels) generic paint programs or (for drawings) some
     widely available drawing editor, and that is suitable for input to
     text formatters or for automatic translation to a variety of
     formats suitable for input to text formatters.  A copy made in an
     otherwise Transparent file format whose markup has been designed
     to thwart or discourage subsequent modification by readers is not
     Transparent.  A copy that is not `Transparent' is called `Opaque'.

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and
     standard-conforming simple HTML designed for human modification.
     Opaque formats include PostScript, PDF, proprietary formats that
     can be read and edited only by proprietary word processors, SGML
     or XML for which the DTD and/or processing tools are not generally
     available, and the machine-generated HTML produced by some word
     processors for output purposes only.

     The `Title Page' means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, `Title
     Page' means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow
     the conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies of the Document numbering more than
     100, and the Document's license notice requires Cover Texts, you
     must enclose the copies in covers that carry, clearly and legibly,
     all these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the
     title equally prominent and visible.  You may add other material
     on the covers in addition.  Copying with changes limited to the
     covers, as long as they preserve the title of the Document and
     satisfy these conditions, can be treated as verbatim copying in
     other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a
     machine-readable Transparent copy along with each Opaque copy, or
     state in or with each Opaque copy a publicly-accessible
     computer-network location containing a complete Transparent copy
     of the Document, free of added material, which the general
     network-using public has access to download anonymously at no
     charge using public-standard network protocols.  If you use the
     latter option, you must take reasonably prudent steps, when you
     begin distribution of Opaque copies in quantity, to ensure that
     this Transparent copy will remain thus accessible at the stated
     location until at least one year after the last time you
     distribute an Opaque copy (directly or through your agents or
     retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of
     copies, to give them a chance to provide you with an updated
     version of the Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with
     the Modified Version filling the role of the Document, thus
     licensing distribution and modification of the Modified Version to
     whoever possesses a copy of it.  In addition, you must do these
     things in the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of
          previous versions (which should, if there were any, be listed
          in the History section of the Document).  You may use the
          same title as a previous version if the original publisher of
          that version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has less than five).

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document's
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section entitled `History', and its title, and
          add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on
          the Title Page.  If there is no section entitled `History' in
          the Document, create one stating the title, year, authors,
          and publisher of the Document as given on its Title Page,
          then add an item describing the Modified Version as stated in
          the previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in
          the `History' section.  You may omit a network location for a
          work that was published at least four years before the
          Document itself, or if the original publisher of the version
          it refers to gives permission.

       K. In any section entitled `Acknowledgments' or `Dedications',
          preserve the section's title, and preserve in the section all
          the substance and tone of each of the contributor
          acknowledgments and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document,
          unaltered in their text and in their titles.  Section numbers
          or the equivalent are not considered part of the section
          titles.

       M. Delete any section entitled `Endorsements'.  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section as `Endorsements' or to
          conflict in title with any Invariant Section.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option
     designate some or all of these sections as invariant.  To do this,
     add their titles to the list of Invariant Sections in the Modified
     Version's license notice.  These titles must be distinct from any
     other section titles.

     You may add a section entitled `Endorsements', provided it contains
     nothing but endorsements of your Modified Version by various
     parties--for example, statements of peer review or that the text
     has been approved by an organization as the authoritative
     definition of a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end
     of the list of Cover Texts in the Modified Version.  Only one
     passage of Front-Cover Text and one of Back-Cover Text may be
     added by (or through arrangements made by) any one entity.  If the
     Document already includes a cover text for the same cover,
     previously added by you or by arrangement made by the same entity
     you are acting on behalf of, you may not add another; but you may
     replace the old one, on explicit permission from the previous
     publisher that added the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination
     all of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections entitled
     `History' in the various original documents, forming one section
     entitled `History'; likewise combine any sections entitled
     `Acknowledgments', and any sections entitled `Dedications'.  You
     must delete all sections entitled `Endorsements.'

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the
     documents in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow
     this License in all other respects regarding verbatim copying of
     that document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of
     a storage or distribution medium, does not as a whole count as a
     Modified Version of the Document, provided no compilation
     copyright is claimed for the compilation.  Such a compilation is
     called an `aggregate', and this License does not apply to the
     other self-contained works thus compiled with the Document, on
     account of their being thus compiled, if they are not themselves
     derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one
     quarter of the entire aggregate, the Document's Cover Texts may be
     placed on covers that surround only the Document within the
     aggregate.  Otherwise they must appear on covers around the whole
     aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License provided that you also include the
     original English version of this License.  In case of a
     disagreement between the translation and the original English
     version of this License, the original English version will prevail.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided for under this License.  Any other
     attempt to copy, modify, sublicense or distribute the Document is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

 10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     `http://www.gnu.org/copyleft/'.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License `or any later version' applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If
     the Document does not specify a version number of this License,
     you may choose any version ever published (not as a draft) by the
     Free Software Foundation.

ADDENDUM: How to use this License for your documents
----------------------------------------------------

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

       Copyright (C)  YEAR  YOUR NAME.
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.1
       or any later version published by the Free Software Foundation;
       with the Invariant Sections being LIST THEIR TITLES, with the
       Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
       A copy of the license is included in the section entitled `GNU
       Free Documentation License'.

   If you have no Invariant Sections, write `with no Invariant Sections'
instead of saying which ones are invariant.  If you have no Front-Cover
Texts, write `no Front-Cover Texts' instead of `Front-Cover Texts being
LIST'; likewise for Back-Cover Texts.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.



Local Variables:
coding: utf-8
End:
